Skip to main content
AI Review integrates with GitLab by receiving webhook events from your GitLab instance and posting review comments back on merge requests. This page walks you through setting up the connection.

​
Prerequisites

Before you begin, gather the following:
  • GitLab base URL — https://gitlab.com for GitLab SaaS, or your private instance address (e.g. https://gitlab.example.com).
  • Access token — A GitLab personal access token or project access token.
  • Webhook secret — A secret string you choose; it will be used to verify that webhook payloads come from GitLab.
The access token must have sufficient permissions to read projects and post comments on merge requests. For a personal access token, the api scope is required. Without the correct scope, project sync and comment posting will fail.

​
Setup

1

Add a platform configuration

In the AI Review dashboard, go to Platform Configs and click Add.Fill in the fields:
FieldValue
NameA label for this connection (e.g. GitLab SaaS)
Platform typeGitLab
Base URLYour GitLab instance URL
Access tokenYour GitLab access token
Webhook secretThe secret string you chose
Save the configuration. The platform config will appear in the list with its status.
2

Sync projects

Go to Project Management and click Sync.Select the platform configuration you just created and start the sync. AI Review will fetch all accessible projects from your GitLab instance and import them into the project list.
If the sync fails, verify that the base URL is reachable from the AI Review server and that the access token has the correct permissions.
3

Enable auto-review on a project

In Project Management, locate the project you want to enable and open its settings.Turn on Auto Review. You can also configure:
  • The AI configuration to use for this project.
  • Review templates.
  • Default reviewers and assignees.
4

Configure the GitLab webhook

In your GitLab project, go to Settings → Webhooks and add a new webhook.
URL:    https://<your-ai-review-host>/api/webhook/gitlab
Secret: <the webhook secret you set in the platform config>
Enable at minimum the Merge request events trigger. Click Add webhook.AI Review reads the token from the X-Gitlab-Token request header to authenticate each delivery.

​
Supported events

AI Review processes the following GitLab webhook events:
object_kindactionBehavior
merge_requestopenTriggers auto-review and applies auto-assignments
merge_requestreopenTriggers auto-review and applies auto-assignments
merge_requestupdateTriggers auto-review (see filtering note below)
note—Triggers manual review when the comment body starts with /ai-review
All other event types and actions are acknowledged with HTTP 200 but are not processed.

​
Assignment-only update filtering

For update events, AI Review inspects the changes field of the payload. If the only changed keys are assignee_id, assignee_ids, assignees, reviewer_ids, updated_at, or updated_by_id, the event is ignored. This prevents a review from being re-triggered every time an assignee or reviewer is changed.

​
Review gate

Receiving a webhook event does not unconditionally start a review. Before queuing a review job, AI Review checks:
  1. The project exists in the system (was synced).
  2. The project has review enabled.
  3. Auto-review is turned on for the project (for automatic triggers).
  4. An AI configuration is available for the project.
  5. The platform configuration is complete and enabled.
If any check fails, the webhook returns HTTP 200 with a descriptive message and no review is queued.

​
Troubleshooting

Check the following in order:
  1. Webhook token mismatch — The X-Gitlab-Token header sent by GitLab must exactly match the webhook secret stored in the platform configuration. Re-enter the secret on both sides if you are unsure.
  2. Project not synced — The project must appear in Project Management. Run a sync if you recently added the project to GitLab.
  3. Project disabled — Open the project settings in AI Review and confirm that Auto Review is enabled.
  4. AI configuration missing — The project must have an AI configuration assigned. Go to the project settings and select or create an AI config.
  5. Platform configuration disabled — In Platform Configs, verify that the configuration is enabled.
  • Confirm the base URL is correct and the GitLab instance is reachable from the AI Review server.
  • Verify the access token has the api scope and has not expired.
  • Check that the token grants access to the projects you expect to import.
  • Confirm the webhook URL is reachable from GitLab (no firewall blocking outbound requests).
  • Check that the URL path is exactly /api/webhook/gitlab with no trailing slash.
  • Review the AI Review server logs for any errors returned during processing.
  • Verify the access token has permission to post notes on merge requests.
  • Check the AI Review server logs for errors from the GitLab API response.
  • Confirm the project’s AI configuration points to a working AI provider.

Build docs developers (and LLMs) love

Get started for freeTalk to us