GitLab CI/CD secrets from HashiCorp Vault

What you need before connecting GitLab to Vault

Connecting GitLab CI/CD to Vault touches four systems: the GitLab instance that issues ID tokens, the Vault cluster that validates them, the runners that fetch secrets, and the people who own the policies. Settle each of the cards below before writing any pipeline configuration, because a gap in one usually surfaces as a failed job.

Configuration sequence from Vault auth to a passing pipeline

This sequence connects a GitLab project to a Vault role that issues read-only access to one secret, scoped to a single project and protected branch. It ends with a passing pipeline and audit evidence that the restrictions work, using a non-production project for the test.

1. Confirm tier and instance network path

   The platform owner confirms that the GitLab edition and tier on your instance include the CI/CD secrets integration, using the current pricing and feature pages. They then record the external URL that Vault will use to reach GitLab's OpenID configuration. Vault must reach that URL over HTTPS from its own network, so the security team checks firewall rules and certificate trust between the two systems first. This step is done when a request from the Vault host to the instance's OpenID discovery document returns a valid response that lists the expected issuer.

2. Enable and configure the JWT auth method

   A Vault administrator enables the JWT auth method and sets the GitLab instance URL as the OIDC discovery URL, with the bound issuer set to the same value. The issuer string must match exactly what GitLab advertises, because a trailing slash or hostname mismatch is a common reason logins fail. Read the auth configuration back to confirm the issuer and discovery URL match your instance. Then attempt a login with no role attached, which should return a clear error instead of a token.

3. Create a test secret path

   The secrets owner confirms a KV version 2 secrets engine is available, then writes a dummy value under a path reserved for one non-production GitLab project, such as a sandbox project with no deployment rights. Production secrets stay out of this exercise entirely. Read the secret back as an administrator to confirm the path and version. Share only the path with the pipeline team, never the value, and keep the value out of tickets, chat and job logs.

4. Write a read-only policy for that path

   The Vault administrator writes a policy that grants only the read capability on the exact data path of the test secret, with no list, create, update or delete capabilities. Keep one policy per application or environment, so a compromised job cannot reach unrelated secrets. Confirm the policy by testing it with a token that carries it: a read on the test path should succeed, and a write to the same path should return permission denied.

5. Bind the role to project and branch

   Create a JWT role that accepts only tokens issued for the test project, using claims that GitLab sets for each job. Set the user claim to a stable identifier, bind the audience to the value the job will request, and restrict the ref and protected-branch claims so only a protected branch can receive the policy. Attach the read-only policy and a short token lifetime. Confirm by reading the role back and checking each bound claim against a sample token from a protected branch and from an unprotected branch.

6. Request the ID token in the job

   The pipeline author adds an id_tokens entry to the test job with the audience that Vault expects, then adds a secrets entry that names the Vault path and role and maps the value to a CI/CD variable. Keep the audience specific to this Vault instance. Restrict who can edit the job definition on protected branches, since the role and path are visible to anyone who can change the pipeline. Run the job on a protected branch and confirm in the job log that the secrets step completed without an error.

7. Confirm retrieval without printing the value

   In the test job, print only a fixed success message and never the secret value or any part of it, then confirm the job passes. Next, open the Vault audit log and find the JWT login entry, which should name the role and show the project and branch claims without any secret content. Finally, run the same pipeline from an unprotected branch and confirm Vault denies the login. A denial there proves the branch restriction works.

Which GitLab claims map to which Vault role conditions

This table pairs each GitLab ID token claim with the Vault role condition that can match it, the stability of that claim, and the policy paths it should unlock. Read the stability column first, because a role condition built on an unstable claim can stop matching after a rename or quietly widen access. Confirm the exact claim names and their formats in the GitLab CI/CD ID token documentation for your installed version before writing any role.

Hardening the GitLab to Vault trust path

The trust path runs from a GitLab job's ID token to a Vault role and then to the secret the job reads. Each link can be tightened separately, and the cards below cover the controls that matter most. Roll them out gradually, starting with role conditions and logging, as the GitLab hardening guidance recommends.

Choosing between HashiCorp Vault and OpenBao for this integration

Why the secret fetch fails and how to fix it

This table lists the failures teams most often hit when a CI/CD job pulls a secret from Vault, with the likely cause and a check you can run to confirm and fix it. Work down the rows in the order a job reaches each step: tier and feature, token, Vault authentication, network trust, token lifetime and finally the policy. The main takeaway is that most failures trace back to a mismatch between the job's ID token claims and the Vault role, so compare those values first.

Questions buyers ask before connecting GitLab to Vault