Unity Review Automation

Generate Semantic Unity Asset Diff Reports for Pull Requests

A guide to producing reviewer-friendly Unity asset reports for pull requests and machine-readable evidence for automation.

Alexandr Rice Follow on X Updated August 27, 2026 4 min read CI and Automation

What the report should contain

A semantic Unity asset report should summarize changed files, then explain each scene, prefab, material, or data asset in Unity terms: objects, components, hierarchy, properties, overrides, references, and validation findings. Publish Markdown for reviewers and JSON for automation.

Comparison identity: base and head commits or VCS revisions.
Changed asset inventory: path, asset type, change status, and risk.
Semantic summary: added, removed, modified, moved, reordered, and override changes.
Reference context: resolved GUIDs, fileIDs, source prefabs, materials, scripts, and data assets.
Validation: errors, warnings, unresolved decisions, and tool limits.
Artifact links: raw JSON, Markdown, preview, and relevant logs.

Design the Markdown for scanning

# Unity Asset Review

- Base: 2a41...
- Head: 78bd...
- Assets changed: 4
- Blocking issues: 1

## Assets/Scenes/World.unity
- Added: SpawnPoint_B
- Reparented: Lighting/ReflectionProbe
- Modified: MainCamera/Camera.m_FieldOfView
- Reference: EncounterConfig -> Assets/Data/Act2.asset
- Validation: pass

## Assets/Prefabs/Enemy.prefab
- Missing script: Enemy/Combat
- Validation: blocking

Lead with counts and blocking issues. Keep raw YAML out of the summary unless a reviewer opens a detailed artifact.

Design stable JSON for automation

{
  "schemaVersion": 1,
  "base": "2a41...",
  "head": "78bd...",
  "assets": [
    {
      "path": "Assets/Scenes/World.unity",
      "type": "Scene",
      "risk": "medium",
      "changes": [],
      "validation": []
    }
  ]
}

Version the schema. Use stable change kinds and target identities so later tools can aggregate results without parsing human prose.

Generate reports from semantic review

MergeSight Markdown and JSON Unity diff reports can export Review Mode summaries for working-tree, branch, commit, and supported VCS sources. Merge CLI workflows can also emit merge-model.json, validation-result.json, summary.md, preview, and result-diff artifacts for explicit 3-way inputs.

Use branch/commit review exports for normal pull requests. Use 3-way merge artifacts only when the workflow actually has Base / Ours / Theirs.

Pull-request reporting workflow

Resolve the PR merge base and head commit.
List changed supported Unity assets and related meta/dependency files.
Load exact source content and build semantic changes.
Run validation appropriate to available context.
Render Markdown and JSON from the same structured model.
Upload immutable artifacts named with commit identities.
Post or link a concise summary without overwriting reviewer discussion.
Regenerate when the head commit changes.

Assign risk without pretending to know design intent

Signal	Example risk
Scalar property change	Low unless the property is project-critical.
Reference or script identity change	Medium to high; resolve the target.
Hierarchy reparent/reorder	Medium; review layout and ownership.
Delete-versus-edit or unresolved decision	Blocking in a merge context.
Missing script, dangling reference, invalid hierarchy	Blocking structural error.

Let project policy raise or lower severity for known asset paths. Keep the underlying semantic fact separate from the policy decision.

Report limitations explicitly

Which asset types were parsed and which were skipped.
Whether Unity import validation ran.
Whether the comparison was two-source or 3-way.
Whether references were resolved project-wide or only locally.
Whether generated data and binary assets were excluded.
Whether the report describes structure but not visual or gameplay correctness.

FAQ

What is a semantic Unity asset diff report?

It converts serialized scene, prefab, material, and data changes into Unity concepts such as objects, components, hierarchy, properties, overrides, references, and validation results.

Should a Unity pull request report use Markdown or JSON?

Use both. Markdown is optimized for human review, while versioned JSON supports CI policy, dashboards, and later automation.

Can MergeSight export Unity asset diff reports?

Yes. Review Mode supports Markdown and JSON export, and merge CLI workflows emit structured merge, validation, preview, and summary artifacts.

Does a semantic report replace opening the scene in Unity?

No. It improves review and catches structural risks, but visible, imported, runtime, and project-specific behavior still requires Unity validation.

Try MergeSight

Review the Unity change, not the YAML noise

Generate MergeSight Markdown for reviewers and JSON for automation from the same semantic Unity asset comparison.

Get it on the Asset Store See how MergeSight works