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

# Connecting a Repository

> Connect GitHub or GitLab, choose a test source, and manage workspace repositories.

Watchtower needs access to a repository before it can build a test inventory or run Watchman analysis. All repository connections are managed from **Configuration → CI / Repos**, and are scoped to your current [workspace](https://docs.watchtower.systems/v0.7.0/guides/workspaces.md).

## Connect with the GitHub App

1. Open **Configuration → CI / Repos** and click **Connect GitHub** (or **Connect another repo** if you already have one connected).
2. You'll be sent to GitHub to install Watchtower's GitHub App and choose which repositories to grant access to.
3. Once you're back, the repositories you selected appear under **Repositories**.

## Choosing your test source

Watchtower tracks exactly one repository at a time as your **test source**, the one it scans for Playwright or Cypress spec files. The first time you connect, a **GitHub connected** modal asks directly which repository should be the test source, with a detected framework badge (Playwright, Cypress, or Mixed) and spec-file count next to each option to help you decide. A repository with no detected spec files is shown but disabled, it stays available for Watchman analysis, just not as your test source. You can pick **None (Watchman analysis only)** if you don't want a tracked test inventory yet.

Only one repository can be the test source; the rest stay connected under **Watchman only** and continue to get AI analysis on their pull requests and commits. To change your test source later, go to **Repositories** and select a different repo's radio button, then confirm with **Apply**. Switching the test source provisions the reporting workflow and secrets on the newly chosen repository.

## Managing connected repositories

Each connected repository has a menu with:

* **Run tests** (test source only): triggers a CI run for that repository directly from Watchtower.
* **Re-provision** (test source only): re-installs Watchtower's reporting workflow and refreshes its access if a connection starts acting up.
* **Disconnect**: removes the repository from Watchtower.

> [!NOTE]
>
> Disconnecting a repository in Watchtower doesn't uninstall the GitHub App or remove its secrets from GitHub. Manage those directly from your GitHub account or organization settings if you want to fully revoke access.

Use **Disconnect all** to remove every connected repository at once.

## Connecting a repository manually

If a repository can't use the GitHub App (for example, it's hosted outside GitHub), the **CI / Repos** tab includes manual setup instructions for **GitHub Actions** and **GitLab CI**. These provide a workflow file to add to your repository along with the ingest URL and token it needs to report results back to Watchtower.

## Permissions for editing spec files

Unlinking or relinking a test through a [pull request or direct commit](https://docs.watchtower.systems/v0.7.0/test-center.md#unlink-and-relink) requires the GitHub App installation to have the matching permission: **Pull requests: write** for pull requests, **Contents: write** for both. If a permission is missing, Watchtower tells you which one before attempting the change, rather than partway through.

## Connect GitLab

In **Configuration → CI / Repos**, choose **Connect GitLab** to authorize a gitlab.com account, then select the projects to connect. For a self-hosted GitLab instance, use the access-token option and provide your instance URL and token. GitLab projects appear alongside GitHub repositories in the test-source picker, Patrol, Reports, and Watchman.

You can connect more than one account and disconnect accounts individually. Select the intended workspace before connecting: connections belong to that workspace, including when an invited admin connects on behalf of its owner.

> [!NOTE]
>
> GitLab connections must be enabled for your Watchtower instance. If the connection option is unavailable, ask your instance administrator to check its configuration.

After a hosted GitHub connection, Watchtower returns you to the development, staging, or production environment where you started, including when you update an existing installation.


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