Skip to documentation
MMirageDocs

Documentation

↑↓ Navigate↵ OpenEsc Close

Get started

Connect GitHub

Give Mirage access to private repositories and use them without a second enablement step.

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.

Use a repository

  1. Select a private repository when connecting the Mirage GitHub App. Mirage provisions local routing automatically; public repositories are never eligible.
  2. Check Machines for capacity shared with the account, or pair a Mac.
  3. Open the repository in Repos and choose Set up routing. Mirage checks that your machines are ready, lists the jobs it can route, and opens the setup pull request for you; Compare CI providers walks through it. To write the route yourself instead, configure a workflow route or use a direct Cloudflare label.

GitHub App access is the repository-level authorization. A workflow’s runs-on chooses which jobs actually use Mirage; the setup pull request writes it for the jobs you select. 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 a repository's Set up routing ready check reports missing App permissions, approve the update on GitHub, then reload the repository’s setup page 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. Newly added private repositories work automatically.

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