GitLab Access

Effective date: 15 September 2026

Enji Guard connects to GitLab using an access token you create. This page explains what the token needs to be able to do, why each permission is there, what we add to your projects, and how to take access away.

GitLab works differently from GitHub, where we use an app installation instead — see GitHub App Permissions.

Which GitLab

Enji Guard works with GitLab Cloud and self-managed GitLab. You enter the host during setup, and we derive the API endpoint from it. A token belongs to one host — do not reuse a GitLab Cloud token on a self-managed instance or vice versa.

If you run self-managed GitLab, your repository data stays wherever your instance is; what we hold is described in the Privacy Policy.

What you give us

You create a personal access token in GitLab and paste it into Enji Guard. Currently the token must be created as a Legacy token.

That is a limitation on our side, not a preference. GitLab’s newer token formats are more granular, and more granular is better for you. Our connection flow does not support them yet. We will move when it does, and until then a Legacy token is what works — which means the scopes below are the only lever you have for narrowing access, so use them.

Alongside the token you give us a Git author name and email. These identify commits created by approved improvement workflows, so they appear in your repository history. They do not have to match the token owner — use whatever your GitLab rules allow.

Do not use your own everyday account for this. We recommend a service account, or a project or group access token, with the minimum access needed for the projects you want audited. A token made from a personal account carries everything that person can reach, stops working when they leave, and makes GitLab’s audit log attribute our actions to them by name.

We store the token encrypted, use it only to run the work you ask for, and delete our copy when you disconnect the project.

Who inside your team can use the token

At setup you choose:

• Save as personal — only the Guard user who added the token can see and use it.
• Attach to project — members of that Guard project can select repositories and manage the connection.

Pick deliberately: attaching to a project makes the connection survive one person’s absence, but widens who can act through it.

Put this next to the api scope below, because the two multiply. A token carries everything its owner can reach in GitLab — potentially a whole group, not only the projects you connected here. Attaching it to a Guard project lets every member of that Guard project act through it. So the people who can use the token may be a wider set than the people who were ever given that GitLab access, and Guard cannot narrow it for you.

Two ways to keep that in hand, and they work together: use a service account or a project or group token whose own access is already scoped to what Guard needs, and keep the connection personal unless shared management is worth more to you than the narrower blast radius.

Keeping the token alive

GitLab tokens expire. Enji Guard shows the connection state — connected, expires soon (within seven days), needs a new token, needs access, or unchecked — so you get warning before automation stops. You can rotate the secret with Update token without rebuilding the connection.

If the token expires, is revoked, loses project membership, or the host changes, runs stop and we report the failure. We do not go looking for another credential or another repository.

Scopes we need

Grant the smallest set that covers what you actually intend to switch on. A read-only audit does not need write access just because autofixes exist elsewhere in the product.

About the api scope

api is GitLab’s broadest scope. It grants full read and write access to everything the token’s owner can reach through the API — not only the projects you connect. GitLab does not offer a narrower scope that still lets us find projects and manage the webhooks described below, so api is what we have to ask for.

This is exactly why the token should not come from a personal account. With a service account or a project or group token, api is bounded by that account’s access. With your own account, it is bounded by everything you can reach in GitLab.

We use the token only for the projects you connect and only for the work described on this page.

Webhooks we add to your projects

Code review and run statistics need webhooks — GitLab notifying us when something happens in the project, rather than us polling. Enji Guard can create these webhooks for you automatically, but only if the token has a role of Admin, Maintainer or Owner on the project.

If the token has a lower role, Enji Guard runs in read-only mode: audits still work, but code review and statistics do not, because we never get told anything happened.

There is a genuine trade-off here: least privilege and full functionality pull in opposite directions. A Developer-role token is the safer choice and gives you audits; Maintainer or above gives you the full product.

Adding a webhook changes your project’s settings. That is a write to your project configuration, not just to code, and it is the one thing we do that is not obvious from “read and write your repository”.

What we are told about, and when

Reading your code happens when an audit runs. Separately, the webhooks subscribe to three kinds of GitLab event — the same three we use on GitHub — so that code review and activity tracking can respond to what happens between audits:

These arrive whenever they happen, not only while an audit is running. They carry the activity itself — who did it, the title and text of the issue, merge request or comment, and identifiers for the project and branch. They do not carry the contents of your code.

We are not subscribed to push events. We are not told when someone commits to your project. The one indirect exception: pushing to a branch with an open merge request updates that merge request, so we are told it changed — not what the commit contained.

We are also not subscribed to: pipeline or job events, tag pushes, releases, deployments, wiki edits, or feature-flag changes.

What Enji Guard does not do

• Merge merge requests. Not automatically, not on a setting — a person always merges.
• Deploy code.
• Write to branches you already have. Commits go only to branches we create for a change we are proposing, which then wait for your review.
• Reach projects you have not connected.
• Use your token for unrelated accounts or purposes.
• Keep your token in service after you disconnect. Our working copy is deleted; an encrypted copy may persist in backups for up to 7 days until they are overwritten on their ordinary cycle, and it is not used for anything in the meantime. Rotate the token in GitLab if you want certainty — that ends its usefulness immediately, whatever any backup holds.

Taking access away

Revoke the token in your GitLab settings — under your account, or the project or group it belongs to. Revoking cuts off access immediately, including our ability to reach anything through it.

Webhooks we created stay in your project settings until you remove them; deleting them is done in the project’s webhook settings. Reports and history already generated are handled as described on the Data Retention & Deletion page.