> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantiva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CI Integration

> Run visual regression tests in GitHub Actions and other CI systems

## GitHub Actions

```yaml theme={null}
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: Run visual regression tests
        env:
          GRANTIVA_API_KEY: ${{ secrets.GRANTIVA_API_KEY }}
        run: grantiva ci run
```

The CLI automatically posts results as a GitHub Check Run on the pull request.

## Environment variables

| Variable           | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `GRANTIVA_API_KEY` | API key for authentication (required in CI)            |
| `GRANTIVA_API_URL` | Base URL override (default: `https://api.grantiva.io`) |

## 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, enabling faster and more flexible CI pipelines.

```bash theme={null}
# 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 automatically extracted (`.app` from `Payload/`)
* `scheme` is not required in `grantiva.yml`

### Split build and test

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

```yaml theme={null}
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
```

Benefits:

* Build and test can be separate jobs (even separate machines)
* Build artifacts can be cached and reused across multiple test runs
* Visual regression doesn't re-build when only baselines changed
* Multiple Grantiva configs (different screen sizes, locales) can run in parallel against the same binary

## JSON output for scripting

```bash theme={null}
grantiva ci run --json | jq '.failed_count'
```

Exit code is `0` if all screens pass, `1` if any fail — works with CI `if` conditions.

## Approving new baselines

When UI changes are intentional, approve the new screenshots:

```bash theme={null}
grantiva diff approve
```

Or approve specific screens:

```bash theme={null}
grantiva diff approve "Home" "Settings"
```

Approved captures become the new baselines for future comparisons.

## Results

After each run, the CLI outputs:

* Run ID and dashboard URL
* Screen-by-screen pass/fail status
* Pixel diff percentage and perceptual distance per screen
* Total duration

Results are also visible in the Grantiva dashboard under your project.