Rotate leaked tokens with GitLab Duo

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed
  • Status: Beta

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

When secret detection finds an active GitLab personal access token in your code, you can rotate the token from the vulnerability details page. GitLab stores the new value in GitLab Secrets Manager, and GitLab Duo opens a merge request that replaces the hardcoded token with a reference to the secret. The new token value is never shown to you or sent to GitLab Duo.

Prerequisites

  • GitLab Secrets Manager must be enabled and active for the project.
  • You must meet the prerequisites for the GitLab Duo Agent Platform.
  • The Developer Flow must be turned on for the project.
  • You must have the Security Manager, Maintainer, or Owner role for the project, or a custom role with the admin_vulnerability permission.
  • You must have permission to create secrets in the project.
  • The vulnerability must be a secret detection vulnerability for a GitLab personal access token, including a fine-grained personal access token, with the active token status. You cannot use this feature for other secrets that secret detection finds, like cloud provider keys.
  • Pipeline secret detection must run with validity checks turned on.
  • You must own the token or have administrator access.

If you call the API with a fine-grained personal access token, the token must have both:

  • The Secret: Create permission for the project.
  • The Personal Access Token: Rotate permission for the user.

Rotate a leaked token and fix the code

You can’t undo a rotation. The leaked token is revoked as soon as the rotation runs, and any code or system that still uses the leaked value stops working.

To rotate a leaked token:

  1. In the top bar, select Search or go to and find your project.
  2. In the left sidebar, select Secure > Vulnerability report.
  3. Select the secret detection vulnerability.
  4. In the upper-right corner, select AI actions > Fix with AI.
  5. Optional. Change the Secret name. The default name is ROTATED_GITLAB_TOKEN_<vulnerability_id>. The name must be unique in the project, 255 characters or fewer, and contain only letters, numbers, and underscores (_).
  6. Select Rotate and fix.

To follow the progress of GitLab Duo updating the code, select View agent session.

To view the secret’s details in GitLab Secrets Manager, select View secret.

You can also rotate the token with the projectSecretCreateFromLeakedToken GraphQL mutation. The mutation rotates the token and stores the secret, but does not start a GitLab Duo session.

What happens when you rotate a token

When you rotate a leaked token, GitLab:

  1. Revokes the leaked token and creates a new token with the same name and scopes. The new token has the same lifetime as the leaked token, counted from the rotation date.
  2. Stores the new token value as a project secret, available to all environments and branches. The secret description contains the file and line where the token was leaked.
  3. Changes the token status on the vulnerability to inactive.
  4. Starts a GitLab Duo session with the Developer Flow. The flow opens a merge request that:
    • Removes the hardcoded token from the file.
    • Adds a secrets: keyword with gitlab_secrets_manager to each CI/CD job that uses the token.

GitLab does not change the vulnerability state. After you review and merge the merge request, change the vulnerability status to Resolved.

If GitLab Duo can’t start the session, the token is still rotated and stored. To finish the fix, replace the hardcoded token yourself and use the secret in your CI/CD jobs.

What GitLab Duo receives

The request that starts the GitLab Duo session includes:

  • The project and the vulnerability.
  • The file and line where the token was leaked.
  • The name of the secret that stores the new value.
  • Your username, so GitLab Duo can assign the merge request to you.

The request does not include the leaked token value or the new token value. To remove the hardcoded token, GitLab Duo reads the file, which contains the leaked value. The leaked token is already revoked by then, and GitLab Duo never receives the new value.

Code and systems that use the leaked token

Code and systems that use the leaked token fail from the moment you rotate it until they use the new token:

  • CI/CD jobs in the project work again after you merge the merge request from GitLab Duo.
  • CI/CD jobs in other projects need a new token, because the secret is stored only in this project.
  • Systems outside GitLab CI/CD need a new token, because you cannot retrieve the secret value through the UI.

For other projects and systems, create a personal access token.

GitLab Credits usage

This feature consumes GitLab Credits for:

  • The GitLab Duo Developer Flow session that opens the merge request.
  • The stored secret, and each time a CI/CD job reads it. For more information, see GitLab Secrets Manager credit usage.

Troubleshooting

Fix with AI is not available

If AI actions does not include Fix with AI on a secret detection vulnerability, check that:

  • The secrets_manager_pat_rotation feature flag is enabled.
  • The token status on the vulnerability is active. The token status comes from validity checks. If you turned on validity checks after the last pipeline ran, run a new pipeline.
  • The Developer Flow is turned on for the project.
  • You have the Security Manager, Maintainer, or Owner role for the project, or a custom role with the admin_vulnerability permission.
  • You meet the other prerequisites, including those for the GitLab Duo Agent Platform.

Errors before the token is rotated

GitLab checks these conditions before it rotates the token. If you get one of these errors, the leaked token is not changed. Fix the cause, then try again.

Error Cause and action
Could not resolve a GitLab personal access token from this vulnerability The finding does not contain a token that matches an existing personal access token. Revoke the token manually.
Personal access token not found The token no longer exists.
Token already revoked The leaked token was already revoked, but its status on the vulnerability is still active. Refresh the token status. You don’t need to rotate it.
Failed to revoke token GitLab couldn’t revoke the leaked token, so nothing changed. Try again.
Secrets manager is not active Enable GitLab Secrets Manager, or wait for it to finish provisioning.
Secrets Manager cannot be written: entitlement state is <state> Your namespace can’t write secrets, for example because the trial ended or credits ran out. See GitLab Secrets Manager credit usage.
Another secret operation in progress Wait for the other operation to finish, then try again.

Error: The token was rotated, but the new value could not be stored

This error means the leaked token was revoked, but GitLab could not store the new value in the GitLab Secrets Manager. The message includes the reason the store failed. Both variants mean the leaked token no longer works:

  • The token was rotated, but the new value could not be stored, so it was revoked. Create a new token manually.

    GitLab revoked the new token, so no active token exists. To restore access, create a personal access token and store it as a secret.

  • The token was rotated, but the new value could not be stored or revoked. Revoke the token named <name> manually.

    The new token is still active, but nobody can retrieve its value. Revoke the token with the name in the message. Then create a token and store it as a secret.

You do not need to rotate the same token again because the leaked token is already revoked.

Error: Failed to complete the rotation

GitLab couldn’t confirm whether the rotation finished, for example because of a network error. Before you try again, check whether the leaked token was revoked:

  • If the token status on the vulnerability is active, refresh the token status. If the token is still active, try again.
  • If the token was revoked, check the Secrets Manager for the secret. If the secret is missing, create a token and store the token as a secret.

Error: GitLab Duo could not start or GitLab Duo could not be reached

The token was rotated and stored, but the GitLab Duo session did not start. The message includes the secret name.

To fix this issue, troubleshoot GitLab Duo. Then replace the hardcoded token yourself and use the secret in your CI/CD jobs.