# 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, Cloudflare, or Blacksmith. |
| 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](https://mirageci.com/docs/workflow-routing.md) for local-infrastructure routing and fallback,
or [Cloudflare runners](https://mirageci.com/docs/cloudflare.md) for a direct Cloudflare route.

### Let Mirage set up the repository

Open the repository in [Repos](https://mirageci.com/repos) and choose **Set up routing**. Mirage checks that your
machines are ready for the jobs, lists the jobs it can route, and opens one pull request that
writes the routing for every job you select. Once you merge it, those jobs run on your
machines, and each falls back to the runner it used before.

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](https://mirageci.com/docs/ci-providers.md) 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. |
| Blacksmith | Blacksmith runners in your own Blacksmith account | Compare supported jobs on it, promote successful comparisons, or keep a job’s Blacksmith label as the fallback for a local-infrastructure route. Blacksmith’s GitHub App runs the job; Mirage chooses the label and reports its cost. |

Local infrastructure supports Linux arm64, Linux x64, and native macOS profiles when the required host
setup is ready. Blacksmith supports the same three profiles once Mirage has seen it run a job
for your account in the last 30 days. 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](https://mirageci.com/docs/proxmox.md), use capacity your team has already shared, or
[set up Cloudflare](https://mirageci.com/docs/cloudflare.md) 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 no machine takes it within the repository’s [queue
timeout](https://mirageci.com/docs/workflow-routing.md#queue-timeout), or runner infrastructure fails, Mirage
requests 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](https://mirageci.com/docs/workflow-routing.md#fallback) before
using it for work that publishes, deploys, or changes external state. If a budget or
spending limit blocks your GitHub-hosted runners, see [When GitHub-hosted runners are
blocked](https://mirageci.com/docs/workflow-routing.md#hosted-runners-blocked).

A job that fails because its runner’s disk filled up is reported by default. Each repository
in [Repos](https://mirageci.com/repos) can instead have such jobs fall back to their fallback runner; see
[My job ran out of disk](https://mirageci.com/docs/troubleshooting.md#job-ran-out-of-disk).

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](https://mirageci.com/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](https://mirageci.com/docs/runs.md)
for the available history and usage estimates.