A pipeline often acquires credentials one integration at a time: a personal access token to download a package, a cloud key to publish a release, and a password for an older deployment service. Over time, the same secrets can end up shared across projects, inherited by unrelated jobs, or left active after their original owner changes teams. Rotation becomes disruptive because nobody is sure which jobs still depend on them.
Start by replacing one well-understood access path. Use a GitLab job token where the GitLab operation supports it, or an ID token to obtain temporary access from an external provider. Where a stored credential is still needed, reduce its permissions and the jobs that receive it. The job should complete its intended work without leaving a broadly reusable credential behind. Removing CI/CD variables alone doesn't establish that.
Short-lived credentials reduce how long a stolen value can be used. They don't make the code receiving that value trustworthy or limit its permissions automatically. Plan the identity, allowed operations, pipeline configuration, and worker access together.
Start with one job and its destination
Choose an access path with a clear owner and a result you can check without risking a live service. Downloading a private package or publishing a bundle to a staging location is often easier to start with than replacing every production deployment credential at once. Include a production example in the later rollout; success in staging won't establish that production permissions and recovery work.
Follow the job's actual commands, included configuration, and runner setup. Record enough to explain:
| Question | What to look for |
|---|---|
| What operation needs authentication? | The package download, API method, registry push, secret read, or deployment action and its destination. |
| Where does access come from? | Project and inherited group variables, a secrets provider, credentials baked into an image, or a cloud identity available from the worker host. Record references and owners, not secret values. |
| Which work receives that access? | Branch, tag, merge request, schedule, downstream pipeline, and manual-job paths, including who starts them and which configuration they execute. |
| What else uses the same credential? | Other projects, scheduled jobs, release tools, or services that would fail if it were revoked. |
| Who can change or stop access? | The GitLab project owner, target-service administrator, and person responsible for replacement or emergency revocation. |
For example, a job called publish_preview might use an inherited cloud key that can also replace production objects. Migrating that job means choosing a preview-only role and removing its access to the inherited key, not giving the same broad rights to a temporary identity.
Keep the first inventory focused on the path you're changing. If a credential has many consumers, separate them into independently replaceable credentials or roles before attempting a shared cutover. Suspected compromise needs incident handling and prompt revocation rather than a routine migration schedule.
Match the credential to the operation
Use a job token for supported GitLab actions
GitLab supplies CI_JOB_TOKEN to a running job and revokes it when the job finishes. It supports selected GitLab operations, not GraphQL. Its permissions depend on the initiating user, including a schedule's owner. Check the exact operation in the job-token documentation before replacing a personal access token.
For a private cross-project dependency, add the calling project to the destination's job-token allowlist. The initiating user still needs destination permissions; the entry doesn't grant a role. Prefer a specific project over a group containing unrelated callers. Public and internal resources also have visibility settings, so an allowlist alone doesn't make them private.
Suppose services/payments downloads a generic package from shared/build-tools. Add services/payments to the allowlist in shared/build-tools, then use the job token for the supported package request. Where fine-grained job-token permissions cover the operation, grant READ_PACKAGES rather than package administration. Fine-grained permissions apply to supported endpoint groups; inspect the group's complete permissions before treating it as access to only one command.
Try the package request from a normal developer pipeline and from the scheduled pipeline that needs it. A successful Maintainer-triggered run won't show whether a different initiating user can work. Also try a caller outside the allowlist against a private test resource. Compare the actual result with the intended access before removing the old token.
If you're replacing a token used for Git pushes, job-token pushes don't start a new pipeline, and repository push access has separate settings. Check that required follow-on work still happens after the change.
Use an ID token for an external provider
For an OIDC-capable cloud or secrets provider, the job requests an ID token through id_tokens. The provider checks the signed token and its claims before granting access. This removes the need to store a cloud key merely to establish the job's identity. An ID token isn't a replacement value for CI_JOB_TOKEN; the two are accepted by different services for different purposes. GitLab's cloud connection guidance explains that exchange.
Work with the destination's owner to make two decisions separately: which jobs may assume the role, and what the role may do afterward. A role limited to one project can still be dangerously powerful if it administers the entire cloud account.
For a deployment from delivery/payments on main, the choices might be:
| Choice | Example and reason |
|---|---|
| Issuer and audience | Trust your GitLab issuer and request an audience accepted by the destination, such as sts.amazonaws.com for an AWS setup configured with that audience. Audience matching doesn't by itself restrict access to one project. |
| Project and ref | Match the intended project and branch, such as the default subject project_path:delivery/payments:ref_type:branch:ref:main. Avoid a wildcard covering every project or branch merely to make the first job pass. |
| Role permissions | Allow publishing the approved bundle to the payments deployment location, without permissions to edit IAM or another application's files. Give preview deployment a different role and destination. |
Use stable project identifiers where the provider supports them, and review path-based conditions when projects move or are renamed. AWS accepts additional GitLab claims such as project_id and namespace_id for the gitlab.com identity provider. For GitLab Self-Managed and GitLab Dedicated, AWS supports sub and aud as condition keys, not that same set of custom claims. A field appearing in a JWT doesn't mean a provider can enforce it. Use the AWS integration guidance to choose supported conditions for your offering.
Where supported, add conditions such as ref_protected or pipeline_source when the deployment decision depends on them. Protecting a branch is a separate GitLab configuration choice; matching a branch name doesn't protect it. Inspect the claims for the pipeline types you intend to allow, including forks: project_id and project_path describe the source project in merge request pipelines, while job_project_id and job_project_path identify the project running the job. The ID-token claim reference explains their meanings. Keep token values out of logs while inspecting the non-secret claims you need.
For a private GitLab instance, check that the provider can retrieve the issuer's discovery document and verification keys. A worker's ability to reach the cloud API doesn't establish that the cloud can validate its token. AWS's documented non-public-instance approach requires careful management of publicly hosted discovery information and keys; that needs an infrastructure owner, not a pipeline-only workaround.
Keep build access separate from deployment access
A dependency installation can execute third-party code. Giving that job a production role lets the dependency use production permissions too, even if the role lasts only a few minutes. Keep tests and builds on identities that can read their inputs and publish the outputs they need. Let a separate deployment job obtain deployment access and consume the selected artifact without repeating dependency installation under the stronger identity.
The handoff still needs care. A deployment job that executes an arbitrary script from the build artifact grants that script its own access. Prefer a reviewed deployment script that treats the artifact as data, and identify the artifact by the intended pipeline, version, or digest rather than whichever file happens to be latest. The credential change should preserve the link between the reviewed change and what gets deployed.
Request each ID token only in the job that needs it, and have downstream jobs authenticate for themselves. Avoid passing credentials through artifacts, caches, or dotenv reports. Check that a job denied federation can't fall back to a worker's broad cloud identity. Runner separation by workload trust helps when build and deployment jobs also need different hosts or networks.
Treat pipeline configuration as code that can use the job's permissions. Review included components and scripts as well as .gitlab-ci.yml. A rules condition that skips deployment on merge requests helps control the workflow, but a contributor who can change the configuration can also change that condition. The destination's trust policy and GitLab's controls over accepted changes need to enforce the access decision.
A fork pipeline normally uses the fork's resources. If a parent-project member runs a fork merge request pipeline in the parent, it uses configuration from the fork with the parent's resources and the triggering member's permissions. Review that configuration before running it. Protected variables and runners have additional restrictions: merge request access requires the relevant setting, protected source and target branches in the same project, and a user with push or merge access to the target. Fork merge requests can't obtain those protected resources. These restrictions don't automatically define an external provider's trust policy. See merge request pipeline access.
When a stored credential still needs to remain
Some destinations don't support federation, and some GitLab operations aren't available through a job token. Choose the narrowest credential that does support the operation. A project deploy token can fit repository reads or registry access, but it isn't a general-purpose GitLab API token. Set an expiry deliberately because deploy tokens don't expire by default. The deploy-token scopes distinguish repository, package, and container access.
For a GitLab API operation outside job-token support, a project access token can avoid tying the automation to a person's broad account access.1 Choose both its role and scopes for the required action. It remains a stored credential requiring rotation and revocation, and project tokens created by internal users can also read Internal-visibility projects. Check that exposure rather than assuming the token's name establishes all its access.
For an older external deployment service, use a dedicated service identity restricted to the application and environment. Keep its secret in a secrets provider or an appropriately protected project CI/CD variable. Set the project variable's environment scope to its intended destination, such as production, rather than leaving it available to every environment. Masking reduces accidental log exposure; hiding a new variable prevents later disclosure through the settings UI. Neither stops malicious code in an authorized job from using or sending the secret elsewhere. CI/CD variable security covers these controls and their limits.
An external secrets provider can centralize access and rotation. GitLab's built-in secrets integrations can retrieve secrets only for the jobs that request them.2 Retrieving an old, broad password through OIDC improves delivery of that password, but doesn't make the password itself short-lived. Keep its destination permissions and rotation plan in the migration.
Give each remaining credential a purpose, owner, expiry or rotation date, and a tested replacement path. Removing shared credentials can mean more individual roles or tokens to maintain. Use consistent naming and reviewed reusable configuration after the first path works, without collapsing distinct deployment permissions back into one shared identity.
Cut over with the old credential absent
Test the new path while the old credential is unavailable to the pilot job. Otherwise an SDK credential chain or helper script can silently use the old value and make a broken migration look successful. Keep any temporary fallback outside that job's normal access, with a named operator and a clear retirement date.
Use the pilot to check that intended operations succeed and unauthorized access is denied:
- The intended job can obtain the intended identity and complete the real operation against a safe representative destination. An identity lookup alone doesn't establish permission to deploy or publish.
- The wrong project, wrong audience, and an unapproved branch or tag fail to obtain the deployment role. Try fork and parent-run fork pipelines if your contribution process uses them.
- The build identity can't assume the deployment role or write to its destination. The deployment identity can't change another application's resources.
- A timeout, expired credential, or unavailable identity service stops the operation with an error that explains what went wrong instead of falling back to a static key or broader host identity.
- Scheduled jobs, retries, and recovery jobs obtain fresh credentials under the intended identity. A retry shouldn't depend on a token saved from an earlier job.
Use harmless resources with representative permissions for denial checks. Record the job, project, ref, role or token identity, requested operation, and result without retaining secret values. Distinguish a denied role assumption from a role that was granted but then failed to access the resource; they point to different configuration problems.
After the pilot, move the remaining consumers of that credential in manageable groups. Once they use the replacement, revoke the old credential at its issuer and remove its stored copies from variables, secret stores, and worker configuration. Deleting a variable alone doesn't invalidate a credential someone already copied. Confirm that the retired credential fails a harmless authentication check and that normal and scheduled jobs continue without it. Pause wider rollout if unexpected callers still depend on it.
Plan emergency access separately from normal fallback. GitLab job tokens end with the job, but an ID token's expiry and a cloud session's lifetime are separate. Cancelling a pipeline or removing a trust-policy entry isn't a substitute for the provider's response to already-issued credentials. For example, AWS role-session revocation denies sessions issued before a chosen time and can affect other jobs using that role. Rehearse the interruption and recovery with the destination's owner so an incident doesn't require inventing the process.
Judge the change by access removed and work preserved
Compare the pilot with its starting point: which stored credentials are now revoked, which jobs no longer receive deployment rights, and which negative checks reliably fail? Retain enough job and provider activity records to connect an access request to its project, ref, and operation. A count of OIDC-enabled jobs doesn't show whether a shared cloud key still provides a second route.
Also watch authentication failures, time spent obtaining credentials, expired-session failures during long jobs, and recovery delays. Federation adds a dependency on the issuer and provider being available when access is requested. Choose a session duration that covers the operation with a reasonable margin, rather than maximizing its lifetime to hide a slow or unreliable deployment.
Expand the pattern after both normal work and denied access behave as intended. Repeat the checks when a project moves, branch rules change, a shared pipeline component gains new behavior, or a provider role is broadened. For credentials that remain static, practice rotation and remove consumers that no longer need access.
Further Reading
Notes
-
Project access tokens are available in Premium and Ultimate on GitLab.com, and with any license on GitLab Self-Managed and GitLab Dedicated. Their role and scopes determine permissions. GitLab's Rotate action immediately invalidates the previous value, so plan consumers' updates before using it. ↩
-
GitLab's built-in external secrets integrations are available in Premium and Ultimate. ID tokens themselves are available on Free, Premium, and Ultimate; a job can use a provider's client to authenticate with an ID token without using the built-in
secretsintegration. ↩
- Job-token permissions and fine-grained permissions help you check the exact GitLab operation, configure the destination allowlist, and narrow the allowed endpoints.
- Connect to cloud services leads to provider-specific setup; use the ID-token claim reference when writing or diagnosing trust conditions.
- Configure OpenID Connect in AWS walks through a concrete federation setup, including offering-specific condition keys and discovery requirements.
- CI/CD variable security helps you protect the stored credentials you still need and understand what masking can't prevent.
- Runner separation by workload trust helps you pair job identities with suitable workers and network access.