Get started
Routing and providers
Understand how Mirage connects jobs to providers, manages defaults, and handles fallback.
Mirage gives you one place to choose execution providers for GitHub Actions jobs, compare their results, and manage changes to those choices. A route applies to a job, so different jobs in the same workflow can use different providers.
Workflows, routes, and runners
| Concept | What it controls |
|---|---|
| Workflow | GitHub’s triggers, jobs, dependencies, and steps: the work you want to do. |
| Route | Which provider a job uses by default, and its fallback where supported. |
| Provider | Where the compute comes from: GitHub-hosted runners, local infrastructure, or Cloudflare. |
| Runner profile | The operating system, architecture, and resources the job needs. |
For example, a Linux arm64 job can use a ready Mac runner first and GitHub’s Ubuntu arm64 runner for fallback. Another job in the same workflow can keep its GitHub-hosted label. Your workflow continues to define the steps and required checks.
Choosing a provider does not make its environment identical to another provider’s. Check architecture and tool support, install dependencies explicitly, and compare a real build or test job before changing its normal route.
Two ways to choose a route
Configure the workflow yourself
Set the job’s runs-on to its desired runner. Use the documented attempt expression for
local infrastructure with GitHub-hosted fallback, or an explicit Cloudflare label for a direct
Cloudflare job. You review and commit the workflow change yourself.
Start with Configure workflows for local-infrastructure routing and fallback, or Cloudflare runners for a direct Cloudflare route.
Compare providers, then change the default
Onboard an eligible existing GitHub-hosted job through Per-job routes and experiments in Settings. Mirage opens a pull request that prepares the job for comparisons while keeping GitHub as its default provider.
After a normal run completes, launch an experiment on the providers you want to evaluate. Mirage runs extra copies of that job at the same commit and shows their results and timing. When you promote a supported provider, Mirage opens a separate pull request to change the job’s normal route. Review and merge it to apply the change.
Follow Compare CI providers for eligibility rules and the full setup. This path starts from a supported static GitHub-hosted label; a job already using the local-infrastructure attempt expression needs a separate eligible job or its original label restored before onboarding.
Available providers
| Provider | Compute | How you use it with Mirage |
|---|---|---|
| GitHub-hosted | GitHub’s runner infrastructure | Keep it as a job’s default, compare supported jobs on it, or use it as the fallback for a local-infrastructure route. |
| Local infrastructure | Your paired Mirage connectors | Route compatible Linux or macOS jobs to your machines, compare them against other providers, and promote successful comparisons. |
| Cloudflare | Cloudflare Containers in a shared or your own account | Run direct Linux x64 jobs or compare eligible jobs. Promotion and automatic hosted fallback are currently unavailable. |
Local infrastructure supports Linux arm64, Linux x64, and native macOS profiles when the required host setup is ready. Cloudflare supports Linux x64 jobs that do not need Docker commands, service containers, or container actions. The comparison flow offers only the providers compatible with the selected job and available to your account.
Pairing a Mac adds one source of execution capacity. You can also connect a Proxmox cluster, use capacity your team has already shared, or set up Cloudflare without a Mac.
Defaults and fallback
The default is where the normal job runs. For local-infrastructure routing with hosted fallback, attempt 1 targets your machines. When local capacity or runner infrastructure cannot complete it, Mirage can request one rerun of the whole workflow; attempt 2 uses the configured GitHub-hosted runner.
This can repeat completed jobs and their side effects. Failed tests do not trigger infrastructure recovery. Read How fallback works before using it for work that publishes, deploys, or changes external state.
Experiments help you choose a default. They do not automatically redirect future jobs: you review and merge a route-change pull request. Routes are based on your configuration; Mirage does not automatically choose the cheapest or fastest provider for each run.
Follow a job across providers
Open Runs to see which provider ran a job, its result, and available timing information. For a local-infrastructure job, inspect the machine assignment and route reason to understand whether it ran locally or used fallback. Provider comparisons appear alongside the source job without changing its required check.
Follow the GitHub links for full logs and artifacts. Provider usage is billed according to the compute you use; GitHub-hosted fallback uses your GitHub Actions allowance or billing, and your own Cloudflare account is billed by Cloudflare. See Monitor runs for the available history and usage estimates.