CI integration

GitHub Actions

name: Visual Regression
on: pull_request

jobs:
  vrt:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4

      - name: Install Grantiva CLI
        run: brew install grantiva/tap/grantiva

      - name: Preflight
        run: grantiva doctor

      - name: Run visual regression tests
        env:
          GRANTIVA_API_KEY: ${{ secrets.GRANTIVA_API_KEY }}
        run: grantiva ci run

actions/checkout matters here: grantiva ci run derives the project slug from the origin git remote (owner/repo) and the branch from GITHUB_HEAD_REF or GITHUB_REF_NAME, falling back to git rev-parse. Without the checkout there is no remote to read. grantiva doctor exits non-zero when a required check fails — Xcode missing, an unreadable toolchain — and stays quiet about the optional ones, so it is safe as a preflight step. Results are posted as a GitHub Check Run when the GitHub App is configured for your organization.

Environment variables

Variable	Default	Description
`GRANTIVA_API_KEY`	—	API key. Takes precedence over `~/.grantiva/auth.json`, so nothing has to be written to disk on a runner.
`GRANTIVA_API_URL`	`https://api.grantiva.io`	API base URL override.
`GRANTIVA_SESSION_ID`	—	Ticket identifier that owns the simulators booted under it, so several commands share one durable owner.
`GRANTIVA_MAX_SIMULATORS`	`4`	Maximum Grantiva-booted simulators on this host.
`GRANTIVA_SIMULATOR_WAIT_TIMEOUT_SECONDS`	`600`	How long a boot waits for a free simulator slot.
`NO_COLOR`	—	Suppress colour. Colour is already suppressed when stdout is not a terminal.

Output and exit codes

0 if every screen passes, 1 if any fails. The results are uploaded either way — a visual regression is a verdict, not a crash. Progress narration goes to stderr and results go to stdout, so a pipeline can parse the result without filtering:

grantiva ci run --json | jq '.failed_count'

{
  "run_id": "0d0a0c9e-2f1b-4c0c-9a8b-7d5e3f1a2b4c",
  "status": "completed",
  "url": "https://grantiva.io/dashboard/vrt/runs/0d0a0c9e",
  "branch": "feature/dark-mode",
  "commit_sha": "9f2b1c4",
  "trigger": "ci",
  "screen_count": 12,
  "passed_count": 10,
  "failed_count": 1,
  "new_count": 1,
  "duration": 84.2
}

Add --verbose when a job fails for a reason the summary does not explain: it logs every subprocess Grantiva runs — the exact xcodebuild and simctl invocations — and their exit status.

Pre-built binaries

Grantiva can consume pre-built .app bundles or .ipa archives instead of building from source. This decouples the build from the test.

# Use a pre-built .app bundle (skips xcodebuild, still installs)
grantiva ci run --app-file ./build/MyApp.app

# Use an .ipa from a CI artifact
grantiva ci run --app-file ./artifacts/MyApp.ipa

# App is already installed on the simulator (skip build and install)
grantiva ci run --no-build

When --app-file is provided:

The xcodebuild step is skipped entirely
The binary is validated to be a simulator build, not a device build
The bundle ID is derived from the binary’s Info.plist if not specified
.ipa files are extracted automatically (the .app from Payload/)
scheme is not required in grantiva.yml

Split build and test

Separate the build and the test into different jobs. That lets you cache build artifacts, reuse them across test runs, and run visual regression on several device configurations in parallel.

jobs:
  build:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: |
          xcodebuild build -scheme MyApp \
            -destination 'generic/platform=iOS Simulator' \
            -derivedDataPath build/
      - uses: actions/upload-artifact@v4
        with:
          name: app-binary
          path: build/Build/Products/Debug-iphonesimulator/MyApp.app

  visual-regression:
    needs: build
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: app-binary
          path: ./app
      - name: Install Grantiva CLI
        run: brew install grantiva/tap/grantiva
      - name: Visual regression
        env:
          GRANTIVA_API_KEY: ${{ secrets.GRANTIVA_API_KEY }}
        run: grantiva ci run --app-file ./app/MyApp.app

