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

# Version Control

> Connect GitHub, GitLab, Bitbucket, or Azure DevOps.

Version control is the most important connection — it powers pull request, review, cycle time, and output metrics. Connect the one your engineers actually push code to.

All of these are connected from **Admin → Connections → Version Control** in the [Bilanc dashboard](https://app.bilanc.co).

***

## GitHub

GitHub is connected in two steps: authorize Bilanc (OAuth), then install the Bilanc GitHub App on the organizations you want to track.

**Who needs to do it:** a GitHub **organization owner**, so they can install the app and grant repository access.

### Steps

1. On the **GitHub** card, click **Connect**.
2. Authorize Bilanc in the GitHub popup.
3. When prompted to install the GitHub App, select the organization and choose **All repositories** (or pick specific repos).
4. To add another organization later, open the **GitHub** card's **Settings** (gear) icon and click **+** to start a new installation.

<Note>
  Bilanc requests read-only access to repository metadata, pull requests, and organization membership. It does not get write access.
</Note>

***

## GitLab

GitLab supports both **GitLab Cloud** (gitlab.com) and **self-hosted** instances.

**Who needs to do it:** a **group owner or maintainer** with visibility into the projects you want tracked.

### GitLab Cloud

1. On the **GitLab** card, click **Connect**.
2. Choose **GitLab Cloud**.
3. Authorize Bilanc in the GitLab popup.

### Self-hosted GitLab

1. On the **GitLab** card, click **Connect**.
2. Choose **Self-hosted GitLab** and enter your instance URL (e.g. `https://gitlab.yourcompany.com`).
3. Authorize with a personal access token from an account that can see the relevant projects. The token needs the `read_api` and `read_repository` scopes — create one at **GitLab → User Settings → Access Tokens**.

***

## Bitbucket

**Who needs to do it:** a **Bitbucket workspace admin**.

### Steps

1. On the **Bitbucket** card, click **Connect**.
2. Authorize Bilanc and select the workspace you want to track.

***

## Azure DevOps

Azure DevOps connects with a **personal access token (PAT)**. A single connection covers everything Bilanc reads from Azure DevOps — **Azure Repos** (commits, pull requests, reviews), **Azure Boards** (work items), and **Pipelines** (builds) — so there's nothing to set up separately for Repos and Boards.

Bilanc only ever reads data. It never writes to your organization, and it does not read or store your source code beyond the diffs needed for change-size metrics.

**Who needs to do it:** someone who can generate a PAT from an account with access to every project you want tracked. We recommend creating a dedicated **service account** and generating the token from it, so access doesn't depend on one person's profile and the token has its own lifecycle and expiry.

### Prerequisites

* An Azure DevOps **service account** with access to the organization and projects you want tracked.
* A **personal access token (PAT)** generated from that account, with the read scopes below and an expiration date you're comfortable with.

### Required PAT scopes

All scopes are **read-only**, and all are set on a single token:

| Scope                                    | What it covers                                                            |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| **Code** (read)                          | Repositories, commits, pull requests, reviewers, comments, and file diffs |
| **Work Items** (read)                    | Azure Boards work items                                                   |
| **Build** (read)                         | Builds and pipelines                                                      |
| **Project and Team** (read)              | Projects, teams, and team membership                                      |
| **Identity** (read)                      | Resolving user identities on reviews and teams                            |
| **Member Entitlement Management** (read) | Users and their license levels                                            |

<Note>
  These are exactly the scopes Bilanc uses — it does not need Release or Task Group permissions.
</Note>

### Steps

1. In the [Azure portal](https://portal.azure.com), create (or pick) a **service account** in Microsoft Entra ID, then add it to your Azure DevOps organization and grant it access to the relevant projects.
2. Sign in to Azure DevOps as that account and go to **User settings → Personal access tokens → New Token**.
3. Set an expiration date and select the **read** scopes listed above, then create the token. Copy it now — Azure DevOps only shows it once.
4. In Bilanc, go to **Admin → Connections → Version Control**, click **Connect** on the **Azure DevOps** card, and provide your organization name and the token.