How to rotate GitLab access tokens

Create a new access token with the same scopes, and for a project or group token the same role, move every pipeline and script to it, and revoke the old token once nothing uses it. Two tokens can be active together, so the switch costs no downtime. GitLab's built-in Rotate action is faster but has no overlap: it creates a token with the same permissions and scope, and the original becomes inactive immediately (GitLab docs). Keep Rotate for leaks, or for tokens with a single consumer you can update in the same minute.

Crunu doesn't create, rotate or revoke GitLab tokens. It works out which GitLab values a departing person received, stores the replacement as a new version of the environment, and hands it to the jobs that need it.

Which GitLab token you hold

Personal, project and group access tokens all start with glpat-. Only the personal token prefix can be configured, so on a self-managed instance it may differ. Other credentials have their own prefixes, which helps when you sort a list of leaked values: gldt- for deploy tokens, glcbt- for CI/CD job tokens, glrt- for runner authentication tokens and glptt- for trigger tokens (token overview).

• Personal access token. Acts as a person with the scopes you pick. GitLab's documentation now labels these legacy personal access tokens and links to a newer fine-grained type.
• Project access token. GitLab creates a bot user for it, named like project_{project_id}_bot_{random_string}, and the bot gets the role and scopes you choose. Creating one needs the Maintainer or Owner role, and on GitLab.com a Premium or Ultimate subscription (project tokens).
• Group access token. The same idea at group level, for automation that spans several projects.

For pipelines and integrations, project or group tokens survive staff changes better than a person's token, because no human account sits behind them.

Expiry forces a reissue anyway

By default every new token must have an expiry date, and that date can be at most 365 days ahead; leave it blank and GitLab sets 365 days. On GitLab 17.6 and later an administrator can change the maximum, and a 400-day limit exists behind a feature flag that is off by default. Tokens expire at midnight UTC and can't be reactivated. GitLab emails the owner 7 days before expiry, and since 17.7 also 30 and 60 days before; in 17.6 those earlier notices were behind a feature flag. For project tokens, the mail goes to members with the Maintainer or Owner role.

In practice every GitLab token gets reissued at least once a year, so the steps below are worth making routine.

Reissue without downtime

Personal, project and group tokens can also be rotated through their own API endpoints, which suits a scheduled job. Remember that an API rotation behaves like the button: the previous token stops working at once.

When to reissue a GitLab token

• A departure. Personal tokens belong to the person. GitLab's docs say the tokens of deleted or blocked enterprise users are revoked automatically; for anyone else, check their tokens yourself. Everything they could read is a different matter: project and group tokens, a shared bot's personal token, trigger tokens. In Crunu, removing the person produces a reissue checklist of the values they received, by name.
• A leak. Rotate or revoke at once and accept the short break. GitLab keeps both versions of a rotated token for its audit records.
• An expiry email. Treat the 30-day notice as the start of a planned reissue, not a reminder to extend.

GitLab's own advice helps here too: name tokens consistently so you can judge the impact of rotating or revoking each one, and review active tokens of every type regularly. What to rotate when a developer leaves covers the full order of work, and the offboarding checklist builds the list for your stack. Crunu's environment history then shows when each GitLab value was replaced and by whom, while the token changes themselves stay in GitLab.