From 682297ccc6b93b064556d64012b2b5d4a19bc26f Mon Sep 17 00:00:00 2001 From: Duo Developer Date: Fri, 12 Dec 2025 22:12:27 +0000 Subject: [PATCH] docs: Add Beta quick start guide for GitLab Secrets Manager Create comprehensive quick start guide for Beta customers with step-by-step instructions for enabling and using GitLab Secrets Manager. Update main documentation to reference the new Beta guide and add Secrets Manager to the list of supported secret management providers. - Add beta_quick_start.md with complete onboarding guide for Beta customers - Include prerequisites, getting started steps, and feedback mechanisms - Add placeholders for PM-provided demo recording and known limitations - Link to Beta guide from main Secrets Manager documentation - List GitLab Secrets Manager as first provider in external secrets index --- doc/ci/secrets/_index.md | 1 + doc/ci/secrets/secrets_manager/_index.md | 2 + .../secrets_manager/beta_quick_start.md | 182 ++++++++++++++++++ 3 files changed, 185 insertions(+) create mode 100644 doc/ci/secrets/secrets_manager/beta_quick_start.md diff --git a/doc/ci/secrets/_index.md b/doc/ci/secrets/_index.md index e557bd39dfef6b..bc7ffd5f00f672 100644 --- a/doc/ci/secrets/_index.md +++ b/doc/ci/secrets/_index.md @@ -21,6 +21,7 @@ requested by a job. GitLab supports several secret management providers, including: +1. [GitLab Secrets Manager](secrets_manager/_index.md) (Beta) 1. [HashiCorp Vault](hashicorp_vault.md) 1. [Google Cloud Secret Manager](gcp_secret_manager.md) 1. [Azure Key Vault](azure_key_vault.md) diff --git a/doc/ci/secrets/secrets_manager/_index.md b/doc/ci/secrets/secrets_manager/_index.md index 242633f17890cc..efadac94cac9a5 100644 --- a/doc/ci/secrets/secrets_manager/_index.md +++ b/doc/ci/secrets/secrets_manager/_index.md @@ -28,6 +28,8 @@ notice. This feature is not ready for public testing or production use. {{< /alert >}} +For Beta customers, see the [Quick start guide for Beta customers](beta_quick_start.md). + Secrets represent sensitive information your CI/CD jobs need to function. Secrets could be access tokens, database credentials, private keys, or similar. diff --git a/doc/ci/secrets/secrets_manager/beta_quick_start.md b/doc/ci/secrets/secrets_manager/beta_quick_start.md new file mode 100644 index 00000000000000..0505a093a15ee1 --- /dev/null +++ b/doc/ci/secrets/secrets_manager/beta_quick_start.md @@ -0,0 +1,182 @@ +--- +stage: Software Supply Chain Security +group: Pipeline Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +title: Quick start guide for Beta customers +--- + +{{< details >}} + +- Tier: Ultimate +- Offering: GitLab.com, GitLab Self-Managed +- Status: Beta + +{{< /details >}} + +{{< alert type="info" >}} + +This guide is for participants in the GitLab Secrets Manager Closed Beta program. +The Beta is the final round of testing before general availability (GA). +Thank you for participating and helping us improve GitLab Secrets Manager! + +{{< /alert >}} + +This quick start guide helps Beta customers get started with GitLab Secrets Manager. + +## Overview + +GitLab Secrets Manager is a native secrets management solution that helps you securely store and manage your group or project's secrets and credentials for CI/CD pipelines. + +Secrets represent sensitive information your CI/CD jobs need to function, such as: + +- Access tokens +- Database credentials +- Private keys +- API keys + +Unlike CI/CD variables, which are always available to jobs by default, secrets must be explicitly requested by a job, providing an additional layer of security. + +The Closed Beta program allows selected customers to test GitLab Secrets Manager in both SaaS and self-managed environments before general availability. Your feedback during this phase is critical to ensuring the product meets your needs. + +## Prerequisites + +Before you begin, ensure you have: + +- A GitLab Ultimate license (for both GitLab.com and self-managed instances) +- The Owner role for the project or group where you want to enable GitLab Secrets Manager +- For self-managed instances: Your GitLab administrator must have configured the GitLab Secrets Manager infrastructure + +If you're unsure about your access level or configuration, contact your GitLab administrator. + +## Getting started + +Follow these steps to start using GitLab Secrets Manager: + +### Step 1: Enable GitLab Secrets Manager + +You can enable GitLab Secrets Manager at either the project or group level. + +#### For a project + +To enable 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. + +Secrets defined for a project can only be accessed by pipelines from the same project. + +#### For a 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. + +### Step 2: Define a secret + +After enabling GitLab Secrets Manager, you can add secrets: + +1. On the top bar, select **Search or go to** and find your project or group. +1. Select **Secure** > **Secrets manager**. +1. Select **Add secret** and fill in the details: + - **Name**: Must be unique in the project or group. + - **Value**: The secret value (no limitations on format). + - **Description**: Optional. Maximum of 200 characters. + - **Environments**: Can be: + - **All (default)** (`*`) + - A specific [environment](../../environments/_index.md#types-of-environments) + - A [wildcard environment](../../environments/_index.md#limit-the-environment-scope-of-a-cicd-variable) + - **Branch**: Can be: + - A specific branch + - A wildcard branch (must have the `*` character) + - **Expiration date**: Optional. 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). + +### Step 3: Use secrets in your CI/CD pipelines + +To access secrets in your CI/CD jobs, use the [`secrets`](../../yaml/_index.md#secrets) keyword with `gitlab_secrets_manager`: + +```yaml +job: + secrets: + TEST_SECRET: + gitlab_secrets_manager: + name: foo + script: + - cat $TEST_SECRET +``` + +The secret is made available as an environment variable in your job and can be used in your scripts. + +## Access instructions + +For complete documentation on GitLab Secrets Manager features and capabilities, see: + +- [GitLab Secrets Manager main documentation](https://docs.gitlab.com/ci/secrets/secrets_manager/) + +{{< alert type="info" >}} + +Documentation is being actively updated as part of the Beta program. +For the latest updates, see [issue #550380](https://gitlab.com/gitlab-org/gitlab/-/issues/550380). + +{{< /alert >}} + +## Demo recording + + + +A demonstration video showing GitLab Secrets Manager setup and usage will be available soon. + +## Known limitations + + + +Known limitations and considerations for the Beta release are being documented. +As a Beta participant, you may encounter some limitations or issues. Please report +any problems you experience through the feedback channels described below. + +## Administrator documentation + +For self-managed GitLab instances, administrators need to configure the GitLab Secrets Manager infrastructure. + +Administrator documentation is currently being developed: + +- [Administration documentation](https://gitlab.com/gitlab-org/gitlab/-/issues/573065) (Work in progress) +- [OpenBao chart documentation for Beta](https://gitlab.com/gitlab-org/gitlab/-/issues/573278) (Work in progress) + +If you're a self-managed customer and need assistance with setup, please contact your GitLab account team or use the feedback channels below. + +## Providing feedback + +Your feedback is essential to making GitLab Secrets Manager successful. As a Beta participant, please share: + +- Feature requests and suggestions +- Bug reports and issues +- Use cases and workflows +- Performance observations +- Documentation feedback + +To provide feedback: + +1. Create an issue in the [GitLab project](https://gitlab.com/gitlab-org/gitlab/-/issues/new) with the label `~"Category:Secrets Management"` +1. Contact your GitLab account team +1. Participate in Beta program feedback sessions (if scheduled) + +Your input directly influences the product roadmap and helps ensure GitLab Secrets Manager meets your organization's needs. + +## Next steps + +After getting started with GitLab Secrets Manager, you can: + +- Explore advanced secret configuration options like environment and branch scoping +- Set up secret rotation reminders to maintain security best practices +- Integrate secrets into your existing CI/CD pipelines +- Review the [CI/CD secrets documentation](../_index.md) for broader context on secrets management in GitLab + +Thank you for being part of the GitLab Secrets Manager Beta program! -- GitLab