Rotate leaked tokens with GitLab Duo

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 with the active token status.
• 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

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.

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

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: 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.