Unity GitHub Actions

Validate Unity Scenes and Prefabs with GitHub Actions

A useful GitHub Actions pipeline validates Unity assets in layers: a fast conflict-marker scan on every pull request, semantic checks when complete merge inputs exist, and Unity batchmode import or project validation on a trusted runner. Publish artifacts even when a gate fails so reviewers can diagnose the asset.

Use three validation layers

Run a marker scan on every asset pull request

name: Unity Asset Guard

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

jobs:
  conflict-markers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Reject unresolved Unity conflict markers
        shell: bash
        run: |
          if git grep -n \
            -e '^<<<<<<< ' \
            -e '^=======$' \
            -e '^>>>>>>> ' -- \
            'Assets/*.unity' 'Assets/*.prefab' \
            'Assets/*.asset' 'Assets/*.mat'; then
            echo "Unresolved merge markers found." >&2
            exit 1
          fi

This layer is cheap and objective. It does not prove that the asset is structurally correct.

Run semantic checks with real merge inputs

MergeSight GitHub Actions merge validation can run through the standalone .NET CLI or Unity-hosted headless wrapper. Commands such as inspect, check, validate-plan, and preview produce JSON, Markdown, validation, and preview artifacts for explicit Base / Ours / Theirs inputs.

Add Unity batchmode validation

Use a self-hosted runner when the check needs the project's Unity version, AssetDatabase import, scene loading, or Editor tests. A packaged MergeSight template uses a repository variable for the Unity executable and uploads artifacts even when the semantic check fails:

jobs:
  unity-assets:
    runs-on: [self-hosted, macOS]
    env:
      UNITY_EXE: ${{ vars.MERGESIGHT_UNITY_EXE }}
      REPORT_DIR: artifacts/unity-assets
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run MergeSight headless check
        continue-on-error: true
        id: asset_check
        run: |
          Scripts/run_headless_merge_ci_check.sh \
            --unity-exe "$UNITY_EXE" \
            --out "$REPORT_DIR"
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: unity-asset-report
          path: ${{ env.REPORT_DIR }}
      - name: Enforce result
        if: steps.asset_check.outcome == 'failure'
        run: exit 1

Adapt paths to the packaged tooling. If the repository accepts pull requests from untrusted forks, do not expose a privileged self-hosted runner to arbitrary contributor code.

Define what blocks the pull request

• Unresolved conflict markers.
• Asset parsing or Unity import failure.
• Unresolved required semantic merge decisions.
• Missing scripts or dangling references introduced by the branch.
• Invalid hierarchy or component ownership.
• Failure of project-specific EditMode, PlayMode, scene, or build checks.

Keep subjective design warnings non-blocking until the team has a reliable, reviewed rule.

Always upload diagnostic artifacts

Useful outputs include summary.md, merge-model.json, validation-result.json, decision-plan.json, preview.yaml, and result diff reports. Upload them with if: always() before the final enforcement step.

Roll out safely

1. Start with marker checks and reports only.
2. Run semantic or Unity checks in non-blocking mode and measure false positives.
3. Promote objective failures to required checks.
4. Keep deep full-project validation on merge queues, nightly jobs, or release branches if PR latency becomes too high.
5. Version the validation policy with the project.

FAQ

Can GitHub Actions validate Unity scene files?

Yes. It can scan serialized text, run semantic tools, invoke Unity batchmode on a suitable runner, execute project tests, and upload reports. Each layer catches different failures.

Do GitHub-hosted runners include Unity?

Do not assume so. Use an approved Unity setup action or a self-hosted runner with the required Editor version and license configuration when the job must run Unity.

Can MergeSight check all changed PR assets with --assets conflicted?

No. That mode reads actual unmerged Git stages. A normal PR checkout usually has none; use explicit merge inputs, a materialized merge job, or separate branch-level review and Unity validation.

Should a failed Unity asset job still upload artifacts?

Yes. Capture the check outcome, upload reports with if: always(), then fail the job in a final enforcement step.

Summary

Guard every PR

Run fast marker and basic text checks on any hosted runner.

Preserve real context

Semantic merge checks need complete sides or a genuine conflicted index.

Validate in Unity

Use a trusted runner for import, Editor APIs, tests, and project-specific behavior.

The pipeline is trustworthy when each check states what evidence it has and does not pretend a clean checkout contains a 3-way conflict.

Next step

Add a focused structural gate with missing script and broken reference checks.