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

# Connect a repository

> Back an empty Peeps project with a GitHub or GitLab repository: choose the repository, the test root and the branch Peeps mirrors, then check what Peeps is allowed to do there.

You connect a repository from the project's **Repository** settings page. Connecting takes Contributor or above.

## Before you start

* **Give Peeps access to the repository.** On GitHub, [install the Peeps GitHub App](/integrations/github) on the repository. On GitLab, [connect the GitLab group](/integrations/gitlab) that holds it.
* **Use an empty project.** A repository can only be connected to a project with no test cases, because the tests in the repository take the place of the ones Peeps would hold. Only web projects can be connected.

<Warning>
  Connecting can't be undone. You can't later move the project to a different repository or project. The test root, Playwright config, workflow file and delivery settings stay editable.
</Warning>

## Connect the project

<Steps>
  <Step title="Open the project's repository settings">
    In Peeps, open the project, then **Settings** and select **Repository** under **Project**.
  </Step>

  <Step title="Choose where your repository lives">
    Select **GitHub** or **GitLab**.
  </Step>

  <Step title="Pick the repository">
    <Tabs>
      <Tab title="GitHub">
        Choose the **GitHub installation**, then the **Repository**.
      </Tab>

      <Tab title="GitLab">
        Choose the **GitLab connection**, then search for and pick the **Project**.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Check where the tests live">
    Peeps looks through the repository and fills in two fields for you. Change either if it's wrong.

    * **Test root** is the directory your suite lives in, relative to the repository root. Use `.` for the whole repository.
    * **Playwright config** is the path to your Playwright config, relative to the repository root. Leave it empty to let Playwright find its own.

    On GitHub, Peeps says what it based this on, such as how many spec files it found and where. If it found Python test files, it says so. If it found no tests, you can still connect: Peeps finds tests once they exist.

    On GitLab you also set **CI configuration**, the file GitLab CI/CD reads. It's `.gitlab-ci.yml` unless yours is elsewhere.
  </Step>

  <Step title="Connect">
    Click **Connect repository** (GitHub) or **Connect GitLab project** (GitLab).

    Peeps starts reading your repository straight away. The page shows **Reading your repository…** until the tests it finds appear under **Tests found in the repository**.
  </Step>
</Steps>

Peeps mirrors the repository's default branch to begin with. You can choose another branch afterwards, see [Choose the headline branch](#choose-the-headline-branch).

Next, [add the Peeps workflow](/repository/workflow) to your repository. Peeps can read your tests without it, but nothing runs in your CI until it's there.

## When the project already has tests

A project that already has test cases can't be connected. The **Repository** page says **This project already has tests** and offers **Create a project for your repository**.

That opens the usual new-project dialog, filled in for you:

* the name is the current project's name followed by "(repository)"
* the environments that have a `BASE_URL` are copied from the current project, with their names and `BASE_URL` values only; other variables and secrets are not copied

Once you create it, Peeps takes you to the new project's **Repository** page to connect it. Your existing project and its test cases stay as they are. Nothing is moved.

## Choose the headline branch

Peeps mirrors one branch of your repository, the **headline branch**. Its tests are the project's test cases, and fixes and new tests open against it unless they're for another branch Peeps follows.

The headline branch is your repository's default branch unless you choose another. A team that ships from `develop` can choose `develop`, and Peeps keeps mirroring it even if the repository's default stays `main`. Peeps re-reads the headline branch on its own when you push to the repository's default branch, so after a push to a different headline branch, click **Run inventory now** to see the change straight away. See [When Peeps reads your tests](/repository/how-tests-sync#when-peeps-reads-your-tests).

To change it, click **Change** next to **Headline branch** and pick a branch. Peeps re-reads the tests on the new branch straight away. Peeps also follows other branches, such as `staging`; see [Tracked branches](/repository/how-tests-sync#tracked-branches).

## Check what Peeps can do

The **What Peeps can do in this repository** card lists each thing Peeps does in your repository, with **Allowed** or **Missing permission** beside it.

| What Peeps does | GitHub permissions it needs | Without it |
| - | - | - |
| Read the tests in your repository | Contents: read | Tests added or changed in the repository don't show up in Peeps. |
| Start runs in your CI | Contents: read, Actions: write | **Run all in your CI** doesn't work. Peeps only reports the runs your own CI starts. |
| Read CI logs for failure analysis | Actions: read | Failures are still analyzed, without your CI job's log as evidence. |
| Open fix and new-test pull requests | Contents: write, Pull requests: write, Actions: write | Fixes and new tests stop before anything is pushed. |
| Answer `/peeps` comments on issues | Issues: write | A `/peeps` comment on an issue gets no reaction or reply. |
| Answer `/peeps` comments on pull requests | Issues: write, Pull requests: write | A `/peeps` comment on a pull request gets no reaction or reply. |
| Post the fix verification check | Contents: read, Checks: write | Fix pull requests get no Peeps check saying whether the test passed on that branch. |

On GitLab, everything that writes needs a token with the `api` scope, and reading needs `read_api` or `api`.

If you grant a permission or replace the GitLab token after connecting, click **Re-check permissions** so Peeps reads the change.

## Settings you can change later

The **Settings** card on the **Repository** page holds:

* **Test root** and **Playwright config (optional)**, as above.
* **Workflow file** (GitHub): the file name under `.github/workflows/` that Peeps starts, `peeps.yml` by default. On GitLab, **CI configuration**.
* **Open fix pull requests**: the most pull requests Peeps keeps open in the repository at once, fixes and new tests together, from 1 to 50. It's 5 unless you change it.
* **Healed fixes arrive as** and **Generated tests arrive as**: **Pull request** or **Draft pull request**.
* **Include every pytest test under the test root**: see [Python tests](/repository/how-tests-sync#python-tests).

Click **Save settings**, then **Run inventory now** to re-read the repository with them.

## Disconnecting

There's no disconnect button on the project. To stop Peeps reaching your repository:

* **GitHub:** uninstall the Peeps GitHub App, or remove the repository from it, on GitHub.
* **GitLab:** disconnect the group under **Settings** > **GitLab** in Peeps.

The project keeps its tests and history. Reinstalling the app or reconnecting the group picks it back up.

***

Need help connecting? [Get in touch](mailto:support@peepsai.com).


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