GitLab Secrets Manager

Secrets represent sensitive information your CI/CD jobs need to function. Secrets could be access tokens, database credentials, private keys, or similar.

Unlike CI/CD variables, which are always available to jobs by default, secrets must be explicitly requested by a job.

Use the GitLab Secrets Manager to securely store and manage your project’s secrets and credentials.

Enable or disable the GitLab Secrets Manager

For a project

Prerequisites:

• You must have the Owner role for the project.

To enable or disable GitLab Secrets Manager for a project:

1. On the top bar, select Search or go to and find your project.

2. Select Settings > General.

3. Expand Visibility, project features, permissions.

4. Turn on the Secrets manager toggle and wait for the secrets manager to be provisioned.

   If you later disable the Secrets Manager for the project, all the project secrets are permanently deleted. These secrets cannot be recovered.

Secrets defined for a project can only be accessed by pipelines from the same project.

Define a secret

You can add secrets to the secrets manager so that it can be used for secure CI/CD pipelines and workflows.

1. On the top bar, select Search or go to and find your project
2. Select Secure > Secrets manager.
3. Select Add secret and fill in the details:
   • Name: Must be unique in the project.
   • Value: No limitations.
   • Description: Maximum of 200 characters.
   • Environments: Can be:
     • All (default) (*)
     • A specific environment
     • A wildcard environment.
   • Branch: Can be:
     • A specific branch
     • A wildcard branch (must have the * character)
   • Rotation reminder: Optional. Send an email reminder to rotate the secret after the set number of days. Minimum 7 days.

After you create a secret, you can use it in the pipeline configuration or in job scripts.

Use secrets in job scripts

To access secrets defined with the secret manager, use the secrets and gitlab_secrets_manager keywords:

job:
  secrets:
    TEST_SECRET:
      gitlab_secrets_manager:
        name: foo
  script:
   - cat $TEST_SECRET

Manage Secrets Permissions

For a project

Prerequisites:

• You must have the Owner role for the project to manage the secrets permissions.
• Users with the Maintainer role for the project can view the defined permissions.
• The Secrets Manager must be enabled for the project.

To update the secrets permissions for a project:

1. On the top bar, select Search or go to and find your project.
2. Select Settings > General.
3. Expand Visibility, project features, permissions.
4. Under Secrets manager, in the Secrets manager user permissions section, you can manage the user permissions:
   • Select Add to add permissions rules for specific users, groups, or roles.
   • You can set permission scopes to read, create, update, and delete secrets.

Deletion of a project

When you delete a project with secrets:

• The secrets manager for the project is disabled and removed from the secrets storage engine.
• All the secrets are permanently deleted.

Transfer of a project

When you transfer a project with secrets:

• The secrets defined for the project are not transferred to the project in it’s new namespace.
• The secrets manager for the project is disabled and removed from the secrets storage engine.
• All the secrets are permanently deleted.

Secret rotation notifications

Users with the Owner role in the project receive an email notification to rotate a secret on the day specified in a secret’s configuration.