Get started
What is Mirage?
Choose where your CI jobs run, compare providers, and control fallback.
Mirage is a router for CI jobs. It connects your GitHub Actions workflows to execution providers, so you can choose where each job runs, compare providers, and configure fallback.
Your workflows define the builds and tests. Mirage manages their execution routes across GitHub-hosted runners, your Macs, and Cloudflare. You keep using GitHub Actions for triggers, pull request checks, logs, artifacts, and secrets.
One workflow, multiple providers
Choose an execution provider for each job. A workflow can keep some jobs on GitHub-hosted runners while routing others to your own machines or Cloudflare.
Mirage shows the provider, result, and available timing information for each job. The routing guide explains how providers, runner labels, and fallback fit together.
Choose, compare, and fall back
- Choose where a job runs. Set its runner in the workflow, or onboard an eligible job so you can manage its default provider through Mirage.
- Compare before switching. Run an extra copy of a completed job on the same commit across providers. Review the results and timings, then promote a supported provider through a pull request.
- Configure a fallback. Try your Macs first and use GitHub-hosted runners when local capacity or infrastructure is unavailable. Failed tests still fail the check.
Provider support varies. Cloudflare supports direct Linux x64 workflows and comparisons; it currently has no promotion action or automatic hosted fallback. See provider capabilities before choosing a route.
Choose a starting point
- Understand the routing model: start with Routing and providers.
- Evaluate providers for an existing job: compare CI providers while keeping the current GitHub-hosted default.
- Try routing with a Mac and hosted fallback: follow Route your first job.
- Use your Proxmox cluster: connect Proxmox runners for disposable Linux QEMU VMs.
- Use Cloudflare compute: connect Cloudflare runners and run a compatible Linux x64 job.
- Manage Mirage from a terminal: use the CLI guide.
What you need
Start with a private GitHub repository and permission to install the Mirage GitHub App and review workflow changes. Connect GitHub, then set up the providers you want to use. Your team may already have shared capacity available.
- GitHub-hosted runners use your repository’s GitHub Actions access and billing.
- Local infrastructure uses a paired Mirage connector with a ready runner profile for the job’s operating system and architecture. The guided setup uses an Apple-silicon Mac.
- Cloudflare uses available shared capacity or your own Cloudflare account, without requiring a paired Mac.
Mirage also has a dedicated Linux connector with Docker and Proxmox runtimes. Its current installation requires a source build and host administration; it is not part of the Mac quick start. See the differences in job isolation before choosing a host.
Use the hosted router at mirageci.com. Provider setup and workflow changes happen in your accounts; Mirage’s server is managed for you.