# 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](https://docs.gitlab.com/user/profile/service_accounts/) 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](https://docs.gitlab.com/user/group/settings/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](/login/) 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`](./config/index.md) file to each repo.
## 6. Require PullApprove Before Merge
PullApprove reports its review status as a [commit status](https://docs.gitlab.com/ci/ci_cd_for_external_repos/external_commit_statuses/) 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](https://docs.gitlab.com/user/project/merge_requests/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`](./config/scopes/reviewed-for.md) | ✅ | ❌ | Requires review body text, which GitLab approvals don't have |
| [Checklists](./config/scopes/checklist.md) | ✅ | ❌ | Requires review submission through PullApprove UI |
| Insights (timeline) | ✅ | Partial | Time-to-merge works; detailed timeline events are not yet available |
