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 describes;
• merges the merge request once its pipeline is green and GitLab allows the merge, if 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 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.