GitLab integration
GitLab access changes,
recorded and verifiable.
Governax records access changes from GitLab into a tamper-evident ledger: group and project membership and role changes, custom admin roles, access tokens, deploy keys and visibility changes. It polls the group audit events API every 10 minutes with a read-only group access token you create, and appends each change to a per-entity, SHA-256 hash-chained record.
What lands in the ledger
What does Governax record from GitLab?
Membership
Members added, including through SAML group sync, members removed, and access level changes.
Custom admin roles
Custom admin roles assigned to or removed from a user, and custom roles defined.
Tokens
Personal access tokens, deploy tokens and group deploy tokens created and revoked.
Deploy keys
Deploy keys added and removed.
Visibility
A group or project made Public, or made Internal or Private.
Not captured: A membership update that only changed the expiry date, SAML group link configuration, and the many GitLab audit event types that do not change who can access what are not recorded. Events keep their GitLab scope, so a project-level change is distinguishable from a group-level one.
How does the GitLab connection work?
You need a group on GitLab.com with a paid Premium or Ultimate subscription. A trial does not count: the group audit events API is a Premium and Ultimate feature, and group access tokens are only available on a paid subscription. Self-managed and GitLab Dedicated instances are not supported.
Create a group access token with the Owner role and the read_api scope only, then enter the group path and the token in Governax. Governax checks that the token can see the group, that its role is Owner, and that the group can serve audit events, and writes nothing until all three pass.
Governax polls every 10 minutes. The first poll backfills the previous 7 days, and each later poll re-reads a 1-hour trailing window. GitLab tokens expire after at most 365 days; reconnect the same group with a fresh token and the poll position is kept.
The baseline snapshot on connect
When you connect, Governax reads the group's current member list, inherited members included, and records each member as an access.baseline_observed event with their access level by name and their membership expiry, if any. The snapshot covers group-level membership only; project-level changes are captured from connect time forward.
Scope
What Governax does not do
Governax is a system of record, not a control plane. It records GitLab access changes after they have happened; it does not grant, revoke or block anything.
It never writes to GitLab
The token needs read_api only, which gives read access and nothing to write with. Governax only reads.
It does not revoke its token
The token belongs to your group. After disconnecting, delete it under Group settings, then Access tokens.
It does not block changes
Audit events are read after the change has happened. Governax records changes; it cannot prevent one.
How this helps with audits
When an auditor asks who had access in GitLab and when it changed, the answer is a filtered view of the ledger rather than a folder of screenshots. Approvals are recorded for access requests raised with /governax in Slack. Filters combine tool, event type, actor and a date range, and the date range matches when the change happened in GitLab, not when Governax recorded it.
Because a baseline snapshot is taken when you connect, the record starts from who already had access, not only from the changes that followed.
Every event is appended to the entity's SHA-256 hash chain, and database triggers reject every update and delete. Anyone given read access to the entity, an auditor included, can re-run verification, which recomputes every hash and checks every link.
Verification proves that what was recorded has not changed. It cannot prove that everything that happened was recorded. Governax records the evidence; it does not map it to controls, perform the audit or export reports.
Questions
GitLab integration FAQ
Which GitLab tiers are supported?
A group on GitLab.com with a paid Premium or Ultimate subscription. The group audit events API is a Premium and Ultimate feature, and group access tokens are only available on a paid subscription, so a trial does not count and a Free group is refused at connect time.
Is self-managed GitLab supported?
No. Only groups on GitLab.com are supported today; self-managed and GitLab Dedicated instances are not. Subgroups are fine.
Why does the token need the Owner role?
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, which Governax cannot tell apart from a complete feed, so Governax checks the role directly and refuses anything below Owner.
Does Governax need write access to GitLab?
No. The token needs the read_api scope only, which gives read access to everything Governax needs and nothing to write with. Do not grant the api scope.
What happens when the GitLab token expires?
GitLab allows tokens of up to 365 days. When the token lapses, ingestion for the group stops until you reconnect the same group with a fresh token. The poll position is kept, so nothing is re-imported.
Other integrations
- SlackWorkspace membership, channels, external sharing and access requests
- GitHubOrganisation, team and repository access, branch protection
- OktaUsers, groups, app assignments and admin roles
- Google WorkspaceUsers, groups, admin roles and third-party app grants
- AWSIAM users, roles and policies, read from CloudTrail
- Microsoft Entra IDDirectory roles, group membership and app consent
Connect GitLab and start the record.
Read the GitLab setup guide, compare plans, or start free with one entity.