# Route your first job

Try a local-infrastructure route with GitHub-hosted fallback using a complete smoke-test workflow.

This quick start demonstrates one route: run a Linux arm64 job on your Mac, with
GitHub-hosted runners as fallback. You will connect GitHub, add execution capacity, choose
the job’s route, and verify which provider ran it.

To evaluate an existing job before changing its default, start with
[Compare CI providers](https://mirageci.com/docs/ci-providers.md). To route directly to cloud compute, follow
[Cloudflare runners](https://mirageci.com/docs/cloudflare.md). [Routing and providers](https://mirageci.com/docs/routing.md) explains
the choices.

## 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](https://mirageci.com/) 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](https://mirageci.com/docs/connect-github.md)
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.

Terminal · interactive Mac setup:

```bash
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](https://mirageci.com/docs/local-mac.md) 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.

.github/workflows/mirage-smoke.yml:

```yaml
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](https://mirageci.com/docs/workflow-routing.md#fallback) before using this expression in a workflow
with side effects. For an existing workflow, a [setup pull
request](https://mirageci.com/docs/ci-providers.md#adapt-a-job) 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](https://mirageci.com/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](https://mirageci.com/docs/troubleshooting.md).

To test fallback, set the repository’s queue timeout to 2 minutes on its page in
[Repos](https://mirageci.com/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](https://mirageci.com/docs/ci-providers.md#adapt-a-job) 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](https://mirageci.com/docs/workflow-routing.md). 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](https://mirageci.com/repos) and choose **Set up routing**; see [Compare CI providers](https://mirageci.com/docs/ci-providers.md#adapt-a-job).