GitLab
Proofroom reads one GitLab group (and its subgroups’ projects) with a read_api token and files three kinds of
evidence. It works with gitlab.com, GitLab Dedicated and self-managed GitLab. Add it on Integrations → Catalogue →
GitLab → Connect.
What each collector shows
| Collector | Kind | Default cadence | What it shows | Suggested controls |
|---|---|---|---|---|
| Reviewed merges | window | monthly | Merge requests merged in the window, per project, with the author, who merged and who approved. Flags No approval and Self-approved (approved only by the author). | PCI DSS 6.2.3, 6.5.1; SOC 2 CC8.1 |
| Branch protection | snapshot | quarterly | Each project’s default branch: protected or not (wildcard rules count), who can push, whether force pushes are allowed, and the approvals required (Premium or Ultimate). | PCI DSS 6.2.3; SOC 2 CC8.1 |
| Members and 2FA | snapshot | quarterly | Every direct and inherited member with their role and whether two-factor authentication is on, and whether the group requires it. | PCI DSS 8.3.1; SOC 2 CC6.1 |
Create the token
GitLab shows members’ two-factor status only to group Owners (GitLab 19.4 or later), so the token must belong to an Owner. Reading the rest needs only Reporter (merge requests) and Maintainer (protected branches).
- A group access token (gitlab.com Premium or Ultimate, or any self-managed licence): in the group, Settings → Access tokens → Add new token, role Owner, scope read_api.
- Or a personal access token of an Owner: User settings → Access tokens, scope read_api. A dedicated service user is best.
read_api keeps every call read-only. Tokens expire after at most a year; renew before then.
Connect
| Field | Value |
|---|---|
| GitLab address | https://gitlab.com (default), or your self-managed or Dedicated address |
| Token | From above |
| Group | The group’s full path, such as example-group |
| Projects | Paths within the group, one per line; empty means every non-archived project |
A self-managed GitLab inside your network must be reachable over https from the server Proofroom runs on. If GitLab limits access by address, allow that server’s outbound address (operations §12).
Known limits
- Approval rules need GitLab Premium or Ultimate and, for the token, the Developer role or higher in the project; otherwise required approvals show as —. GitLab gives the same refusal for both, so Proofroom checks the token’s own role in the project and the note says which applies (or that it could be either, when GitLab does not show the role).
- Without the Owner role (or before GitLab 19.4), Members and 2FA fails with a message rather than guessing.