Route your first job

Before you start

• A private GitHub repository where you can add a workflow.
• Permission to install a GitHub App on its personal account or organization.
• An Apple-silicon Mac running macOS 26, with administrator access to install Mirage.
• Enough free memory and disk for the runner. The initial Linux runner uses 2 CPUs, 8 GiB memory, and a 6 GiB disk budget, plus host reserves and downloaded images.

Connect the Mac to power and leave it awake during setup. This guide uses a Linux arm64 job, which does not need Rosetta or native macOS runner setup.

1. Connect GitHub

1. Open the Mirage dashboard and sign in with GitHub.
2. Choose Connect an organization or Connect personal repositories. Select your account and the private repository in GitHub’s installation screen.
3. Return to Mirage and select that GitHub account from the account menu.
4. Continue to the workflow step. Mirage creates the repository's runner mappings when the first Mirage-labeled job queues.

GitHub App access automatically enables the private repository. Connect GitHub explains repository access and organization permissions.

2. Pair your Mac

1. On the Mac that will run CI, open Terminal and run the command below. Setup asks about runner types and installs the host service, menu app, and CLI.
2. Choose personal and the default Linux-only setup for this example, then approve the macOS administrator prompt.
3. Open the approval link shown in Terminal. Sign in if needed, check that the verification code matches, choose the GitHub account that will manage this Mac, and confirm. Setup pairs the Mac automatically.

bash <(curl -fsSL https://mirageci.com/bootstrap/macos)

The approval link expires after twenty minutes. If it expires, run the bootstrap command again to get a new link. An already installed but unpaired Mac can also rerun setup.

Open your Mac in Machines. Wait for Linux arm64 to show Ready, and check that Available to includes the repository’s GitHub account. The first setup downloads and checks the runner image. A connected machine may still be preparing its runners.

For a Mac dedicated to CI, follow Set up a Mac for the installation and sleep settings.

3. Add a workflow

Create .github/workflows/mirage-smoke.yml in your repository with the following contents, then commit and push it. The job only prints its operating system, architecture, and a message, so it needs no project dependencies.

name: Mirage smoke test

on:
  push:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  smoke-test:
    runs-on: ${{ github.run_attempt == '1' && 'mirage-linux-arm64' || 'ubuntu-24.04-arm' }}
    steps:
      - name: Check the runner
        run: |
          uname -s
          uname -m
          echo "Hello from Mirage"

The runs-on expression tries Mirage on the first attempt and selects GitHub’s Ubuntu arm64 runner on every later attempt, including a manual rerun. GitHub-hosted fallback uses your GitHub Actions allowance or billing.

Fallback can rerun the whole workflow, repeating jobs that already finished. Read How fallback works before using this expression in a workflow with side effects. For an existing workflow, a setup pull request is the recommended path: its fallback reruns only the affected job, and a manual rerun tries your machines again.

4. Check the result

1. In your repository’s GitHub Actions tab, open Mirage smoke test.
2. Open the Check the runner step. It should print Linux, aarch64, and Hello from Mirage.
3. Open the same run in Mirage’s Runs page. Check the provider and machine to confirm it ran on your Mac; the printed output alone is the same on the fallback runner.

A successful local run uses Local infrastructure on attempt 1. A second attempt on GitHub means fallback worked; inspect the route reason to find out why your Mac was not used. If the job stays queued, follow Troubleshooting.

To test fallback, set the repository’s queue timeout to 2 minutes on its page in Repos. Wait until the Mac is idle, pause it in Mirage, and push another change to this smoke-test workflow. With no other eligible machine available, the job waits until the timeout ends, then attempt 2 runs on GitHub’s runner under the same run. Resume the Mac and restore the timeout afterward.

Use your own workflow

Open a setup pull request to route your project’s existing jobs; Mirage writes the routing and keeps each job’s current runner as its fallback. To edit a job by hand instead, use Configure workflows. Choose its operating system and architecture, install its tools explicitly, and check the fallback behavior before adding more jobs. You can remove the smoke-test file once your project’s workflow works.

Choose routes per job. Other jobs in the same workflow can keep their GitHub-hosted runners or use a compatible Cloudflare runner.

To route existing jobs without editing them, open the repository in Repos and choose Set up routing; see Compare CI providers.