Unity CI Guide

How to Add Unity Asset Merge Checks to CI

Unity CI often focuses on compilation, tests, and builds. That is necessary, but it misses a common failure path: a scene, prefab, material, or YAML asset merge can look fine to Git while still leaving broken references, missing scripts, unresolved decisions, or unsafe serialized state.

Why Unity asset merge checks belong in CI

A Unity pull request can pass code tests and still merge a risky asset change. This happens because many Unity assets are serialized data files. Git sees text, but Unity sees object graphs, hierarchy, prefab instances, component ownership, file IDs, GUIDs, and references.

When those relationships are damaged, the failure may appear later: on a teammate's machine, during QA, while opening a scene, or in a release build. CI is the right place to catch repeatable structural problems before the branch enters main.

What a useful Unity asset check should catch

A good first CI layer should answer practical questions:

• Did this PR change any .unity, .prefab, .asset, or .mat files?
• Do changed text assets contain unresolved Git conflict markers?
• Can changed Unity YAML assets be parsed?
• Do references point at assets and local objects that still exist?
• Did the merge create missing scripts or dangling references?
• Are hierarchy relationships valid, or did a merge create circular or impossible ownership?
• If a merge plan exists, are all required decisions resolved before apply?

A practical CI workflow for Unity asset merges

The simplest workflow has four stages.

1. Detect changed Unity assets. Compare the PR branch with the target branch and collect changed scene, prefab, material, and asset files.
2. Run fast file checks. Fail immediately on conflict markers, invalid text serialization, or missing files referenced by a merge plan.
3. Run semantic checks. Parse changed assets into Unity object structure and validate references, hierarchy, ownership, and unresolved decisions.
4. Publish a readable artifact. Attach JSON or Markdown summaries so reviewers can see what failed without opening the Unity Editor.

This is intentionally conservative. CI should fail when a state is clearly unsafe or unresolved. It should not silently invent design decisions for a human team.

Example GitHub Actions shape

The exact command depends on your tooling, but the job shape should stay simple:

name: Unity Asset Checks

on:
  pull_request:
    paths:
      - "Assets/**/*.unity"
      - "Assets/**/*.prefab"
      - "Assets/**/*.asset"
      - "Assets/**/*.mat"
      - "Assets/**/*.meta"

jobs:
  unity-assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check Unity asset merge state
        run: dotnet path/to/mergesight.dll check --base origin/main --format json --output merge-check.json

This pattern keeps the job scoped to Unity asset changes. In a real project, you would adjust the target branch, CLI path, output format, and artifact upload steps.

What should fail the PR?

Be explicit about failure policy. CI should block the merge on issues that are objective and reproducible:

• Unresolved Git conflict markers in Unity text assets.
• Assets that cannot be parsed as Unity YAML when they should be text-serialized.
• Merge plans with unresolved required decisions.
• Dangling references to missing assets or local objects.
• Missing script references introduced by the PR.
• Invalid hierarchy or component ownership detected after merge preview.

Warnings can remain non-blocking at first. Once the team trusts the signal, promote important warnings to failures.

Where MergeSight CLI fits

MergeSight is designed to make this workflow easier because its CLI can produce machine-readable artifacts around Unity asset review and merge state. Useful commands include:

• inspect for structured summaries of changed assets.
• check for CI-safe validation of Unity text assets and merge state.
• auto-plan to build an explicit merge plan for safe automatic decisions.
• validate-plan to ensure a saved plan has no unresolved required decisions.
• preview to generate merged Unity YAML before writing changes.
• apply to write validated results after preview, backup, and checks.

The important detail is that CI gets structured output. Humans get a readable summary. The build system gets a clear pass/fail signal.

How this complements Unity tests

Unity edit mode and play mode tests are still important. They answer behavioral questions. Asset merge checks answer structural questions before the project even reaches full test execution.

In mature workflows, you use both: asset checks to block obviously unsafe serialized state, tests to catch runtime and gameplay behavior, and builds to verify the project packages correctly.

FAQ

Can CI detect Unity asset merge problems?

Yes, if the check parses changed Unity assets and validates references, conflict markers, missing scripts, hierarchy, ownership, and unresolved merge decisions.

Should Unity asset checks run on every PR?

Lightweight changed-asset checks should run on every PR that touches Unity assets. Deeper full-project scans can run nightly or before release.

Do these checks replace UnityYAMLMerge?

No. UnityYAMLMerge can help create a merged file. CI checks help decide whether the resulting Unity asset state is acceptable.

Do these checks replace play mode tests?

No. They catch different failure classes and should run alongside normal Unity tests and builds.

Summary

What CI sees

Files changed, tests passed, maybe a Unity build completed.

What CI misses

Unsafe YAML asset merges, broken object references, and unresolved semantic decisions.

What to add

Changed-asset validation, conflict checks, semantic summaries, and merge-plan validation.

The goal is not to make CI understand your game design. The goal is to stop clearly unsafe Unity asset states before they land.

Next step

If your team already has Unity builds in CI, add changed-asset checks before the expensive build step. If you need semantic artifacts for review and automation, start with the MergeSight CLI workflow.