A job usually needs access for a specific action: read a package, publish an image, retrieve a secret, or deploy to one environment. Credentials that outlive the job or grant unrelated permissions make an error or compromise more consequential.
Match both the lifetime and the authority of a credential to the work. A short-lived token reduces the time it can be misused, while narrow permissions reduce what it can do during that time. Neither choice replaces a trustworthy execution environment.
Start with the action and its target
Follow a pipeline's calls to registries, cloud services, secret managers, deployment targets, and other GitLab projects. For each call, understand what the job needs to do and who owns the receiving system. This is often enough to expose a personal token used for a machine task, an obsolete cloud key, or access inherited from an earlier deployment design.
Prefer CI_JOB_TOKEN for the GitLab actions it supports. GitLab issues it for the running job and revokes access when the job finishes. It can also authenticate to the job project's Container Registry. Its permissions depend on the user who triggered the job and the resources the token is allowed to use; it isn't an independent service account with a fixed role.
That dependency matters for scheduled, manual, retried, and downstream work. A pipeline that works for a Maintainer may fail for a developer or use more authority than expected under a schedule owner. Check the access under the identities that actually run those paths.
Keep cross-project access deliberate
The receiving project's job token allowlist controls which other projects can use job tokens to access it. An allowlist entry doesn't grant the triggering user new permissions. The user still needs permission for the requested action, and fine-grained job token permissions can further limit supported API endpoints.
Choose a group entry only when the whole group is intended to have that access. It includes projects in nested subgroups and projects added later. A narrow project entry is easier to reason about when only one producer or consumer needs access. Public and internal projects also have resource-visibility settings that affect what jobs outside the allowlist can read.
Review authentication logs alongside expected calls. Logs help identify dependencies in use; testing an unrelated project's request helps check that the restriction works. Broadening an allowlist to clear an unexplained failure can quietly authorize much more work than intended.
Let external services recognize the job
OpenID Connect ID tokens let a compatible cloud service or secret manager identify a GitLab job without a stored cloud key. The external service then decides what that identity may do. Set aud for the intended service and restrict the provider's trust policy to the intended project and execution context.
For example, production deployment access should be distinguishable from a test job in the same namespace. Project identity, protected ref status, environment, and pipeline source can help express that distinction where the provider supports those claims. Provider support varies by integration and GitLab offering, so use its documented claim set when writing the trust policy.
An ID token's expiry follows the configured job timeout, or five minutes when no timeout is specified. The provider may issue a separate session credential with its own expiry. Check both lifetimes when deciding how long deployment or secret access should last.
A secret manager centralizes storage, access, and rotation, but each job should still request only the secrets it needs. GitLab's external secrets integrations can retrieve them for the job.1 When a target requires a stored credential, give it a limited purpose, a clear owner, and a rotation and revocation path.
Tokens remain bearer credentials while valid. Keep them out of logs and artifacts, restrict the services that accept them, and test that an unrelated job can't exchange them for access.
Replacing long-lived pipeline credentials takes this from intent to a migration approach: choose one access path, agree what the receiving service should allow, test both allowed and denied requests, and retire the old credential.
Further Reading
Notes
-
GitLab's external secrets integrations are available in Premium and Ultimate. OIDC ID tokens are available on all tiers, so a job can also authenticate directly to a compatible provider and retrieve secrets using that provider's tools. ↩
- Choose supported actions and restrict CI/CD job tokens explains user permissions, allowlists, resource visibility, and authentication logs.
- Limit job tokens to specific API permissions provides the available permission sets.
- Configure OIDC tokens and provider trust describes audiences, claims, expiry, and provider-specific guidance.
- Retrieve secrets from an external provider explains GitLab's supported integrations.