Skip to main content
GitLab connects with an access token rather than an app: you paste a token, Ankra shows you a webhook URL and secret, and you register the hook in GitLab yourself. GitLab.com and self-managed instances work the same way.

​
What a GitLab connection powers

  • AI code review on merge requests, and replies when somebody mentions @ankraai in a merge request comment.
  • GitOps for clusters whose repository lives on GitLab: configuration is committed to the repository, and pushes flow back into Ankra.
Both ride the same credential and the same webhook. Every AI capability is off until an organisation admin turns it on.

​
Prerequisites

You need:
  • A GitLab access token. A personal, group, or project access token all work.
  • Permission to add a webhook to each project Ankra should watch, or to the group containing them.

​
Token scopes

read_api is read-only. A token carrying only read_api and read_repository connects successfully and reads your merge requests, but every attempt to post a review comment fails. Use api unless you deliberately want a read-only connection.
A group access token scoped to the group that owns your projects is usually the least fiddly choice: one token, one webhook per project, and it survives people leaving.

​
Connect GitLab

1

Open the source-control connections

In Ankra, go to AI → Settings → Connections and find Source control & AI review → GitLab.
2

Fill in the credential

  • Credential name - optional, and worth setting when you connect more than one instance.
  • Instance URL - leave empty for https://gitlab.com, or give the base URL of your self-managed instance, for example https://gitlab.my-company.com.
  • Access token - the token from above.
Press Connect. Ankra validates the token against the instance before storing it, so a rejected token fails here rather than silently later.
3

Copy the webhook URL and secret

The credential now shows a webhook URL of the form https://platform.ankra.app/webhooks/gitlab/<credential-id> and a secret.
The secret is shown once, when the credential is created or its secret is regenerated. Copy it before you leave the page. If you lose it, regenerate it - you cannot read it back.
4

Register the webhook in GitLab

In the GitLab project, go to Settings → Webhooks → Add new webhook:
  • URL - the webhook URL you copied.
  • Secret token - the secret you copied.
  • Trigger - tick Merge request events, Comments, Push events, and Tag push events.
Save, then press Test → Merge request events. A 200 means Ankra accepted the delivery.Repeat per project, or add the hook once at group level under Settings → Webhooks to cover every project in the group.
5

Turn on what you want

A fresh connection does nothing. Switch on AI review and Mention replies on the credential’s row, or on a rule for individual projects. See AI code review for what each switch does.

​
Which events do what

Every delivery is authenticated by comparing the X-Gitlab-Token header against the credential’s stored secret. A delivery with the wrong secret is rejected with 401; an event kind Ankra does not use is answered 200 so GitLab keeps the hook enabled.

​
Rotate the webhook secret

Regenerate secret on the credential mints a new one and shows it once.
The old secret stops working immediately. GitLab keeps delivering with it until you update the hook, and those deliveries are rejected, so update the webhook in GitLab straight away.

​
Repository paths and subgroups

Repository rules key on the project’s full path, lowercased, including every subgroup - my-group/my-subgroup/my-project. Up to 20 levels of nesting are supported. The path is what appears in the project’s URL after the instance host.

​
Disconnect

Disconnect on the credential’s row removes it. AI reviews, mention replies, and GitOps sync through that credential all stop, and the webhook deliveries start being rejected. Remove the hook in GitLab too, so it stops retrying.

​
Troubleshooting