Unity CI Kit

Unity CI Kit

Purpose

A drop-in CI toolkit for Unity projects that enables fully automated build-test-validate pipelines. The Python agent (ci_agent.py) handles Unity batchmode invocation and result parsing; the C# runner (CiRunner.cs) provides a reusable step framework inside Unity Editor. Together they eliminate the need for manual Unity Editor interaction during development iterations.

When to Use

Trigger this skill when:

• User asks to "set up CI for Unity" or "automate Unity builds"
• User wants to run Unity batchmode compilation from the command line
• User needs to migrate a hardcoded CI script to a reusable, config-driven kit
• User mentions ci_agent.py, ci_config.json, or CiRunner.cs in the context of Unity automation
• User is setting up a new Unity project and wants a proven CI pipeline from day one

Do NOT use this skill for non-Unity projects, or for simple one-off shell scripts that don't need a reusable framework.

Workflow

Step 1: Initialize the Project

Run ci_agent.py init from the Unity project root. This creates ci_config.json with defaults. Edit the config to set:

• unity_version — e.g. "2022.3.62f3c1" (matches ProjectVersion.txt)
• unity_path — leave empty for auto-discovery, or set absolute path
• execute_method — the Unity static method to invoke, e.g. "StarVanguard.Editor.AutoCI.RunCI" or "UnityCI.Editor.CiRunner.RunCI"

Step 2: Install the Unity-side Runner

Copy templates/CiRunner.cs (from this skill's templates/ directory) into the project's Assets/Editor/ (or Assets/_Project/Scripts/Editor/).

Edit the RunPipeline() method to insert project-specific build steps. Each step uses the Step(string name, Func action) helper:

private static bool RunPipeline()
{
    bool ok = true;
    ok &= Step("Create Assets",  () => { AssetBuilder.Run();   return true; });
    ok &= Step("Run Validation", () => { TestRunner.RunAll();   return testsPassed; });
    ok &= Step("Apply Font",     () => { FontSetup.Apply();     return true; });
    AssetDatabase.SaveAssets();
    return ok;
}

The helper automatically wraps each step in try-catch and logs [AutoCI] STEP: name => OK/FAIL. The Python agent parses these log lines to produce structured JSON output.

Step 3: Verify Environment

Run python ci_agent.py check to verify:

• Python version is compatible
• ci_config.json is present and valid
• Unity executable is found at the configured path or auto-discovered
• The project contains an Assets/ directory

Step 4: Run CI

python ci_agent.py build     # Full pipeline (batchmode + executeMethod + parse)
python ci_agent.py compile   # Compile-only (fast check)
python ci_agent.py status    # Read last build result JSON

The build command:

1. Launches Unity in batch mode (-batchmode -quit -nographics)
2. Executes the configured execute_method
3. Reads ci_output.log and parses CS errors/warnings
4. Writes structured JSON to ci_result.json
5. Prints a summary to stdout

Step 5: Integrate with AI Workflow

The structured JSON output from ci_result.json is designed for AI consumption:

{
  "timestamp": "2026-06-30T08:30:00",
  "build_ok": true,
  "errors": [],
  "error_count": 0,
  "warnings": [...],
  "warning_count": 3,
  "ci_pass": true,
  "log_file": "ci_output.log"
}

AI agents can:

1. Write code changes
2. Run python ci_agent.py compile to verify compilation
3. If errors exist, parse ci_result.json → fix → repeat
4. Once clean, run python ci_agent.py build for full validation
5. Commit and push when all passes

File Layout

project-root/
├── ci_config.json          # Created by `ci_agent.py init`
├── ci_output.log           # Generated by Unity batchmode
├── ci_result.json          # Generated by `ci_agent.py build`
├── ci_agent.py             # Copied from skill's scripts/ directory
└── Assets/
    └── Editor/
        └── CiRunner.cs     # Copied from skill's templates/ directory

Bundled Resources

scripts/ci_agent.py

The main Python CLI. Copy this to the project root. Run python ci_agent.py for usage. Commands: init, check, build, compile, status.

templates/ci_config.json

Minimal config template. Fields: unity_version, unity_path, execute_method, timeout_seconds, log_file, result_file.

templates/CiRunner.cs

Generic Unity Editor script. Provides Step() framework and RunCI() entry point. Namespace: UnityCI.Editor. Method: public static void RunCI().

references/setup_guide.md

Step-by-step setup instructions for new projects.