Connect a repository

Connect a project to its GitHub repository, so Rehearsal can test pull requests and post each result as a check.

Once a project is connected to its GitHub repository, Rehearsal can run your tests on every pull request and post each result as a check on the commit, where your team looks before it merges. This page connects Parcel's repository to the parcel project, and Rules for pull requests and deployments then says which tests run and when.

Rehearsal works with GitHub through its own GitHub App. The app learns when a pull request opens or a deployment is ready, and it writes checks. It reads a pull request's changes only for a rule that checks what changed. Connecting alone starts nothing, because tests run only once you add a rule.

Before you start Link to Before you start

  • Connecting needs the Manage integrations permission, which admins and owners have. Everyone else in the workspace sees the repository and its runs, and reads Ask a workspace admin to connect GitHub. where the button would be.
  • Installing an app on a GitHub organisation takes one of its owners. If you do not own the account that holds the repository, connect it together with someone who does.

Connect Link to Connect

  1. Step 1: Press Connect GitHub

    Open Pull requests in the sidebar. Without a repository, the page reads Check every pull request before you merge, and Connect GitHub sits under it. The project's Repository page in Settings has the same button.

  2. Step 2: Install the app on GitHub

    GitHub asks which account to install the Rehearsal app on and which of its repositories the app may see. Choose the account that holds Parcel's repository, give the app all repositories or only that one, and install it.

  3. Step 3: Authorise Rehearsal

    GitHub then asks you to authorise Rehearsal. This proves that your own GitHub account can reach the installation you made, so nobody can attach someone else's installation to your workspace. Rehearsal uses the authorisation once and does not keep it.

  4. Step 4: Choose the repository

    GitHub sends you back to the project's Repository page, where Choose a repository lists every repository the app can see. Pick Parcel's repository and press Connect.

The Repository page now shows it under Connected repository, and Pull requests shows it with Connected beside it. Because nothing runs until a rule says so, the page offers Add a rule under Next step.

Good to know

The connection has to finish within ten minutes, in the browser tab that started it, and its link works once. If GitHub sends you back to That link no longer works, press Go to Rehearsal and start again from the project.

One repository per project Link to One repository per project

A project connects one repository, and a repository belongs to one project, so every rule and every check of the project is about that repository. In Choose a repository, a repository that another project already uses is marked Another project, and Rehearsal refuses to connect it a second time.

Once your workspace has installed the app, connecting another project skips GitHub altogether, and Connect GitHub opens Choose a repository at once, with the repositories that installation can see, up to 500 of them. If the one you want is missing, the app cannot see it yet, so add it to the app's repositories in the app's settings on GitHub.

What Rehearsal reads and writes Link to What Rehearsal reads and writes

The Repository page lists what the app may use under Rehearsal can read: the repository's details, its deployments, its pull requests and the checks Rehearsal writes. From these it learns when to start a run, reads which checks a branch requires, and posts its checks. It does not read your repository. A rule with Check what changed turned on is the one exception: Rehearsal then reads each pull request's title, its description and the lines it changed, to choose what to check. It reads them once, with keys and passwords written over first, and keeps only its own notes on what to check, never the code. Turn off Let Rehearsal read the changes on the rule, and it reads the title, the description and the names of the changed files, and nothing inside them.

The app writes one other thing, and only when someone asks. On a bug's report, Share has Create GitHub issue, which opens an issue in this repository with the bug's steps and a link back, as Share a bug shows. It needs Manage projects. If GitHub has not allowed the app to create issues, the row says Rehearsal needs permission to create issues. Allow it in your GitHub settings. and leads to the app's settings on GitHub.

Disconnect or switch repositories Link to Disconnect or switch repositories

Disconnect, on the Repository page, takes the repository off the project after you confirm. Its rules are removed with it, and runs that already finished keep their results.

To test a different repository, disconnect the one you have first, because a project with a repository refuses a second one with This project already has a repository. Disconnect it first. The page then lists the app's repositories again under Choose a repository, and you connect the other one there.

Changes made in GitHub Link to Changes made in GitHub

Rehearsal follows what happens to the app and the repository on GitHub's side:

In GitHub, youIn Rehearsal
Rename the repositoryThe connection follows it, and nothing else changes.
Take the repository away from the app, or delete itThe project loses its repository, so its rules stop running.
Uninstall the appEvery project in the workspace loses its repository.
Suspend the appRehearsal starts no runs and posts no checks until you unsuspend it.

If connecting fails Link to If connecting fails

Rehearsal saysWhat to do
Your GitHub account cannot see this installationThe app is installed on an account your GitHub account cannot reach. Ask an owner of that account to connect it.
This installation belongs to another workspaceUninstall the Rehearsal app in GitHub, then install it again from this workspace.
This installation is suspended in GitHubUnsuspend the app in GitHub, then connect again.
That link no longer worksStart again from the project, in one tab, and finish within ten minutes.
Nothing was connectedThe install was stopped on GitHub. Start again when you are ready.
That repository is already connected to another project.Disconnect it from the other project first, or choose another repository.

Next steps Link to Next steps