# Connect GitHub

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

## Connect an account

Sign in to the [dashboard](https://mirageci.com/) 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](https://mirageci.com/machines) for capacity shared with the account, or
   [pair a Mac](https://mirageci.com/docs/local-mac.md).
3. Open the repository in [Repos](https://mirageci.com/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](https://mirageci.com/docs/ci-providers.md#adapt-a-job) walks through it. To write the
   route yourself instead, [configure a workflow route](https://mirageci.com/docs/workflow-routing.md) or use a direct
   [Cloudflare label](https://mirageci.com/docs/cloudflare.md#first-job).

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](https://mirageci.com/docs/cloudflare.md).

## 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.

> **Update workflows before disconnecting.**
>
> A workflow left on a Mirage label can stay queued after you remove the App, because Mirage
> no longer has access to arrange a fallback.