Unity CI Validation

Detect Missing Scripts and Broken References in CI

Reliable Unity reference validation needs two layers. A semantic file check can detect missing script patterns, unresolved GUID/fileID targets, hierarchy, and ownership problems in serialized assets. A Unity-hosted check confirms import state and uses project context to catch failures that raw files cannot prove.

Define the failures precisely

Run a repository-aware semantic layer

A correct GUID check should parse meta files and serialized references rather than search arbitrary 32-character strings. Build an index from tracked .meta files, parse supported Unity assets, and report each unresolved reference with asset path, object context, property path, GUID, and fileID.

For local references, validate that the target fileID exists in the same serialized asset. For components, validate their owning GameObject. For Transform hierarchy, detect missing parents and cycles.

MergeSight missing-script and reference validation includes checks for dangling references, missing scripts, hierarchy integrity, component ownership, duplicate sibling names, and circular references in supported semantic merge contexts. Its CLI emits machine-readable validation artifacts and fails closed on invalid or unsupported state.

Confirm with Unity project context

Some questions require the AssetDatabase, imported types, scripts, packages, or custom serialization code. Run Unity batchmode on the documented project version and:

• Import all changed assets and fail on serialization errors.
• Open changed scenes additively or through a validation harness.
• Load prefab contents and inspect missing MonoBehaviours.
• Resolve object fields and project-specific required references.
• Run EditMode tests for data migration and asset invariants.
• Save no production assets unless the job is explicitly a migration workflow.

Scope pull-request checks to changed assets and dependents

Start with changed .unity, .prefab, .asset, .mat, script, and .meta files. Expand the validation set when identity or type changes can affect dependents:

• A changed or deleted meta GUID requires a project-wide reference lookup.
• A script rename, namespace change, assembly move, or meta replacement can affect every serialized component.
• A source prefab change requires validation of representative instances and dependent prefabs.
• A shader property change can affect many materials.

Define blocking and warning policy

• Block: missing scripts introduced by the branch, unresolved required references, invalid hierarchy, parse/import failure.
• Warn: duplicate sibling names, optional references, known legacy debt outside the changed scope.
• Baseline: record pre-existing debt so a new check blocks regressions without requiring an immediate full cleanup.

Every result needs a stable asset path, object identity, property path, severity, and suggested next investigation step.

Publish useful CI evidence

{
  "assetPath": "Assets/Prefabs/Enemy.prefab",
  "severity": "error",
  "kind": "MissingScript",
  "objectPath": "Enemy/Combat",
  "propertyPath": "m_Script",
  "guid": "missing-guid",
  "message": "Script reference does not resolve."
}

Provide JSON for automation and a Markdown summary for humans. Upload both before failing the job.

Avoid weak checks

• Do not treat m_Script: {fileID: 0} as the only missing-script representation.
• Do not assume every GUID-looking scalar is an asset reference.
• Do not validate only the working tree when CI checks a different commit.
• Do not make a full-project Unity import mandatory on every small PR without measuring latency.
• Do not silently repair production assets inside a validation job.

FAQ

Can CI detect missing scripts in Unity prefabs and scenes?

Yes. A semantic check can resolve script GUIDs, and a Unity-hosted check can import assets and inspect missing MonoBehaviours with project context.

How can CI detect broken Unity references?

Parse meta GUIDs and serialized asset references, validate local fileIDs and hierarchy, then confirm ambiguous or imported relationships in Unity batchmode.

Should reference checks scan the whole Unity project?

Use changed assets for routine PR speed, but expand to dependents or a project-wide lookup when a meta GUID, script identity, source prefab, or shader contract changes.

Can MergeSight validate missing scripts without Unity?

Its semantic engine can report missing-script and reference problems in supported serialized contexts. Unity-hosted validation is still needed for import and project-specific behavior.

Summary

Parse identities

Build real GUID and fileID relationships instead of relying on broad regular expressions.

Add Unity context

Import and Editor checks confirm scripts, prefabs, scenes, packages, and custom invariants.

Report actionable paths

Every failure should name the asset, object, property, identity, and severity.

Reference validation becomes trustworthy when file-level evidence and Unity project context agree.

Next step

Attach the results to reviews with semantic Unity asset diff reports.