From bb9d20d9e8af18832ec424efd68d11476139a6c0 Mon Sep 17 00:00:00 2001 From: Jayakrishnan Mallissery Date: Wed, 10 Dec 2025 18:27:03 +0100 Subject: [PATCH 1/5] Update the docs for Gitlab Secrets Manager The existing documentation of the Gitlab Secrets Manager feature is not fully updte. This commit adds the missing documentation [Issue] (https://gitlab.com/gitlab-org/gitlab/-/work_items/574411) --- doc/ci/secrets/secrets_manager/_index.md | 95 +++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/doc/ci/secrets/secrets_manager/_index.md b/doc/ci/secrets/secrets_manager/_index.md index 242633f17890cc..9c4b7861cd3d21 100644 --- a/doc/ci/secrets/secrets_manager/_index.md +++ b/doc/ci/secrets/secrets_manager/_index.md @@ -68,6 +68,46 @@ To enable GitLab Secrets Manager for a group: Secrets defined for a group can be accessed by pipelines from all projects in the group and its subgroups. +## Disable GitLab Secrets Manager + +### For a project + +Prerequisites: + +- You must have the Owner role for the project. + +To disable GitLab Secrets Manager for a project: + +1. On the top bar, select **Search or go to** and find your project. +1. Select **Settings** > **General**. +1. Expand **Visibility, project features, permissions**. +1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be provisioned. + +{{< alert type="warning" >}} + + When you dsiable secrets manager for a project, all the secrets of the project are deleted and this action cannot be reversed. + +{{< /alert >}} + +### For a group + +Prerequisites: + +- You must have the Owner role for the group. + +To disable GitLab Secrets Manager for a group: + +1. On the top bar, select **Search or go to** and find your group. +1. Select **Settings** > **General**. +1. Expand **Permissions and group features**. +1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be provisioned. + +{{< alert type="warning" >}} + + When you dsiable secrets manager for a group, all the secrets of the group are deleted and this action cannot be reversed. + +{{< /alert >}} + ## Define a secret You can add secrets to the secrets manager so that it can be used for secure CI/CD pipelines @@ -86,12 +126,17 @@ and workflows. - **Branch**: Can be: - A specific branch - A wildcard branch (must have the `*` character) - - **Expiration date**: Secrets become unavailable after the expiration date. - **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. +{{< alert type="warning" >}} + +The value of a secret is accessible to all CI pipeline jobs. Any user who can create a CI pipeline job in a particular project can access the value of all the secrets accessible to the project directly and from it's parent groups. + +{{< /alert >}} + ## Use secrets in job scripts To access secrets defined with the secret manager, use the [`secrets`](../../yaml/_index.md#secrets) and `gitlab_secrets_manager` keywords: @@ -105,3 +150,51 @@ job: script: - cat $TEST_SECRET ``` + +## Secret Rotation + +Automatic rotation of secrets is not supported. The owners of the group/project receive an email to rotate the secret on the day configured for the email reminder. + +## Secret Expiry + +Automatic expiry of secrets is not implemented as of now. It will be implemented in the future + +## Update Secrets Permissions + +### For a project + +Prerequisites: + +- You must have the Owner role 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. +1. Select **Settings** > **General**. +1. Expand **Visibility, project features, permissions**. +1. Under the Secrets manager section, you can see Secrets manager user permissions +1. The access scopes can be set for an individual user, a group or a role. +1. Read, Create, Update, and Delete access scopes for the secrets can be set + +### For a group + +Prerequisites: + +- You must have the Owner role for the group. + +To update the secrets permissions for a group : + +1. On the top bar, select **Search or go to** and find your group. +1. Select **Settings** > **General**. +1. Expand **Permissions and group features**. +1. Under the Secrets manager section, you can see Secrets manager user permissions +1. The secrets access scopes can be set for an individual user, a group or a role. +1. Read, Create, Update, and Delete access scopes for the secrets can be set + +## Deletion of a project + +When a [project is deleted](../../../user/project/working_with_projects.md#delete-a-project), the secrets manager of the project is disabled, deprovisioned from the secrets storage engine and all the secrets are deleted. + +## Transfer of a project + +When a [project is transferred](../../../user/project/working_with_projects.md#transfer-a-project), the secrets defined for the project are not transferred to the project in it's new namespace. The secrets manager of the project is disabled, deprovisioned from the secrets storage engine and all the secrets are deleted. -- GitLab From 313633ad3335e953fb7002808b66e8972e3f1793 Mon Sep 17 00:00:00 2001 From: Jayakrishnan Mallissery Date: Sat, 13 Dec 2025 10:09:14 +0100 Subject: [PATCH 2/5] Apply Duo feedback --- doc/ci/secrets/secrets_manager/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ci/secrets/secrets_manager/_index.md b/doc/ci/secrets/secrets_manager/_index.md index 9c4b7861cd3d21..d25477fdc4b900 100644 --- a/doc/ci/secrets/secrets_manager/_index.md +++ b/doc/ci/secrets/secrets_manager/_index.md @@ -157,7 +157,7 @@ Automatic rotation of secrets is not supported. The owners of the group/project ## Secret Expiry -Automatic expiry of secrets is not implemented as of now. It will be implemented in the future +Automatic expiry of secrets is not currently implemented. Work is being proposed to add this functionality. ## Update Secrets Permissions -- GitLab From 2d7f1a0b7d3f69f88e93291a4a9b92ebb799d5b9 Mon Sep 17 00:00:00 2001 From: Jayakrishnan Mallissery Date: Sat, 13 Dec 2025 10:10:50 +0100 Subject: [PATCH 3/5] Apply MR feedback --- doc/ci/secrets/secrets_manager/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/ci/secrets/secrets_manager/_index.md b/doc/ci/secrets/secrets_manager/_index.md index d25477fdc4b900..66c23a8cf21c84 100644 --- a/doc/ci/secrets/secrets_manager/_index.md +++ b/doc/ci/secrets/secrets_manager/_index.md @@ -81,7 +81,7 @@ To disable GitLab Secrets Manager for a project: 1. On the top bar, select **Search or go to** and find your project. 1. Select **Settings** > **General**. 1. Expand **Visibility, project features, permissions**. -1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be provisioned. +4. Turn off the **Secrets manager** toggle and wait for the secrets manager to be deprovisioned. {{< alert type="warning" >}} @@ -100,7 +100,7 @@ To disable GitLab Secrets Manager for a group: 1. On the top bar, select **Search or go to** and find your group. 1. Select **Settings** > **General**. 1. Expand **Permissions and group features**. -1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be provisioned. +1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be deprovisioned. {{< alert type="warning" >}} @@ -159,7 +159,7 @@ Automatic rotation of secrets is not supported. The owners of the group/project Automatic expiry of secrets is not currently implemented. Work is being proposed to add this functionality. -## Update Secrets Permissions +## Create Secrets Permissions ### For a project -- GitLab From e8f9db9a39a549ac3681cb3857fc98e9959dee83 Mon Sep 17 00:00:00 2001 From: Jayakrishnan Mallissery Date: Sat, 13 Dec 2025 10:23:21 +0100 Subject: [PATCH 4/5] Apply MR feedback --- doc/ci/secrets/secrets_manager/_index.md | 26 +++++++++++------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/doc/ci/secrets/secrets_manager/_index.md b/doc/ci/secrets/secrets_manager/_index.md index 66c23a8cf21c84..a8428f75194a59 100644 --- a/doc/ci/secrets/secrets_manager/_index.md +++ b/doc/ci/secrets/secrets_manager/_index.md @@ -81,7 +81,7 @@ To disable GitLab Secrets Manager for a project: 1. On the top bar, select **Search or go to** and find your project. 1. Select **Settings** > **General**. 1. Expand **Visibility, project features, permissions**. -4. Turn off the **Secrets manager** toggle and wait for the secrets manager to be deprovisioned. +1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be deprovisioned. {{< alert type="warning" >}} @@ -153,19 +153,16 @@ job: ## Secret Rotation -Automatic rotation of secrets is not supported. The owners of the group/project receive an email to rotate the secret on the day configured for the email reminder. - -## Secret Expiry - -Automatic expiry of secrets is not currently implemented. Work is being proposed to add this functionality. +Automatic rotation of secrets is not supported. Work is being proposed to add this functionality. The owners of the group/project receive an email to rotate the secret on the day configured for the email reminder. -## Create Secrets Permissions +## Manage Secrets Permissions ### For a project Prerequisites: -- You must have the Owner role for the project. +- You must have the Owner role for the project to manage the secrets permissions +- Users with Maintainer role for the project can see the defined permissions To update the secrets permissions for a project : @@ -173,23 +170,24 @@ To update the secrets permissions for a project : 1. Select **Settings** > **General**. 1. Expand **Visibility, project features, permissions**. 1. Under the Secrets manager section, you can see Secrets manager user permissions -1. The access scopes can be set for an individual user, a group or a role. -1. Read, Create, Update, and Delete access scopes for the secrets can be set +1. The secrets management permission scopes can be set for an individual user, a group or a role. +1. Read, Create, Update, and Delete are the permission scopes that can be configured ### For a group Prerequisites: -- You must have the Owner role for the group. +- You must have the Owner role for the group to manage the secrets permissions +- Users with Maintainer role can see the defined permissions -To update the secrets permissions for a group : +To manage the secrets permissions for a group : 1. On the top bar, select **Search or go to** and find your group. 1. Select **Settings** > **General**. 1. Expand **Permissions and group features**. 1. Under the Secrets manager section, you can see Secrets manager user permissions -1. The secrets access scopes can be set for an individual user, a group or a role. -1. Read, Create, Update, and Delete access scopes for the secrets can be set +1. The secrets management permission scopes can be set for an individual user, a group or a role. +1. Read, Create, Update, and Delete are the permission scopes that can be configured ## Deletion of a project -- GitLab From e7e59f1c764af07f331dea018f4ea6330713305b Mon Sep 17 00:00:00 2001 From: Jayakrishnan Mallissery Date: Tue, 16 Dec 2025 11:19:31 +0100 Subject: [PATCH 5/5] Apply feedback, Remove group secrets manager docs --- doc/ci/secrets/secrets_manager/_index.md | 88 ++++-------------------- 1 file changed, 12 insertions(+), 76 deletions(-) diff --git a/doc/ci/secrets/secrets_manager/_index.md b/doc/ci/secrets/secrets_manager/_index.md index a8428f75194a59..d79a97b6923dbc 100644 --- a/doc/ci/secrets/secrets_manager/_index.md +++ b/doc/ci/secrets/secrets_manager/_index.md @@ -33,9 +33,9 @@ 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 group or project's secrets and credentials. +Use the GitLab Secrets Manager to securely store and manage your project's secrets and credentials. -## Enable GitLab Secrets Manager +## Enable or disable the GitLab Secrets Manager ### For a project @@ -43,68 +43,20 @@ Prerequisites: - You must have the Owner role for the project. -To enable GitLab Secrets Manager for a 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. 1. Select **Settings** > **General**. 1. Expand **Visibility, project features, permissions**. 1. Turn on the **Secrets manager** toggle and wait for the secrets manager to be provisioned. +1. You can turn off the **Secrets manager** toggle to deprovision the secrets manager of the project and delete all the secrets Secrets defined for a project can only be accessed by pipelines from the same project. -### For a group - -Prerequisites: - -- You must have the Owner role for the group. - -To enable GitLab Secrets Manager for a group: - -1. On the top bar, select **Search or go to** and find your group. -1. Select **Settings** > **General**. -1. Expand **Permissions and group features**. -1. Turn on the **Secrets manager** toggle and wait for the secrets manager to be provisioned. - -Secrets defined for a group can be accessed by pipelines from all projects in the group -and its subgroups. - -## Disable GitLab Secrets Manager - -### For a project - -Prerequisites: - -- You must have the Owner role for the project. - -To disable GitLab Secrets Manager for a project: - -1. On the top bar, select **Search or go to** and find your project. -1. Select **Settings** > **General**. -1. Expand **Visibility, project features, permissions**. -1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be deprovisioned. - {{< alert type="warning" >}} - When you dsiable secrets manager for a project, all the secrets of the project are deleted and this action cannot be reversed. - -{{< /alert >}} - -### For a group - -Prerequisites: - -- You must have the Owner role for the group. - -To disable GitLab Secrets Manager for a group: - -1. On the top bar, select **Search or go to** and find your group. -1. Select **Settings** > **General**. -1. Expand **Permissions and group features**. -1. Turn off the **Secrets manager** toggle and wait for the secrets manager to be deprovisioned. - -{{< alert type="warning" >}} - - When you dsiable secrets manager for a group, all the secrets of the group are deleted and this action cannot be reversed. +If you later disable the Secrets Manager for a project, all the project secrets are permanently deleted. +These secrets cannot be recovered. {{< /alert >}} @@ -113,7 +65,7 @@ To disable GitLab Secrets Manager for a group: 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 or group. +1. On the top bar, select **Search or go to** and find your project 1. Select **Secure** > **Secrets manager**. 1. Select **Add secret** and fill in the details: - **Name**: Must be unique in the project. @@ -133,7 +85,7 @@ After you create a secret, you can use it in the pipeline configuration or in jo {{< alert type="warning" >}} -The value of a secret is accessible to all CI pipeline jobs. Any user who can create a CI pipeline job in a particular project can access the value of all the secrets accessible to the project directly and from it's parent groups. +The value of a secret is accessible to all CI pipeline jobs running in a specific environment or branch, which are defined when the secret is created or updated. Ensure only users with permission to access the value of these secrets can run CI pipeline jobs in the specified environment or branch. {{< /alert >}} @@ -151,10 +103,6 @@ job: - cat $TEST_SECRET ``` -## Secret Rotation - -Automatic rotation of secrets is not supported. Work is being proposed to add this functionality. The owners of the group/project receive an email to rotate the secret on the day configured for the email reminder. - ## Manage Secrets Permissions ### For a project @@ -173,22 +121,6 @@ To update the secrets permissions for a project : 1. The secrets management permission scopes can be set for an individual user, a group or a role. 1. Read, Create, Update, and Delete are the permission scopes that can be configured -### For a group - -Prerequisites: - -- You must have the Owner role for the group to manage the secrets permissions -- Users with Maintainer role can see the defined permissions - -To manage the secrets permissions for a group : - -1. On the top bar, select **Search or go to** and find your group. -1. Select **Settings** > **General**. -1. Expand **Permissions and group features**. -1. Under the Secrets manager section, you can see Secrets manager user permissions -1. The secrets management permission scopes can be set for an individual user, a group or a role. -1. Read, Create, Update, and Delete are the permission scopes that can be configured - ## Deletion of a project When a [project is deleted](../../../user/project/working_with_projects.md#delete-a-project), the secrets manager of the project is disabled, deprovisioned from the secrets storage engine and all the secrets are deleted. @@ -196,3 +128,7 @@ When a [project is deleted](../../../user/project/working_with_projects.md#delet ## Transfer of a project When a [project is transferred](../../../user/project/working_with_projects.md#transfer-a-project), the secrets defined for the project are not transferred to the project in it's new namespace. The secrets manager of the project is disabled, deprovisioned from the secrets storage engine and all the secrets are deleted. + +## Secret rotation reminder + +The owners of the project receive an email to rotate the secret on the day configured when creating or updating a secret -- GitLab