Unity GitHub Actions

Validate Unity Scenes and Prefabs with GitHub Actions

A practical GitHub Actions workflow for checking Unity scenes and prefabs before a pull request is merged.

Use three validation layers

Use three layers: conflict-marker scan, semantic checks, and Unity validation. Upload diagnostic artifacts whenever a gate fails.

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.

Try MergeSight

Review the Unity change, not the YAML noise

Run MergeSight in GitHub Actions to validate Unity asset changes and upload readable reports when a check fails.

Get it on the Asset Store See how MergeSight works