Quick start

Before you start

You need a private GitHub repository and an Apple-silicon Mac running macOS 26.

1. Connect GitHub

1. Open Mirage setup and continue with GitHub.
2. Install the GitHub App on a personal account or organization.
3. Select the private repositories Mirage may administer.
4. In Settings, enable the installation and then enable Local Mac for the repository.

GitHub repository access and Mirage routing consent are separate. Newly discovered repositories stay disabled until you opt them in.

2. Pair a Mac

1. Install and open the signed Mirage menu-bar app.
2. Choose the intended GitHub installation in the dashboard.
3. Select Pair Mac and copy the one-use code.
4. Paste the code into the menu-bar app.

3. Route a job

Use an attempt-aware expression. Attempt 1 targets the Local Mac scale set; attempt 2 targets the GitHub-hosted fallback.

name: CI

on:
  push:
  pull_request:

jobs:
  tests:
    runs-on: ${{ github.run_attempt == '1' && 'mirage-linux-arm64' || 'ubuntu-24.04-arm' }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

4. Verify the run

Push the workflow, then open Runs in Mirage. A healthy first run should show:

• the selected GitHub installation and repository;
• a Local Mac provider decision;
• one workflow attempt; and
• the paired machine and runner timing after assignment.

Turn off local capacity to test fallback. Mirage should cancel attempt 1 and GitHub should create attempt 2 under the same run ID.