Almost every non-interactive action in GitLab is authenticated by a token, and a single leaked personal access token can read, push and publish across every project its owner can reach. GitLab issues more than a dozen token types, each with its own prefix, scopes, owner and expiry behaviour, and the safe choice for a given job is rarely the one developers reach for first. This guide goes deeper than our GitLab Security Guide on one subject: personal, project, group and deploy tokens, plus the job, runner and service account credentials that should replace many of them. It covers issuance, scopes, privileged tokens, rotation, revocation and logging. It is written for GitLab administrators, platform and DevSecOps engineers, and the security teams who own NHI governance for source code and CI/CD.
This is an independent guide from NHI Mgmt Group, based on GitLab's public documentation as of November 2026. It is not sponsored or reviewed by GitLab. Product features change, so confirm settings against GitLab's current documentation.
Key takeaways
- Pick the narrowest credential that does the job. GitLab's own order of preference for CI/CD is the job token first, then project tokens, then group tokens; personal access tokens should not sit in CI/CD variables.
- Expiry is on by default, but not everywhere. Personal, project and group tokens default to 365 days and require an expiry date from GitLab 17.3, but deploy tokens, feed tokens and incoming email tokens do not expire unless you act.
- Scopes matter more than the token type. A project token with
apiand the Owner role is far more dangerous than a personal token withread_repository; review scope and role together. - Revoke at GitLab, not in Git. Deleting a committed token from history does nothing; only revocation or rotation stops it working, and leaked tokens stay valid for years otherwise.
- Use the prefixes. Fixed prefixes such as
glpat-,gldt-andglrt-make scanning reliable, so keep the default prefix and turn on push protection and pipeline secret detection.
How identity and access work in GitLab
GitLab has three kinds of identity that matter for tokens: human users, who own personal access tokens and the feed and incoming email tokens; bot users, which GitLab creates automatically for every project or group access token; and service accounts, which are non-human users created on purpose and authenticated with personal access tokens. A token never has more access than the identity behind it. A personal access token inherits its owner's memberships and role in every group and project, which is why it is the hardest token to scope safely.
Project and group access tokens are different: each one creates a bot user named project_{project_id}_bot_{random_string} or group_{group_id}_bot_{random_string}. The bot is a member of that one project or group (and inherits into a group's subgroups and projects), cannot be added anywhere else, does not use a licensed seat, and takes the role chosen when the token was created. On GitLab.com these tokens need a Premium or Ultimate subscription; on GitLab Self-Managed and GitLab Dedicated they are available with any licence.
Token types at a glance
| Token | Prefix | Bound to | Default lifetime | API / registry / Git | Who can create |
|---|---|---|---|---|---|
| Personal access token | glpat- | A human user or service account | 365 days if no date set; maximum 365 by default | Yes / Yes / Yes | The user; instance or group administrators for service accounts |
| Impersonation token | glpat- | A specific user, issued by an administrator | Expiry required by default | Yes / Yes / Yes | Instance administrators only |
| Project access token | glpat- | A project bot user | 365 days if no date set | Yes / Yes / Yes (one project) | Maintainer or Owner of the project |
| Group access token | glpat- | A group bot user | 365 days if no date set | Yes / Yes / Yes (group and descendants) | Owner of the group |
| Deploy token | gldt- | A project or group, no user | No expiry unless a date is set | No / Yes / Yes (HTTP only) | Project Maintainer or Owner; group Owner |
| CI/CD job token | glcbt- | One running job | The duration of the job | Limited endpoints / Yes / Yes | Generated automatically |
| Runner authentication token | glrt- (glrtr- if created via a registration token) | A runner | Until rotated or revoked | Runner registration and job fetching only | Created with the runner |
| Pipeline trigger token | glptt- | A project | Until revoked | Triggers pipelines | Created in the project CI/CD settings |
| Feed token | glft- | A user | Does not expire | RSS and calendar feeds only | One per user, automatically |
| Incoming email token | glimt- | A user | Does not expire | Creates issues and merge requests by email | One per user, automatically |
| Agent for Kubernetes token | glagent- | A registered cluster agent | Until revoked or reset | Agent connection to GitLab | Created at agent registration |
Also add gloas- (OAuth application secret), glsoat- (SCIM) and glwt- (workspace) to scanners. Feed tokens matter despite their narrow purpose: anyone holding one can view the user's feed, including confidential issues.
Expiry rules
- Default and maximum: personal, project and group tokens default to 365 days and expire at midnight UTC on the expiry date. Administrators on GitLab 17.6 and later can change the maximum; a feature flag,
buffered_token_expiration_limit, raises it to 400 days (not available on Dedicated). - Require expiration dates: enabled by default since GitLab 17.3 for personal, project, group and impersonation tokens. Service account tokens follow a separate setting,
service_access_tokens_expiration_enforced; if it is off, a service account token can be created with no expiry at all. - Maximum lifetime enforcement: on Self-Managed and Dedicated (Ultimate), setting Maximum allowable lifetime for access tokens (days) revokes existing tokens with no expiry or a longer lifetime, three hours after the change.
- Notifications: a daily job at 01:00 UTC emails owners 60, 30 and 7 days before expiry (60 and 30 from 17.6). Personal tokens also have a calendar feed at
/-/user_settings/personal_access_tokens.ics. - No reactivation: expired and revoked tokens cannot be brought back. Revoked group and project tokens are deleted after 30 days by default (
inactive_resource_access_tokens_delete_after_days).
Admin roles and privileged access
Token privilege comes from three things combined: the identity's role, the token's scopes, and administrative capabilities that only some tokens can carry. The scopes below are the ones that turn a token into an administrative credential.
| Scope or capability | Available to | What it allows | Control |
|---|---|---|---|
sudo | Personal tokens of administrators | API actions as any user | Ban outside break-glass procedures; alert on creation |
admin_mode | Personal tokens of administrators (Self-Managed) | API access while Admin Mode is active | Issue only to named administrators, short expiry |
| Impersonation tokens | Created by administrators | Act as a specific user through the API | Record a ticket for each; review monthly |
api | Personal, group, project | Full read and write API, including registries; for personal tokens, full Git over HTTP | Replace with read_api or narrower scopes wherever possible |
create_runner, manage_runner | Personal, group, project | Create and manage runners in scope | Restrict to platform automation; runners execute code with secrets |
k8s_proxy | Personal, group, project | Kubernetes API calls through the GitLab agent | Treat as cluster access; tie to cluster RBAC review |
self_rotate | Personal, group, project | The token can rotate itself, but no other token | Useful for automated rotation; pair with short lifetimes |
| Owner role on a group token | Group access tokens | Owner rights over the group and all descendants | Use Developer or Maintainer unless ownership is the job |
- Restrict who can mint bot tokens: in a top-level group, clear Users can create group access tokens and project access tokens in this group under Settings, General, Permissions and group features. The setting covers subgroups and projects, but existing tokens stay valid until they expire or are revoked, so pair it with a clean-up.
- Remember internal visibility: GitLab notes that a project token created by an internal user can access all Internal-visibility projects. Check your visibility model before assuming a project token is confined to one project.
- Keep administrators few: issue
admin_modetokens only for administration, with short expiry. See the Privileged Access Management Guide.
Integrations, API tokens and service accounts
Most token risk comes from automation built with whatever credential the engineer already had. Check this table before issuing anything new.
| Need | Use | Avoid | Why |
|---|---|---|---|
| A pipeline calling the GitLab API, registry or another project | CI_JOB_TOKEN with the CI/CD job token allowlist | A personal token in a CI/CD variable | Job tokens exist only for the job and need no storage |
| A pipeline deploying to a cloud or reading secrets from a vault | OIDC ID tokens (id_tokens) federated to the cloud or vault | Static cloud keys in variables | No long-lived secret to leak; see the CI/CD Pipeline Identity Security Guide |
| Pulling images or packages from a cluster or build host | Deploy token with read_registry or read_package_registry | A personal token with api | Deploy tokens cannot call the API and carry no user |
| Cloning one repository from a server | Deploy key (SSH, read-only) or deploy token with read_repository | A maintainer's personal token | Survives the maintainer leaving; scoped to the repository |
| A bot that comments on merge requests in one project | Project access token, Reporter or Developer role, api only if needed | Group token with Owner | Blast radius is one project |
| An integration that spans many groups | Group service account with a personal token, invited only where needed | A human's personal token | Clear ownership, no seat, survives staff changes |
Job tokens and the allowlist
GitLab generates CI_JOB_TOKEN for every job and revokes it when the job ends. It has the access of the user who triggered the pipeline but reaches only listed endpoints: full access to badges, deployments, environments, packages, releases and release links, limited access to branches, commits, files, merge requests, notes, pipelines and tags, and no GraphQL. The CI/CD job token allowlist (under Settings, CI/CD, Job token permissions) controls which other projects may use their job tokens against yours. By default it contains only the project itself. Adding a group admits every current and future project in it, so add projects individually where you can (limits are 200 groups and 200 projects). The authentication log on the same page lists other projects that authenticated with a job token; download the CSV for more than 100 events.
Deploy tokens
Deploy tokens have a username (default gitlab+deploy-token-{n}) and a password-style token, and the scopes read_repository, read_registry, write_registry, read_package_registry, write_package_registry, read_virtual_registry and write_virtual_registry. They work over HTTP only, not SSH, and not with the public API apart from some package registry endpoints. A token named exactly gitlab-deploy-token is exposed to CI/CD jobs as CI_DEPLOY_USER and CI_DEPLOY_PASSWORD, which is convenient but means every job in the project can read it. Because deploy tokens never expire by default, always set a date; owners and maintainers then receive reminders at 60, 30 and 7 days.
Service accounts
Service accounts are non-human users that cannot sign in to the UI and authenticate with personal access tokens. They exist at three levels: instance (created by administrators), group (a top-level group's account can be invited anywhere on the instance; a subgroup's account is limited to its descendants) and project. They do not use a seat, are always external users, and receive no notification email unless you add a custom address, so set one to a team mailbox or expiry warnings go nowhere. See the Service Account Security Guide.
Rotation and revocation
Rotation creates a new token with the same scopes and makes the old one inactive at once, so write the new value to the secrets manager and restart the consumer in the same automated step (the self_rotate scope lets a token rotate itself). Revocation is immediate and permanent; afterwards, review what the token did using last-used data and logs. Reset feed and incoming email tokens from user settings if they may have leaked. See the Secrets Rotation Runbook Template.
Logging and detection
No single source covers every token type, so combine these four.
| Source | What it shows | Tier and notes |
|---|---|---|
| Token last used and IP addresses | Last-used date (updated every 10 minutes after Git or API use) and the last five distinct source IPs (updated every minute) | All tiers; shown on the token pages |
| Credentials inventory | Personal, project and group tokens, SSH keys and (Self-Managed) GPG keys, with owner, scopes, expiry and revocation dates; revoke from the same page | Ultimate; Admin area, Access, Credentials, or a top-level group's Secure, Credentials page for enterprise users |
| Audit events | For example personal_access_token_created, personal_access_token_revoked, deploy_token_created, deploy_token_revoked, group_deploy_token_created, cluster_agent_token_created and secure_ci_job_token_policies_updated | Premium and Ultimate; streaming to a SIEM needs Ultimate |
| Job token authentication log | Which other projects used job tokens against a project | Per project, CSV export |
- Alert on: creation of tokens with
sudo,admin_modeorapi; any new impersonation token; group tokens with the Owner role; deploy tokens without an expiry; changes to job token allowlists; and secret push protection skips. - Hunt for: tokens used from IP ranges outside your runners and offices, tokens unused for 90 days, and bulk repository clones by a single token, which maps to MITRE ATT&CK T1213.003 Code Repositories.
- Detect leaks early: secret push protection (Ultimate) blocks pushes containing secrets in the pre-receive hook, and pipeline secret detection scans after the fact. Skips via the
secret_push_protection.skip_allpush option or a[skip secret push protection]commit message are audited (events added in GitLab 19.3). - Automatic revocation: on GitLab.com, a personal access token found by pipeline secret detection in a public project is revoked automatically and the owner emailed. On Self-Managed and Dedicated an administrator must enable
secret_detection_token_revocation_enabled.
Metrics that show it is working
- Percentage of active tokens with an expiry of 90 days or less.
- Count of personal access tokens referenced in CI/CD variables (target: zero).
- Count of tokens carrying
sudo,admin_modeor Owner-role bot users, each with a named owner. - Deploy tokens without an expiry date (target: zero).
- Mean time from leak detection to revocation, measured from secret detection findings.
Hardening baseline
- Inventory first: export tokens from the credentials inventory (or the token APIs on lower tiers) and tag each with owner, consumer, scopes and role. This shows what each later step will break.
- Enforce expiry: keep Require expiration dates for new tokens on, turn on
service_access_tokens_expiration_enforced, and on Self-Managed set a maximum lifetime (for example 90 days for write scopes). Announce the change, because enforcement revokes non-compliant tokens three hours later. - Move CI to job tokens and OIDC: pilot one product team, replace personal tokens in CI/CD variables with
CI_JOB_TOKENand allowlists, and federate cloud access with ID tokens. Keep the old variable masked and protected for one release as a rollback path, then revoke the token behind it. - Turn on detection: enable secret push protection per project (or for a group through the API), pipeline secret detection, and automatic revocation on Self-Managed.
- Keep the default prefix: GitLab warns that a custom personal access token prefix may be missed by client-side detection, push protection and pipeline secret detection.
- Harden runners: long-lived deploy and runner tokens are only as safe as the runner host. Avoid Docker privileged mode on reused machines and the shell executor where jobs share a machine. See the CI/CD Security Guide.
- Review quarterly: revoke unused tokens and confirm every service account and bot has an owner.
Framework mapping
| Control area | NIST SP 800-53 Rev 5 | NIST CSF 2.0 | MITRE ATT&CK |
|---|---|---|---|
| Token lifetime, rotation and revocation | IA-5 Authenticator Management | PR.AA-01 | T1528 Steal Application Access Token |
| Scopes, roles and bot token creation | AC-6 Least Privilege; AC-2 Account Management | PR.AA-05 | T1098.001 Additional Cloud Credentials |
| Service account and bot ownership | IA-4 Identifier Management; AC-2 | PR.AA-01 | T1078.004 Cloud Accounts |
| Leaked tokens in code and config | IA-5 | PR.AA-01 | T1552.001 Credentials In Files |
| Token use monitoring and audit streaming | AU-6 Audit Record Review, Analysis, and Reporting | DE.CM-03, PR.PS-04 | T1213.003 Code Repositories; T1550.001 Application Access Token |
Common misconfigurations
- Tokens left in reachable files: a token in an exposed configuration file can unlock source code holding further credentials. Rotate everything found alongside it.
- Treating the repository as a vault: keep customer tokens and connection strings in a secrets manager, not in repositories and reports.
- Deleting instead of revoking: the GitLab Public Repositories Secrets Study 2025 found 406 valid GitLab tokens among 17,430 live secrets in public GitLab projects, some committed years earlier. A token removed from a file keeps working until it is revoked.
- Personal tokens as pipeline credentials: a maintainer's
apitoken in a CI/CD variable gives anyone who can edit the pipeline that maintainer's reach across all their projects. - Wide allowlists: adding a whole group to a job token allowlist, or disabling the allowlist on Self-Managed for "testing" and never re-enabling it, lets unrelated pipelines reach the project.
Practitioner checklist
- Inventory every personal, project, group, deploy and service account token with owner, scopes, role and expiry.
- Keep expiry enforcement on, enforce it for service accounts, and set a maximum lifetime on Self-Managed.
- Remove personal access tokens from CI/CD variables; use
CI_JOB_TOKEN, allowlists and OIDC ID tokens instead. - Restrict creation of group and project access tokens at the top-level group.
- Alert on
sudo,admin_mode, impersonation and Owner-role bot tokens, and stream audit events to the SIEM. - Set expiry dates on every deploy token and avoid the
gitlab-deploy-tokenname unless every job needs it. - Enable secret push protection, pipeline secret detection and automatic revocation; keep the default token prefix.
- Rotate through the API with consumers updated in the same step, and revoke immediately on any exposure.
- Revoke tokens unused for 90 days and review owners quarterly.
Standards and references
- GitLab Docs: GitLab token overview
- GitLab Docs: Access token scopes
- GitLab Docs: Personal access tokens
- GitLab Docs: Deploy tokens
- GitLab Docs: GitLab CI/CD job token
- GitLab Docs: Service accounts
- GitLab Docs: Credentials inventory
- MITRE ATT&CK: T1528 Steal Application Access Token
Related NHI Mgmt Group resources: GitLab Security Guide · CI/CD Pipeline Identity Security Guide · OWASP NHI Top 10 NHI7 Long-Lived Secrets Guide · OWASP NHI Top 10 NHI2 Secret Leakage Guide · Slack Tokens Security Guide