Join our Newsletter — 33% off our NHI Course
Home› Guides› GitLab Tokens Security Guide: Personal, Project, Group and…
Guide Non-Human Identity (NHI)

GitLab Tokens Security Guide: Personal, Project, Group and Deploy Tokens

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 8 November 2026 16 min read
On this page

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 api and the Owner role is far more dangerous than a personal token with read_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- and glrt- 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

TokenPrefixBound toDefault lifetimeAPI / registry / GitWho can create
Personal access tokenglpat-A human user or service account365 days if no date set; maximum 365 by defaultYes / Yes / YesThe user; instance or group administrators for service accounts
Impersonation tokenglpat-A specific user, issued by an administratorExpiry required by defaultYes / Yes / YesInstance administrators only
Project access tokenglpat-A project bot user365 days if no date setYes / Yes / Yes (one project)Maintainer or Owner of the project
Group access tokenglpat-A group bot user365 days if no date setYes / Yes / Yes (group and descendants)Owner of the group
Deploy tokengldt-A project or group, no userNo expiry unless a date is setNo / Yes / Yes (HTTP only)Project Maintainer or Owner; group Owner
CI/CD job tokenglcbt-One running jobThe duration of the jobLimited endpoints / Yes / YesGenerated automatically
Runner authentication tokenglrt- (glrtr- if created via a registration token)A runnerUntil rotated or revokedRunner registration and job fetching onlyCreated with the runner
Pipeline trigger tokenglptt-A projectUntil revokedTriggers pipelinesCreated in the project CI/CD settings
Feed tokenglft-A userDoes not expireRSS and calendar feeds onlyOne per user, automatically
Incoming email tokenglimt-A userDoes not expireCreates issues and merge requests by emailOne per user, automatically
Agent for Kubernetes tokenglagent-A registered cluster agentUntil revoked or resetAgent connection to GitLabCreated 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 capabilityAvailable toWhat it allowsControl
sudoPersonal tokens of administratorsAPI actions as any userBan outside break-glass procedures; alert on creation
admin_modePersonal tokens of administrators (Self-Managed)API access while Admin Mode is activeIssue only to named administrators, short expiry
Impersonation tokensCreated by administratorsAct as a specific user through the APIRecord a ticket for each; review monthly
apiPersonal, group, projectFull read and write API, including registries; for personal tokens, full Git over HTTPReplace with read_api or narrower scopes wherever possible
create_runner, manage_runnerPersonal, group, projectCreate and manage runners in scopeRestrict to platform automation; runners execute code with secrets
k8s_proxyPersonal, group, projectKubernetes API calls through the GitLab agentTreat as cluster access; tie to cluster RBAC review
self_rotatePersonal, group, projectThe token can rotate itself, but no other tokenUseful for automated rotation; pair with short lifetimes
Owner role on a group tokenGroup access tokensOwner rights over the group and all descendantsUse 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_mode tokens 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.

NeedUseAvoidWhy
A pipeline calling the GitLab API, registry or another projectCI_JOB_TOKEN with the CI/CD job token allowlistA personal token in a CI/CD variableJob tokens exist only for the job and need no storage
A pipeline deploying to a cloud or reading secrets from a vaultOIDC ID tokens (id_tokens) federated to the cloud or vaultStatic cloud keys in variablesNo long-lived secret to leak; see the CI/CD Pipeline Identity Security Guide
Pulling images or packages from a cluster or build hostDeploy token with read_registry or read_package_registryA personal token with apiDeploy tokens cannot call the API and carry no user
Cloning one repository from a serverDeploy key (SSH, read-only) or deploy token with read_repositoryA maintainer's personal tokenSurvives the maintainer leaving; scoped to the repository
A bot that comments on merge requests in one projectProject access token, Reporter or Developer role, api only if neededGroup token with OwnerBlast radius is one project
An integration that spans many groupsGroup service account with a personal token, invited only where neededA human's personal tokenClear 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.

SourceWhat it showsTier and notes
Token last used and IP addressesLast-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 inventoryPersonal, project and group tokens, SSH keys and (Self-Managed) GPG keys, with owner, scopes, expiry and revocation dates; revoke from the same pageUltimate; Admin area, Access, Credentials, or a top-level group's Secure, Credentials page for enterprise users
Audit eventsFor 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_updatedPremium and Ultimate; streaming to a SIEM needs Ultimate
Job token authentication logWhich other projects used job tokens against a projectPer project, CSV export
  • Alert on: creation of tokens with sudo, admin_mode or api; 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_all push 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_mode or 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

  1. 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.
  2. 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.
  3. Move CI to job tokens and OIDC: pilot one product team, replace personal tokens in CI/CD variables with CI_JOB_TOKEN and 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.
  4. 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.
  5. 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.
  6. 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.
  7. Review quarterly: revoke unused tokens and confirm every service account and bot has an owner.

Framework mapping

Control areaNIST SP 800-53 Rev 5NIST CSF 2.0MITRE ATT&CK
Token lifetime, rotation and revocationIA-5 Authenticator ManagementPR.AA-01T1528 Steal Application Access Token
Scopes, roles and bot token creationAC-6 Least Privilege; AC-2 Account ManagementPR.AA-05T1098.001 Additional Cloud Credentials
Service account and bot ownershipIA-4 Identifier Management; AC-2PR.AA-01T1078.004 Cloud Accounts
Leaked tokens in code and configIA-5PR.AA-01T1552.001 Credentials In Files
Token use monitoring and audit streamingAU-6 Audit Record Review, Analysis, and ReportingDE.CM-03, PR.PS-04T1213.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 api token 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-token name 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 8 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.