> ## Documentation Index
> Fetch the complete documentation index at: https://boxrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect GitHub

> Install or link the BoxRouter GitHub App, choose which repositories it can reach, and see what each permission is for.

A job reaches BoxRouter only after all three of these are true:

1. The GitHub App installation includes the repository.
2. A workspace administrator connects that installation to BoxRouter.
3. A workspace administrator turns on the repository in BoxRouter.

**Before You Begin:** Private repositories you can manage, and administrator rights in the BoxRouter workspace. For an organization, an owner may have to approve the App first.

## Connect an Account

In BoxRouter, open **GitHub Actions**. Under **Connect GitHub**, choose one path.

> [tab] Install the App
>
> 1. Choose **Connect A GitHub Org**.
> 2. In GitHub, pick the owner of the repositories.
> 3. Review the permissions, choose **Only select repositories**, and pick the private repositories to try.
> 4. Complete the install. GitHub returns you to BoxRouter.

> [tab] Link an Existing Install
>
> 1. Choose **Already Installed? Link It**, and authorize with GitHub if asked. This only lets BoxRouter list the installations you can manage; it grants no permission on your repositories.
> 2. Pick the installation, then up to 100 private repositories you can manage.
> 3. Return to BoxRouter.

If GitHub asks an organization owner to approve the installation, the connection completes after that approval. Installations appear under **Account → Integrations**, where every workspace you administer can use them.

If a repository is missing, the installation does not include it or your GitHub account cannot manage it. Add it under the installation's repository access in GitHub, then reload the list in BoxRouter.

## Permissions

The App's manifest asks for these, and GitHub shows the same list before you approve:

| Permission | Access | What BoxRouter Does with It |
| - | - | - |
| Administration | Write | Creates the one-time runner registration for each job. |
| Actions | Write | Cancels or re-runs a workflow run from BoxRouter. |
| Checks | Write | Posts a **BoxRouter** check on the commit when a job is refused. |
| Contents | Read | Mints a read-only token for a private repository you have connected, scoped to that repository. |
| Metadata | Read | Required by GitHub for every App. |

For job operations, BoxRouter requests short-lived installation tokens scoped to the repository and the permissions each operation needs. The App is notified of `push`, `workflow_job`, `workflow_run`, and installation and repository changes.

## Turn Repositories On

In **GitHub Actions**, turn on each repository. Installing the App sends no job to BoxRouter. A job runs there only when its workflow uses a BoxRouter label, as in [Run your first GitHub job](https://boxrouter.ai/docs/actions/quickstart.md).

## Disconnect

Choose **Disconnect** on the account's row under **Account → Integrations**. New jobs stop being accepted. Disconnecting does not cancel a running job or remove its sandbox; find any job still running in [Find a run](https://boxrouter.ai/docs/actions/runs.md).

## Next Steps

> [card] [Run Your First GitHub Job](https://boxrouter.ai/docs/actions/quickstart.md)
>
> Change one line and find the run.

> [card] [How Actions Security Works](https://boxrouter.ai/docs/actions/security.md)
>
> Which jobs run and where secrets stay.

> [card] [Choose a Runner](https://boxrouter.ai/docs/actions/runners.md)
>
> Labels, sizes, and time limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.