# Connect a repository

> Connect a GitHub repository to a project, so rules can run tests on it.

Source: https://rehearsal.dev/docs/github/connect-a-repository

Rehearsal works with GitHub through the Rehearsal GitHub App. Once a repository is connected, [rules](https://rehearsal.dev/docs/github/rules.md) run your tests on its pull requests and branches. Each result appears as a [check on the commit](https://rehearsal.dev/docs/github/checks.md).

Connecting needs **Manage integrations**, which the admin and owner roles include. Other members see **Ask a workspace admin to connect GitHub.**

## Connect

1. **Press Connect GitHub**

   Open **Deployments** in the sidebar and press **Connect GitHub**. The same button is in **Settings**, under **Project** and **Repository**.

2. **Install the app on GitHub**

   GitHub asks which account to install the Rehearsal app on, and which repositories it may see. Choose them and install.

3. **Approve the sign-in on GitHub**

   GitHub then asks you to authorize Rehearsal. This proves your GitHub account can reach the installation. Rehearsal does not keep this sign-in.

4. **Choose the repository**

   Back in Rehearsal, the **Repository** page opens. In **Choose a repository**, pick the repository and press **Connect**.

> [!NOTE]
> A connection link lasts ten minutes, works once, and has to finish in the tab that started it. If it runs out, start again from the project.

## One repository per project

- A project has one repository, and a repository belongs to one project.
- The list marks a repository that another project already uses. Rehearsal refuses to connect it twice.
- The list shows up to 500 repositories. A repository is missing when the app cannot see it. Add it to the Rehearsal app in GitHub.

## What Rehearsal reads

Rehearsal never reads your code. It reads the repository's details, its pull requests, its deployments and its branch rules. None of its requests to GitHub asks for a file. The one thing it writes is a check on a commit.

The **Repository** page shows this too, under **Rehearsal can read**.

## Change or disconnect

- On the **Repository** page, press **Change** to connect a different repository.
- Press **Disconnect** to take the repository off the project. Its rules are removed. Runs that already finished keep their results.

## Changes made in GitHub

| In GitHub, you | In Rehearsal |
| --- | --- |
| Rename or move the repository | The connection follows it. |
| Remove the repository from the app | The project loses its repository. |
| Uninstall the app | Every project that used it loses its repository. |
| Suspend the app | Rehearsal writes no checks until you turn it back on. |

## If connecting fails

| Rehearsal says | What to do |
| --- | --- |
| **Your GitHub account cannot see this installation** | Ask an owner of the GitHub account that has Rehearsal installed to connect it. |
| **This installation belongs to another workspace** | Remove Rehearsal in GitHub, then install it again from this workspace. |
| **This installation is suspended in GitHub** | Turn it back on in GitHub, then connect again. |
| **That link no longer works** | Start again from the project, in one tab. |

## Next steps

- Add a [rule](https://rehearsal.dev/docs/github/rules.md) that says when to run tests.
- Test each pull request's [Vercel preview](https://rehearsal.dev/docs/github/preview-deployments.md).