Connect GitHub

Connect an account

Sign in to the dashboard with GitHub, then connect your organization or personal repositories. You can add more accounts later from the dashboard’s account menu. Choose the private repositories you want to use in GitHub’s App installation screen.

If your organization requires approval to install Apps, an organization administrator must approve the installation before setup can finish. A Mirage login alone does not grant the App access to an organization’s repositories.

Enable a repository

1. Select the repository’s account in Mirage and open Settings.
2. For local-infrastructure routing or provider comparisons, turn on Allow opted-in repositories for the account.
3. Enable the providers you want to use. Local infrastructure enables routing to your machines and is also required for provider-comparison onboarding. Cloudflare enables direct Cloudflare jobs. Wait for runner setup to complete.
4. For local infrastructure, check Runners for available shared capacity or pair a Mac. For Cloudflare, connect a ready Cloudflare account.
5. Configure a workflow route, use a direct Cloudflare label, or onboard an existing job for comparisons.

Repository access, routing settings, and workflow labels each have a job to do. Installing the App makes a repository visible. Enabling it allows Mirage to run its jobs. Its workflow’s runs-on chooses which jobs actually use Mirage. Newly added repositories start with routing disabled.

Cloudflare has a separate repository switch and needs a ready Cloudflare account.

GitHub permissions

Mirage uses its GitHub App to read workflow and job details, register runners, and request reruns for fallback. Review the requested permissions during installation. You do not need to create your own GitHub App or add a Mirage token to workflow secrets.

The optional provider comparison feature also needs permission to create workflow changes and pull requests. If Discover jobs reports missing App permissions, approve the update on GitHub and refresh the jobs in Mirage.

Change or remove access

In Settings, select Manage access on GitHub to change the App’s repository selection. Back in Mirage, select Sync repositories. Enable any newly added private repository you want to run.

To move a repository back to GitHub-hosted runners, restore its original runs-on labels first. Then disable its Mirage routing switches. You can also remove the repository from the GitHub App’s selection or uninstall the App in GitHub when you no longer need the connection.