This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.
Status Authors Coach DRIs Owning Stage Created
proposed @alberts-gitlab @iamricecake @grzesiek @fabiopitino @jocelynjane @shampton devops verify 2023-08-07

GitLab Secrets Manager


GitLab users need a secure and easy-to-use solution to store their sensitive credentials that should be kept confidential (“secret”). GitLab Secrets Manager is the desired system that provides GitLab users to meet that need without having to access third party tools.


The current de-facto approach used by many to store a sensitive credential in GitLab is using a Masked Variable or a File Variable. However, data stored in variables (masked or file variables) can be inadvertently exposed even with masking. A more secure solution would be to use native integration with external secret managers such as HashiCorp Vault or Azure Key Vault.

Integration with external secret managers requires GitLab to maintain the integration with the third-party products and to assist customers in troubleshooting configuration issues. In addition, customer’s engineering teams using these external secret managers may need to maintain these systems themselves, adding to the operational burden.

Having a GitLab native secret manager would provide customers a secure method to store and access secrets without the overhead of third party tools and to leverage the tight integration with other GitLab features.


Provide GitLab users with a way to:

  • Securely store secrets in GitLab
  • Use the stored secrets in GitLab components (for example, CI Runner)
  • Use the stored secrets in external environments (for example, production infrastructure).
  • Manage access to secrets across a root namespace, subgroups and projects.

Use Cases

To help design the architecture, we need to understand how users, in their roles, would operate and use the system. Here are significant use case scenarios that can help drive our design decisions:

  • As a user running a pipeline, I want a CI job to automatically fetch secrets specified in the .gitlab-ci.yml file.
  • As a DevOps engineer, I want the deployment process to fetch secrets necessary for deployment directly from GitLab Secrets Manager.
  • As a DevOps engineer, I want to manually retrieve the staging database password from the GitLab Secrets Manager.
  • As a project maintainer, I want to destroy all secrets in the scope of the project, when the project is being deleted.
  • As a GitLab instance admin, I want to quickly rotate all runner registration tokens.
  • As a FIPS compliant customer, I want GitLab Secrets Manager to encrypt/decrypt secrets using an HSM solution.

Non-functional requirements

  • Security
  • Compliance
  • Auditability


This blueprint does not cover the following:

  • Secrets such as access tokens created within GitLab to allow external resources to access GitLab, e.g personal access tokens.



These documents are part of the initial iteration of this blueprint.


The secrets manager feature will be available on both SaaS and Self-Managed installations and will consist of two core components:

  1. GitLab Rails
  2. OpenBao Server
flowchart LR c([Consumer]) --interacts with-->glab[GitLab Rails]--with backend-->o[OpenBao]

A consumer can be:

  1. A user who interacts manually with a client library, API, or UI.
  2. An integration, for example, Vault integration on Runner.

1. GitLab Rails

GitLab Rails would be the main interface that users would interact with when managing secrets using the Secrets Manager feature.

This component is a facade to OpenBao server.

2. OpenBao Server

OpenBao Server will be a new component in the GitLab overall architecture. This component provides all the secrets management capabilities including storing the secrets themselves.

Use Case Studies

Further investigations required

  1. Authentication of clients other than GitLab Runner. GitLab Runner authenticates using JWT, for other types of clients, we need a secure and reliable method to authenticate requests to decrypt a secret.
  2. How to namespace data, roles and policies to specific tenant.
  3. How to allow organizations to seal/unseal secrets vault on demand.
  4. Infrastructure setup, including how OpenBao will be installed for self-managed instances.
  5. How to best implement sharing of secrets between multiple groups in GitLab.
  6. Establish our protocol and processes for incidents that may require sealing the secrets vault.
  7. How to support protected and environment specific rules for secrets.
  8. How to audit secret changes. Do we want to use audit socket?
  9. Do we want to structure project secret paths to be under namespaces to increase isolation between tenants?
  10. Should the secrets be revoked if a project or subgroup is moved under a different top-level group/organization?

Alternative Solutions

Other solutions we have explored:

  • Separating secrets from CI/CD variables as a separate model with limited access, to avoid unintended exposure of the secret.
  • Secure Files


The following links provide additional information that may be relevant to secret management concepts.