# Connect GitLab

Source: https://docs.tai.ga/administration/connect-gitlab/

Taiga can work in repositories on GitLab as well as on GitHub.
It always acts as a **bot you create in GitLab**, never as a person.

GitLab is enabled per organization. If you do not see GitLab under **Settings → Organization → Integrations**, ask us to turn it on.

## What Taiga does in your GitLab

In the projects you link, Taiga:

- clones the project and reads its code, to import it, to plan against it, and to answer questions about it in product chat;
- pushes its own branches and opens merge requests authored by your bot;
- reads the merge request's pipeline, and when it fails, reads the failed jobs' logs and pushes a fix;
- answers review threads and requests for changes on the merge request, as [Review Taiga's pull requests](https://docs.tai.ga/deliver/review-pull-requests/#on-gitlab) describes;
- merges the merge request once its pipeline is green and GitLab allows the merge, if [auto-merge](https://docs.tai.ga/deliver/auto-merge/) is on for the initiative;
- reads the integration branch, to keep the product's documents and its maintenance findings up to date.

Taiga never pushes to your integration branch directly, and never gets around your push rules, your protected branches or secret push protection.
When GitLab refuses a push, the run ends and names the rule GitLab gave.

Not yet on GitLab: Taiga does not read deployments from GitLab, so a GitLab project's deployments do not appear on the product's deployments page.

## Before you start: a bot for Taiga

Taiga acts in GitLab as a bot, so that its work is never attributed to a person.
Taiga refuses a person's personal access token for that reason, and a token with the `sudo` scope.

Two kinds of bot work. Either way, give it:

- the **`api`** scope: Taiga needs it to open merge requests, and it also covers cloning and pushing;
- the **Maintainer** role on the projects Taiga should work on. As a Maintainer, Taiga adds its webhook to each project itself, and can merge into a protected branch that only Maintainers may merge to.

The **Developer** role works too, if your policy asks for less: Taiga still pushes branches, opens merge requests, reads pipelines and works on reviews. You then add the webhook yourself, as [The webhook](#the-webhook) describes, and a merge into a Maintainer-only branch is refused: the initiative says so, and a person merges. Adding the bot to that branch's **Allowed to merge** lets it merge again.

The token reaches every project the bot is a member of, so add the bot only to the projects or groups Taiga should work on.

If your projects have push rules on the committer email, or require signed commits, the bot's commits must meet them, or GitLab refuses every push.
Taiga commits as the bot's own commit email.

**On GitLab.com, both kinds of bot need the Premium or Ultimate tier.** GitLab Free does not offer them, and neither does a GitLab trial for access tokens.

### Option A: a service account (recommended)

A service account is a dedicated bot user. Its name is what your team sees on Taiga's commits and merge requests.

1. In your top-level group, open **Settings → Service accounts** and add one, for example `taiga`.
2. Open the service account, add a personal access token with the **`api`** scope, and set an expiry date.
3. Copy the token. GitLab shows it only once.
4. Add the service account to the group, or to each project Taiga should work on, under **Manage → Members → Invite members**, with the **Maintainer** role.

### Option B: a group access token

1. In the group, open **Settings → Access tokens** and add a new token.
2. Set the role to **Maintainer**, GitLab's default for a group access token.
3. Select the **`api`** scope, and set an expiry date.
4. Copy the token. GitLab shows it only once.

A project access token works the same way, for one project.

## Connect it in Taiga

An administrator connects GitLab once for the organization.

1. Open **Settings → Organization → Integrations** and choose **Connect** under **GitLab**.
2. Give the connection a name your team will recognize.
3. Enter the GitLab address: `https://gitlab.com`, or your own GitLab's address.
4. Paste the bot token.
5. Leave **Private CA certificate** empty unless your own GitLab uses a certificate issued by your own certificate authority.

Taiga checks the token with GitLab before saving it: that it belongs to a bot, that it has the `api` scope,
and which projects the bot can push to. It stores the token encrypted and never shows it again.

## Link a project

On a new product that starts from existing code, choose **Connect repository** in the import step, and pick the project under your GitLab connection's name.
On a product that already exists, open its **Settings → Integrations** and choose **Connect repository**.
Only projects the bot can push to are listed.

Taiga works from the project's default branch.
To have it branch from, and open its merge requests against, another branch, choose **Change branch** on the repository in the product's **Settings → Integrations**.

## The webhook

A webhook tells Taiga the moment a merge request, its pipeline or its threads change, and when someone pushes to the project.

- Where the bot is a Maintainer, Taiga adds the webhook itself when you link the project.
- Elsewhere, the product shows an item under **Action required** asking you to add Taiga's webhook to the project.

To add it by hand:

1. In Taiga, open **Settings → Organization → Integrations**, open the menu of your GitLab connection, and choose **Webhooks**.
2. Copy the URL, and the signing token (GitLab 19 and later) or the secret token.
3. In the project on GitLab, open **Settings → Webhooks** and add a webhook with that URL and token.
   Select the **Merge request**, **Pipeline**, **Comments** and **Push** events.

The item under **Action required** closes on its own when the first event arrives.

Without a webhook, Taiga still notices merge requests, pipelines and threads within a few minutes, and on a merge request it opened more than 30 days ago, within 6 hours.
A push made outside Taiga to the integration branch, such as a teammate's merge, reaches Taiga only through the webhook, or otherwise within 6 hours.

## Your own GitLab

Taiga connects to a self-managed GitLab the same way, with three requirements:

- it must be reachable from the internet on port 443 from Taiga's IP addresses, which we give you on request;
- GitLab 16 or later; Taiga warns below 17;
- a certificate from a public authority, or your own CA's certificate pasted into the connection.

## When the token expires or is revoked

The connection shows the token's expiry date.
From 14 days before it, each product that uses the connection shows an item under **Action required** asking you to replace the token.

To replace it, create a new token for the same bot in GitLab, with the same role and the `api` scope.
Then open the connection with **Edit** under **Settings → Organization → Integrations**, and paste it into **New bot token**.
The item closes on its own.

When GitLab refuses the token, because it expired or someone revoked it, Taiga marks the connection **Token refused** and stops using it, so a dead token cannot keep failing against your GitLab.
Replace the token the same way.