GitLab

On this page

Before you start
Why the plan matters
Creating the group access token
Connecting
The baseline snapshot
How polling works
Events captured
What is deliberately dropped
Disconnecting
Troubleshooting

GitLab connects with a group path and a group access token you create, rather than an OAuth redirect. Governax then polls the group's audit events every ten minutes. It is entirely self-service, but it has a plan requirement that is worth checking before you start.

Before you start#

What you need
Item	Detail
A group on GitLab.com	Self-managed and GitLab Dedicated instances are not supported. Subgroups are fine.
A paid Premium or Ultimate subscription on that group	Not a trial. See the next section for why this is two requirements rather than one.
The Owner role on the group	You need it to create the token, and the token itself must carry it.
Entity operator access in Governax	Connecting and disconnecting need operator grade on the entity.

Why the plan matters#

The only GitLab feed that reports who joined, who left and whose role changed is the group audit events API, and it is a Premium and Ultimate feature. On GitLab Free it is not reachable at all, and no other feed, webhooks included, carries membership or permission changes. A Free group is therefore refused at connect time rather than left half-working.

Creating the group access token#

Open the group, then Settings, then Access tokens
Choose Add new token.
Set the role to Owner
This is a correctness requirement, not a convenience. A token with a lower role is not refused by GitLab's audit endpoint; it receives a normal response narrowed to that principal's own actions. Governax cannot tell that apart from a complete feed, so it checks the role directly and refuses anything below Owner rather than connect over a ledger that looks complete but is not.
3
Tick the read_api scope only
```
read_api
```
Read access to everything Governax needs, and nothing to write with. Do not grant api, which includes write access Governax never uses.
Choose an expiry and note it down
GitLab allows up to 365 days and does not support tokens that never expire. When the token lapses, ingestion for this group stops until you reconnect with a fresh one, so put the date somewhere you will see it.
Create it and copy the value
GitLab shows the token only once.

Connecting#

Open the entity, then Integrations, then GitLab, and fill in two fields:

The connect form
Field	What to enter
Group path	Whatever follows gitlab.com/ when you open the group, such as your-group or your-group/subgroup. A full group URL, a settings-page URL with its /groups/ and /-/ segments, and stray slashes are all accepted and reduced to the path. The group's display name is not the path and is not accepted.
Access token	The token from the previous section.

Governax then runs three checks, in this order, and nothing is written until all three pass:

Connect-time verification
Check	Proves
Resolve the group with the token	The path is right and the token is valid and can see the group.
Confirm the token's role is Owner	The audit feed will be complete rather than silently narrowed. Inherited Owner from a parent group counts.
Confirm the group can serve audit events	The group is on a plan that exposes the audit events API.

On success the token is encrypted at rest, the connection shows the group's full path, and polling begins. A GitLab group can be connected to one entity at a time; see Connecting a tool for the rules.

The baseline snapshot#

At connect time Governax reads the group's current member list, inherited members included, and records each one as an access.baseline_observed event carrying their access level by name (Guest, Reporter, Developer, Maintainer, Owner and so on) and their membership expiry, if any. This is what lets a later removal be a change from something.

How polling works#

GitLab polling behaviour
Property	Value
Interval	Every 10 minutes
First poll	Backfills the previous 7 days
Each subsequent poll	Re-reads a 1-hour trailing window, so a record that becomes queryable late is not missed
Per pass	Up to 5,000 events; anything beyond that is picked up on the next pass

Nothing is ever written to GitLab. Governax only reads.

Events captured#

GitLab event types by area
Area	Event types
Membership	`access.member_added` (including members added through SAML group sync, which are tagged in the payload), `access.member_removed`, `access.role_changed` when a member's access level changes
Custom admin roles	`access.admin_role_granted`, `access.admin_role_revoked` for a custom admin role assigned to or removed from a user, and `resource.role_created` when a custom role is defined
Tokens	`access.api_token_created`, `access.api_token_revoked` for personal access tokens, deploy tokens and group deploy tokens
Deploy keys	`access.deploy_key_added`, `access.deploy_key_removed`
Visibility	`access.repo_made_public` when a group or project becomes Public, `access.repo_made_private` when it becomes Internal or Private

Events carry the GitLab scope they belong to, so a project-level change inside the group is distinguishable from a group-level one, and the payload keeps GitLab's own event name alongside the ledger's.

What is deliberately dropped#

Records that produce no ledger event
Record	Why
A membership update that only changed the expiry date	GitLab reports a role change and an expiry change under the same event name. Only an update whose details say the access level changed is recorded as a role change, so extending someone's membership is never written up as a privilege change.
SAML group link configuration	Rules that map identity-provider groups to GitLab groups are configuration, not access. Individual users joining through those rules are captured as members added.
Everything else	GitLab documents several hundred audit event types, and only the ones above change who can access what. The rest are counted internally as coverage gaps rather than appended.

Disconnecting#

Reconnecting later keeps the previous poll position, so a reconnect with a fresh token does not re-import everything. That is also the path when a token expires: reconnect the same group with a new token.

Troubleshooting#

Common GitLab connection problems
Symptom	Cause and fix
GitLab rejected this token	The token is wrong, revoked or expired. Create a new one and try again.
That group was not found, or this token cannot see it	The path is wrong (a display name rather than a path is the usual cause), or the token was created on a different group.
This token needs the Owner role on the group	The token was created with Maintainer or lower. Create a new one with the Owner role.
This group is on GitLab Free	Audit events need a paid Premium or Ultimate subscription on the group. A trial does not unlock them.
Already connected elsewhere	The group is live on another entity or organisation. Disconnect it there first, or contact support if it belongs to an organisation you do not recognise.
Events stop and the last error mentions a 401 or 403	The token expired or was revoked. Reconnect the same group with a fresh token; the poll position is kept.
Nothing appears for 15 minutes	Expected. Up to 10 minutes of poll interval, plus the time GitLab takes to make an audit event queryable.

General connector behaviour is covered in Connecting a tool.