Command line and CI/CD

RefSafe Pro exposes a batchmode entry point so validation can run in CI and fail a build before broken references reach a store submission.

Batchmode command

Unity -batchmode -nographics -quit \
      -projectPath "$PROJECT_PATH" \
      -executeMethod RefSafe.Pro.CliRunner.RunScan \
      --scope EntireProject \
      --format json \
      --output report.json \
      --fail-threshold Warning

Arguments

Flag	Values	Default
--scope	OpenScenes, AllScenes, AllPrefabs, AllScriptableObjects, EntireProject, ChangedOnly	EntireProject
--format	Any registered exporter id — csv, json, html, txt, markdown, github, gitlab, plus your own	json
--output	Output file path	none
--fail-threshold	Critical, Warning, Info	Critical

--format resolves through the exporter registry, so a custom exporter works on the CLI with no extra wiring — its [ReportExporter] id is the CLI id.

Exit codes

Code	Meaning
0	No issues at or above the fail threshold
1	Issues found at or above the fail threshold
2	Scan error — details in the Unity log

Treat 2 differently from 1 in CI. 1 means the project has problems; 2 means the scan itself failed and you learned nothing about the project.

Choosing a threshold

--fail-threshold Critical fails only on genuinely broken things — missing scripts, missing prefab sources, deleted build scenes. Good starting point for adding validation to an existing project with a backlog.

--fail-threshold Warning also fails on broken UnityEvents, missing references, and invalid layers. This is where most teams end up once the backlog is cleared.

--fail-threshold Info fails on essentially anything. Rarely practical.

Introducing validation to a project with existing issues is easier at Critical first, then tightening to Warning once the Critical count holds at zero.

GitHub Actions

name: Validate Unity project

on: [pull_request]

jobs:
  refsafe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: game-ci/unity-builder@v4
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        with:
          projectPath: .
          buildMethod: RefSafe.Pro.CliRunner.RunScan
          customParameters: --scope EntireProject --format github --fail-threshold Warning

With --format github, each issue becomes an inline annotation on the pull request diff, so reviewers see broken references on the affected lines instead of reading job logs.

GitLab CI

refsafe:
  image: unityci/editor:2022.3.62f2-base-3
  script:
    - unity-editor
        -batchmode -nographics -quit
        -projectPath .
        -executeMethod RefSafe.Pro.CliRunner.RunScan
        --scope EntireProject
        --format gitlab
        --output gl-code-quality-report.json
        --fail-threshold Warning
  artifacts:
    reports:
      codequality: gl-code-quality-report.json

Issues then appear in the merge request quality widget.

Pre-build validation hook

For local builds, enable Validate Before Build in Settings with a Build Fail Threshold. Every build then runs a scan first and aborts if the threshold is met — the same protection as CI, without waiting for a push.

Keeping CI runs fast

A full EntireProject scan is thorough but not free. Two practical approaches:

Scope by trigger. EntireProject nightly and on release branches; ChangedOnly on pull requests. Note that ChangedOnly relies on RefSafe’s incremental tracker, which is per-machine state — on an ephemeral CI runner with a clean checkout there’s no prior scan to diff against, so it behaves like a full scan. It’s a local-loop optimization, not a CI one.

Scope by asset type. If prefabs are where your breakage lives, --scope AllPrefabs on pull requests catches most of it in a fraction of the time.

Generating the command from Settings

The Settings panel renders a live CI command preview matching your current scope, format, and threshold. Copy from there rather than assembling flags by hand.