Using external secrets in CI

After configuring your Vault server, you can use the secrets stored in Vault by defining them with the vault keyword:

secrets:
  DATABASE_PASSWORD:
    vault: production/db/password@ops  # translates to secret `ops/data/production/db`, field `password`

In this example:

• production/db - The secret.
• password The field.
• ops - The path where the secrets engine is mounted.

After GitLab fetches the secret from Vault, the value is saved in a temporary file. The path to this file is stored in a CI/CD variable named DATABASE_PASSWORD, similar to variables of type file.

To overwrite the default behavior, set the file option explicitly:

secrets:
  DATABASE_PASSWORD:
    vault: production/db/password@ops
    file: false

In this example, the secret value is put directly in the DATABASE_PASSWORD variable instead of pointing to a file that holds it.

For more information about the supported syntax, read the .gitlab-ci.yml reference.

Configure Vault server roles

When a CI job attempts to authenticate, it specifies a role. You can use roles to group different policies together. If authentication is successful, these policies are attached to the resulting Vault token.

all match for authentication to be successful.

Combining bounded claims with GitLab features like user roles and protected branches, you can tailor these rules to fit your specific use case. In this example, authentication is allowed only for jobs running for protected tags with names matching the pattern used for production releases:

$ vault write auth/jwt/role/myproject-production - <<EOF
{
  "role_type": "jwt",
  "policies": ["myproject-production"],
  "token_explicit_max_ttl": 60,
  "user_claim": "user_email",
  "bound_claims_type": "glob",
  "bound_claims": {
    "project_id": "42",
    "ref_protected": "true",
    "ref_type": "tag",
    "ref": "auto-deploy-*"
  }
}
EOF

For a full list of CI_JOB_JWT claims, read the How it works section of the Authenticating and Reading Secrets With HashiCorp Vault tutorial.

You can also specify some attributes for the resulting Vault tokens, such as time-to-live, IP address range, and number of uses. The full list of options is available in for the JSON web token method.

Using a self-signed Vault server

When the Vault server is using a self-signed certificate, you will see the following error in the job logs:

ERROR: Job failed (system failure): resolving secrets: initializing Vault service: preparing authenticated client: checking Vault server health: Get https://vault.example.com:8000/v1/sys/health?drsecondarycode=299&performancestandbycode=299&sealedcode=299&standbycode=299&uninitcode=299: x509: certificate signed by unknown authority

You have two options to solve this error:

• Add the self-signed certificate to the GitLab Runner server’s CA store. If you deployed GitLab Runner using the Helm chart, you will have to create your own GitLab Runner image.
• Use the VAULT_CACERT environment variable to configure GitLab Runner to trust the certificate:
  • If you are using systemd to manage GitLab Runner, see how to add an environment variable for GitLab Runner.
  • If you deployed GitLab Runner using the Helm chart:
    1. Provide a custom certificate for accessing GitLab, and make sure to add the certificate for the Vault server instead of the certificate for GitLab. If your GitLab instance is also using a self-signed certificate, you should be able to add both in the same Secret.

    2. Add the following lines in your values.yaml file:

       ## Replace both the <SECRET_NAME> and the <VAULT_CERTIFICATE>
       ## with the actual values you used to create the secret
       
       certsSecretName: <SECRET_NAME>
       
       envVars:
         - name: VAULT_CACERT
           value: "/home/gitlab-runner/.gitlab-runner/certs/<VAULT_CERTIFICATE>"