GitLab

PullApprove works with GitLab.com and self-managed GitLab instances.

1. Create an Access Token

PullApprove needs an API token to read your repositories, post commit statuses, and manage merge request comments. We recommend creating a service account so that PullApprove activity appears as a dedicated bot user rather than a team member.

Create the service account

1. Go to your group → Settings → Service accounts
2. Click Add service account and fill in:
   • Name: PullApprove5
   • Username: pullapprove5-yourgroup (e.g. pullapprove5-acme)
3. Click Create

Create an access token

1. Click on the newly created service account to open its token page
2. Click Add new token and fill in:
   • Token name: PullApprove5
   • Scopes: check api
3. Click Generate token and copy the token value — you'll need it in the next step

Add the service account to your group

1. Go to your group → Manage → Members
2. Click Invite members
3. Search for the service account username (e.g. pullapprove5-acme) and add it with the Maintainer role

Service accounts don't consume a seat and can't sign in to the GitLab UI. Commit statuses and MR comments will appear as coming from the service account, keeping PullApprove activity visually distinct.

How you manage the API token is ultimately up to you — any token with the api scope and Maintainer access will work, including Group Access Tokens or Personal Access Tokens. We recommend service accounts because they don't consume a seat, provide a clear bot identity, and won't break if a team member leaves.

2. Find Your Group ID

You can find the Group ID on your group's main page in GitLab — it's displayed below the group name, or under Settings → General.

3. Connect the Group

1. Log in to PullApprove with your GitLab account
2. Go to Connect and choose GitLab
3. Enter your Group ID, Access Token, and choose a Webhook mode
4. Click Connect

PullApprove will sync your group's repositories and register webhooks based on your chosen mode.

4. Webhooks

PullApprove uses webhooks to respond to merge request events in real time. During setup you'll choose a webhook mode:

Group webhook (GitLab Premium/Ultimate) — a single webhook is registered on your GitLab group, covering all current and future projects automatically.

Project webhooks (GitLab Free) — a webhook is registered on each project individually. PullApprove registers these automatically during repo sync for every project in the group that the API token has access to. When new projects are added to the group, sync your repos in PullApprove to register webhooks on them.

You can change the webhook mode at any time from your organization's settings in PullApprove.

5. Enable Repos and Add Config

Once connected, enable individual repos in PullApprove, then add a CODEREVIEW.toml file to each repo.

6. Require PullApprove Before Merge

PullApprove reports its review status as a commit status on each merge request. This appears as a job in an external stage within the merge request's pipeline widget.

To prevent merging until PullApprove's status passes, enable "Pipelines must succeed" in your project or group settings:

1. Go to Settings → Merge requests → Merge checks
2. Enable "Pipelines must succeed"

This requires all pipeline jobs — including PullApprove's commit status — to pass before a merge request can be merged. Note that this is all-or-nothing: there is no way to require only specific statuses on GitLab Free/Premium. If you have CI jobs that you don't want to block merges, mark them with allow_failure: true in your .gitlab-ci.yml.

Note: GitLab Ultimate offers a separate External Status Checks feature with per-check granularity, but PullApprove does not use that mechanism — it uses standard commit statuses which work on all GitLab tiers.

GitLab Limitations

Most PullApprove features work identically on GitHub and GitLab. A few features are not available on GitLab due to platform differences:

Feature	GitHub	GitLab	Notes
reviewed_for	✅	❌	Requires review body text, which GitLab approvals don't have
Checklists	✅	❌	Requires review submission through PullApprove UI
Insights (timeline)	✅	Partial	Time-to-merge works; detailed timeline events are not yet available