---
title: "Connect a repository"
section: "Deploys & Repos"
description: "Connect a GitHub, GitLab, Bitbucket, Azure DevOps or Gitea repository to a SmartestQA project, choose token or notification only, and map its environments."
url: https://docs.smartestqa.ai/en/deployments-repos.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "add repository code repositories provider github gitlab bitbucket azure devops gitea forgejo access token test connection service name environment mapping branch start url self-hosted api base url delete repository"
---
# Deploys & Repos: Connect a repository

A repository is the link between your code and the deploy records. This page covers adding one, choosing how it connects, mapping its environments, and changing or deleting it.

## In short

**On this page you can**

- Add a repository from GitHub, GitLab, Bitbucket, Azure DevOps, Gitea or any other Git server.
- Choose Deploy notification only or Connect with token to also read commits.
- Check a token with Test connection before you save.
- Map environments, branches and start URLs, and add your own environments such as STAGING.

**How to use it**

1. Open Repositories and click Add repository .
2. Pick the provider, paste the Repository URL and type a Service name .
3. Choose the connection mode; with a token, click Test connection .
4. Switch on the environments you deploy to, then click Save .
5. Copy the deploy token from the window that opens: it is shown only once.

## Add a repository

Any [Admin](https://docs.smartestqa.ai/en/company-settings-roles.html) or User with access to the project can add repositories. Admins can also do it from **[Integrations](https://docs.smartestqa.ai/en/integrations.html)**, where the same **Code repositories** list appears.

1. **Open the Repositories tab**

   Go to **Deploys & Repos** › **Repositories** and click **Add repository**. On an empty **Overview** the same button sits under “No repository connected to this project yet.”
2. **Pick the provider**

   GitHub, GitLab, Bitbucket, Azure DevOps, Gitea / Forgejo or Other. **Other** records deploys only and never reads commits.
3. **Fill in section 1 · Repository**

   Paste the **Repository URL** and type a **Service name**. **Display name** and **Default branch** are optional. See [the fields](https://docs.smartestqa.ai/en/deployments-repos.html#fields).
4. **Choose section 2 · Connection**

   **Deploy notification only** needs no token. **Connect with token** also reads commits and changed files. With a token, click **Test connection**. See [Connection modes](https://docs.smartestqa.ai/en/deployments-repos.html#connection-modes).
5. **Set section 3 · Environment mapping**

   Switch on the environments you deploy this service to. Add a branch and a start URL per environment if you like. See [Environment mapping](https://docs.smartestqa.ai/en/deployments-repos.html#env-mapping).
6. **Save and copy the deploy token**

   Click **Save**. “Repository saved.” appears and the [**CI code & deploy token**](https://docs.smartestqa.ai/en/deployments-ci.html#add-ci-step) window opens with the new token.

   The repository is listed with the chip **No deploy received yet** (or **Connected with token**). Continue with [Send deploys from CI](https://docs.smartestqa.ai/en/deployments-ci.html#add-ci-step).

> **Warning: The deploy token is shown once**
>
> Copy it before you close the window. Later the window only shows “Token ending in …*abcd* is active. It is shown only once.” If you lose it, [generate a new one](https://docs.smartestqa.ai/en/deployments-ci.html#regenerate).

## The fields

| Field | Required | Rules |
| --- | --- | --- |
| Provider | Yes | GitHub, GitLab, Bitbucket, Azure DevOps, Gitea / Forgejo, Other. Default: GitHub. |
| Repository URL | Yes | Up to 500 characters, `http://` or `https://`. `git@host:owner/repo.git` is accepted too. For every provider except Other it must contain owner and repository. [Formats](https://docs.smartestqa.ai/en/deployments-repos.html#url-formats). |
| Service name | Yes | Lowercase letters, digits, `-` and `_`, starting with a letter or digit, up to 40 characters. Unique in the project. “Deploys are shown under this name.” |
| Display name | No | Up to 120 characters. Empty: the last part of the URL, for example `web-frontend`. |
| Default branch | No | Up to 200 characters. A successful **Test connection** fills it if it is empty. |
| Access token | Only for **Connect with token** | Up to 2,000 characters. Stored encrypted and never shown again. |
| API base URL (self-hosted) | No | Under **Advanced (self-hosted server)**. See [Self-hosted servers](https://docs.smartestqa.ai/en/deployments-repos.html#self-hosted). |

### Repository URL formats

| Provider | Example |
| --- | --- |
| GitHub, GitHub Enterprise | `https://github.com/acme/web-frontend` |
| GitLab (subgroups allowed) | `https://gitlab.com/acme/platform/api` |
| Bitbucket Cloud | `https://bitbucket.org/acme/web-frontend` |
| Azure DevOps | `https://dev.azure.com/acme/Shop/_git/web` or `https://acme.visualstudio.com/Shop/_git/web` |
| Gitea / Forgejo | `https://git.acme.local/acme/web-frontend` |
| Other | Any address; it is stored for reference only. |

## Connection modes

| Mode | What you get | Chip in the list |
| --- | --- | --- |
| **Deploy notification only** | “No token needed. CI notifies Smartest after each deploy; you see which version runs where.” No commit list. | **No deploy received yet** until the first deploy, then **Webhook only** (“Add a token to see commits”). |
| **Connect with token** | Everything above, plus the commits and changed files between two versions. Read-only access is enough. | **Connected with token** (“Commits and diffs are read”). |
| Provider **Other** | “Commits are not read for this provider; only deploy notifications are recorded.” No token field. | **No deploy received yet**, then **Webhook only** (“Deploy records only”). |

### Which token to create

| Provider | Token |
| --- | --- |
| GitHub | Fine-grained token with “Contents: Read” on this repository. |
| GitLab | Project or personal access token with `read_api` scope. |
| Bitbucket | Repository access token, or `username:app-password`. |
| Azure DevOps | Personal access token with Code (Read). |
| Gitea / Forgejo | Access token with `read:repository`. |

### Test connection

**Test connection** is active when the URL is filled and a token is typed (or saved). SmartestQA calls the provider’s API once and shows the result under the field.

- **Green**: the connection works. The message is followed by the repository’s full name and default branch, for example `(acme/web-frontend · main)`.
- **Red**: the server’s reason, such as a rejected token or a repository that was not found. The server writes these messages in Turkish; the [troubleshooting page](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#connection) lists each one with its meaning.

Changing the provider, URL, API base URL or token clears the last result. SmartestQA waits up to 10 seconds to connect and 20 seconds for an answer.

### Self-hosted servers

Leave **API base URL (self-hosted)** empty for github.com, gitlab.com, bitbucket.org and dev.azure.com. For your own server SmartestQA derives the API address from the repository URL:

| Provider | Derived API address |
| --- | --- |
| GitHub Enterprise | `https://your-host/api/v3` |
| GitLab self-managed | `https://your-host/api/v4` |
| Gitea / Forgejo | `https://your-host/api/v1` |

Set the field only if your API lives elsewhere. The SmartestQA server must reach that address. It refuses loopback and link-local addresses and does not follow redirects. Private network addresses are allowed.

## Environment mapping

Section 3 lists DEV, TEST and PRP, each with a switch, a **Branch** and a **Start URL**. “Only the environments switched on are expected for this repository.”

- **Switched off**: the cell for that environment shows [**Not mapped**](https://docs.smartestqa.ai/en/deployments-overview.html#cell-content) until a deploy arrives there anyway. Deploys are still recorded.
- **Branch** (up to 200 characters): for reference, for example `develop` for DEV and `main` for PRP. It is shown in the list; deploys from other branches are still recorded.
- **Start URL**: pick one of the project’s [start page](https://docs.smartestqa.ai/en/project-settings-project.html#start-pages) URLs. The list shows the address for that environment. With none defined the list shows “No URL defined”; add them in [Start Page URLs](https://docs.smartestqa.ai/en/quick-start-connect.html#start-page-url).
- **Your own environments**: type a name in the field with the placeholder “e.g. STAGING” and click **Add environment** (or press `Enter`). Names are turned to upper case: letters, digits, `-` and `_`, up to 32 characters. A repository can map at most 12 environments. Your own environments can be removed with the X; DEV, TEST and PRP can only be switched off.

> **Note: Your own environments get versions, not test results**
>
> [Pipelines](https://docs.smartestqa.ai/en/schedule-create.html) run in DEV, TEST or PRP. A deploy to STAGING is recorded and shown, but its test state is [**No pipeline environment**](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-no-pipeline-env). See [how deploys are matched with runs](https://docs.smartestqa.ai/en/deployments-numbers.html#tested-window).

## Change or delete a repository

In the **Code repositories** list, open the row’s menu (**Repository menu**, the ⋮ button):

| Menu item | What it does |
| --- | --- |
| **Settings** | Opens **Edit repository · *name***. The token field is empty with “Leave empty to keep the saved token”. Choosing **Deploy notification only** and saving removes the saved token. |
| [**CI code & deploy token**](https://docs.smartestqa.ai/en/deployments-ci.html#add-ci-step) | Webhook URL, CI code and [**Generate new token**](https://docs.smartestqa.ai/en/deployments-ci.html#regenerate). See [Send deploys from CI](https://docs.smartestqa.ai/en/deployments-ci.html). |
| **Delete** | Asks **Delete repository: *name***: “The repository connection and its deploy token are removed. Past deploy records are kept.” After confirming: “Repository removed.” |

If you close the dialog with unsaved changes (X, `Esc` or a click outside), it asks before discarding them.

> **Important: Deleting stops CI notifications at once**
>
> The deploy token stops working the moment you delete the repository. CI calls then get “invalid deploy token” errors (they do not break the deploy). The repository’s row disappears from [**Currently running versions**](https://docs.smartestqa.ai/en/deployments-overview.html#current-versions); its past records stay in [**Deploy history**](https://docs.smartestqa.ai/en/deployments-overview.html#history).

### The repository list

- **Repository / service**: display name, URL and a chip `Service: web`.
- **Provider** and **Connection**: the chip described in [Connection modes](https://docs.smartestqa.ai/en/deployments-repos.html#connection-modes).
- **Environment mapping**: the switched-on environments with their branch, for example `TEST ← release/*`.
- **Last deploy**: when the last notification arrived, as “12 min ago”. See [relative times](https://docs.smartestqa.ai/en/deployments-numbers.html#time-ago).

## If something goes wrong

- [“Service name: lowercase letters, digits, - or _ (e.g. web, api).”](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-service-key)
- [Another repository already uses this service name](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-service-taken)
- [“Enter an access token or choose "Deploy notification only".”](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-token-required)
- [The token is rejected (HTTP 401 or 403)](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-token-rejected)
- [The repository URL is not accepted](https://docs.smartestqa.ai/en/deployments-troubleshooting.html#fix-url-format)
