Unity CI Guide

How to Add Unity Asset Merge Checks to CI

A practical guide to adding Unity-aware asset merge validation to CI alongside compilation, tests, and builds.

Alexandr Rice Follow on X Updated August 27, 2026 5 min read CI automation

Why Unity asset merge checks belong in CI

Unity CI usually checks compilation, tests, and builds. Those checks can still miss broken references, missing scripts, unresolved decisions, and unsafe serialized asset state.

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?

CI can validate changed scenes, prefabs, materials, and YAML syntax. It can also block unresolved markers, missing references, missing scripts, and unsafe merge decisions before a PR merges.

Should Unity asset checks run on every PR?

Teams should run lightweight checks on every PR and deeper project-wide validation on scheduled jobs or before release. Changed-asset checks are usually the best default for pull requests.

Do Unity asset merge checks replace play mode tests?

No. Asset merge checks catch structural and reference risks around serialized Unity assets. They complement edit mode, play mode, and build tests.

Try MergeSight

Review the Unity change, not the YAML noise

Use the MergeSight CLI to validate merge plans, preview results, and publish structured Unity asset evidence in CI.

Get it on the Asset Store See how MergeSight works
Related: Unity YAML merge guide · GameCI Unity Actions · Why Unity references break