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. Open Settings. Turn on Allow opted-in repositories, then turn on Local infrastructure beside your repository.
5. Wait for repository setup to finish. If it shows a setup error, use Retry provisioning before continuing.

The account switch and repository switch both need to be on. Connect GitHub explains repository access and organization permissions.

2. Pair your Mac

1. In Machines, select Pair Mac to create a pairing code.
2. On the Mac that will run CI, open Terminal and run the command below. It installs the host service and pairs the machine.
3. Enter the pairing code when prompted and approve the macOS administrator prompt.

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

Pairing codes expire after ten minutes and work once. If one expires, create a new code in the pairing dialog. If Mirage is already installed, enter the code in Pair this Mac in the menu-bar app instead.

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 later attempts. GitHub-hosted fallback uses your GitHub Actions allowance or billing.

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, 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, expect attempt 2 under the same GitHub run. Resume the Mac afterward.

Use your own workflow

Update one build or test job using 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.