Unity CI Kit

Unity CI pipeline toolkit. Provides ci_agent.py Python CLI and CiRunner.cs Unity Editor script for fully automated Unity batchmode builds, compile checks, and structured error parsing. Use this skill to set up automated CI for Unity projects, run batchmode compilation, create reusable build pipelines, or migrate existing CI scripts to a config-driven cross-project framework.

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<bool> action) helper:

csharp

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

bash

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:

json

{
  "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

text

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.