GitLab

GitLab uses a JSON Web Token (JWT) to authenticate with Vault to securely access secrets for CI/CD pipelines. Once authenticated, GitLab can pull static secrets from the KV secrets engine, or dynamic secrets from engines such as the AWS secrets engine.

Follow the guidance in Use HashiCorp Vault secrets in GitLab CI/CD to enable your GitLab pipeline to establish authentication, and use secrets in Vault. Review the Using external secrets in CI tutorial to learn more about using Vault secrets engines with your GitLab pipelines.

Static secrets

To use static secrets, reference the secrets:vault keyword in the secrets portion of your gitlab-ci.yml file.

In the following example, the GitLab pipeline automatically authenticates to Vault with an ID Token. The pipeline then uses secrets:vault to pull a secret from the Vault K/V secrets engine at the path /ops/production/db, and set the value of the password field as the DATABASE_PASSWORD environment variable. Pipeline jobs can then use the secret stored in the environment variable to authenticate to the correlating database. Refer to the Use Vault secrets in a CI job for further documentation.

job_with_secrets:
  id_tokens:
    # Automatically authenticate to Vault with GitLab ID token
    VAULT_ID_TOKEN:
      aud: https://vault.example.com
  secrets:
    # Store the the secret value in the DATABASE_PASSWORD environment variable
    DATABASE_PASSWORD:  
      # Secret path: ops/data/production/db, field: password
      vault: production/db/password@ops
      # Store value directly in the environment variable, not a file
      file: false

You can also pull static secrets and set them to environment variables from the CLI with manual authentication as shown in the Manual ID Token authentication documentation example.

manual_authentication:
  variables:
    VAULT_ADDR: http://vault.example.com:8200
  image: vault:latest
  id_tokens:
    VAULT_ID_TOKEN:
      aud: http://vault.example.com
  # Store the the secret value in the DATABASE_PASSWORD environment variable
  script:
    - export DATABASE_PASSWORD="$(vault kv get -field=password secret/myproject/example/db)"

The following diagram shows the steps a GitLab CI/CD pipeline takes to retrieve a secret from Vault. GitLab Vault workflow

Dynamic secrets

GitLab users are also able to take advantage of Vault dynamic secrets engines. Once you set up JWT authentication to Vault as described above, you can enable a dynamic secrets engine such as AWS secrets engine in Vault. The AWS secrets engine allows the GitLab CI/CD jobs to request short-lived dynamic AWS credentials.

The following is an example of using dynamic AWS credentials in a GitLab job.

Note

If you're signing requests to AWS, you may need to set AWS_SESSION_TOKEN in the following example.

read_secrets:
  image: hashicorp/vault:latest
  script:
    # jq must be installed
    # set the dynamic aws credentials to AWS_CREDS variable
    - export AWS_CREDS="$(vault read aws/creds/my-role -format=json)"
    # use jq to parse AWS_CREDS and set the AWS access_key to AWS_ACCESS_KEY_ID
    - AWS_ACCESS_KEY_ID=$(echo "${AWS_CREDS}" | jq -r .data.access_key)
    - export AWS_ACCESS_KEY_ID
    # use jq to parse AWS_CREDS and set the AWS secret_key to AWS_SECRET_ACCES_KEY
    - AWS_SECRET_ACCESS_KEY=$(echo "${AWS_CREDS}" | jq -r .data.secret_key)
    - export AWS_SECRET_ACCESS_KEY
    # uncomment next two lines to use set a session token if required
    #- AWS_SESSION_TOKEN=$(echo "$(AWS_CREDS}" | jq -r .data.security.token)
    #- export AWS_SESSION_TOKEN

GitLab Community Edition users can pull secrets from Vault.

You must manually set the authentication environment variables to do so.

read_secrets:
  image: hashicorp/vault:latest
  id_tokens:
    VAULT_AUTH_TOKEN:
      aud: https://gitlab.com
  script:
    - export VAULT_ADDR=http://vault.example.com:8200
    # authenticate and get token. Token expiry time and other properties can be configured
    # when configuring JWT Auth - https://developer.hashicorp.com/vault/api-docs/auth/jwt#parameters-1
    - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-staging jwt=$VAULT_AUTH_TOKEN)"
    # use the VAULT_TOKEN to read the secret and store it in an environment variable
    - export PASSWORD="$(vault kv get -field=password secret/myproject/staging/db)"

Once you set the Vault authentication environment variables, you can pull static and dynamic secrets through the CLI, as covered in the GitLab Premium tab.

HashiCorp resources:

External resources:

Authenticating and reading secrets with HashiCorp Vault
Using external secrets in CI
Guy Barros, a Senior Solutions Engineer at HashiCorp, maintains a repository with Terraform code to automate the JWT auth method integration between HCP Vault Dedicated and GitLab. Barros demonstrates how to use the Terraform code in the Codify your JWT-OIDC Vault auth method with Terraform HashiTalks video.
GitLab Unfiltered - How to integrate GitLab CI with HashiCorp Vault to retrieve secrets (via JWT or "secrets:"), uses AWS Quick Start to launch HashiCorp Vault on AWS, and demonstrates how to set up policies, roles, and authentication to Vault.

Next steps

In this section of managing CI/CD secrets, you learned about GitLab and Vault integration. GitLab and Vault integration is part of the Secure systems pillar.