Use --derived-data-path to isolate Xcode products per job when you do build inside the test job — it overrides any -derivedDataPath in build_settings.

Functional flows in CI

grantiva run needs no authentication, so it works in pipelines that do not use visual regression at all.

grantiva run --app-file ./app/MyApp.app \
  --report-dir "$RUNNER_TEMP/grantiva-report" \
  --timeout 1200 \
  --env API_BASE_URL=https://staging.example.com

Flag	Why it matters in CI
`--report-dir`	Writes `report.json`, assets, and failure screenshots somewhere your job can upload them. Without it they go to an ephemeral temp directory.
`--timeout`	Kills the runner subprocess after N seconds. Default 600; raise it for long multi-flow suites.
`--env KEY=VALUE`	Passes an ephemeral port or test fixture into the app under test. Repeatable.
`--snapshot trailing`	Captures the last-good step alongside the failing one, which is usually what you need to diagnose from a log.
`--continue-on-failure`	Runs the whole suite instead of stopping at the first broken flow. The default is fail-fast.

Upload the report directory as an artifact on failure:

      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: grantiva-report
          path: ${{ runner.temp }}/grantiva-report

Backgrounded runs

With --keep-alive the session outlives the flows, so process exit is not a completion signal. Wait on --ready-file instead:

grantiva run --flow flows/onboarding.yaml --keep-alive \
  --ready-file "$RUNNER_TEMP/onboarding.ready" &

while [ ! -f "$RUNNER_TEMP/onboarding.ready" ]; do sleep 0.2; done
status=$(jq -r .status "$RUNNER_TEMP/onboarding.ready")   # passed | failed | interrupted

grantiva hierarchy > "$RUNNER_TEMP/final-state.xml"
[ "$status" = passed ]

The file is deleted at startup and always written, including on a setup failure that never reaches the runner — so that loop, which has no timeout of its own, cannot wedge the job.

Parallel runs on one machine

Runs on different simulator UDIDs execute in parallel. At most four Grantiva-booted simulators are admitted at once; a fifth boot waits up to ten minutes and then fails, naming the sessions holding capacity.

export GRANTIVA_SESSION_ID="$GITHUB_RUN_ID"

udid=$(grantiva simulator ensure --name "CI $GITHUB_RUN_ID iPhone 17")
grantiva ci run --simulator "$udid"

grantiva simulator teardown --session-id "$GITHUB_RUN_ID"

On a self-hosted runner, end the job with grantiva simulator cleanup to delete Grantiva-created simulators that are shut down and no longer in an active session. See Simulator management for capacity limits, leases, and reclaiming a device a killed job left behind.

Approving new baselines

When UI changes are intentional, approve the new screenshots locally:

grantiva diff approve             # all screens
grantiva diff approve Home Settings

From a pipeline, review the uploaded run instead:

run_id=$(grantiva ci run --json | jq -r .run_id)
grantiva console vrt screen accept acme/my-app "$run_id" Home Settings
grantiva console vrt approve acme/my-app "$run_id"

See VRT review for the full review loop.

Results

grantiva ci run prints a run summary: the run ID and status, the branch and commit, the trigger, the screen counts (total, passed, failed, new), the duration, and the dashboard URL. Per-screen detail — status, pixel diff percentage, perceptual distance, and the diff image path — lives in the dashboard, and locally in grantiva diff compare.

Getting Started

SDKs

CLI

Concepts

Push

Dashboard

GitHub Actions

Environment variables

Output and exit codes

Pre-built binaries

Split build and test

Functional flows in CI

Backgrounded runs

Parallel runs on one machine

Approving new baselines

Results

​GitHub Actions

​Environment variables

​Output and exit codes

​Pre-built binaries

​Split build and test

​Functional flows in CI

​Backgrounded runs

​Parallel runs on one machine

​Approving new baselines

​Results

GitHub Actions

Environment variables

Output and exit codes

Pre-built binaries

Split build and test

Functional flows in CI

Backgrounded runs

Parallel runs on one machine

Approving new baselines

Results