GitLab logo

How to manage secrets in GitLab CI

This guide shows you how you can use SecretHub for your pipeline secrets. You’ll be able to define the required secrets in the .gitlab-ci.yml.

Before you begin

To follow along, you will need to:

Step 1: Write your secrets

If you haven’t done so already, store your secrets on SecretHub. You can use the following commands to get everything set up:

In the examples we’ll be using two AWS secrets: company/app/aws/access_key_id and company/app/aws/secret_access_key, but the same principle applies to all secrets.

Step 2: Set up your GitLab CI configuration

To configure your Gitlab CI pipeline add a file named .gitlab-ci.yml to your repository, similar to this one:

image: alpine

stages:
    - deploy

deploy:
    stage: deploy
    variables:
      AWS_REGION: us-east-1
      AWS_ACCESS_KEY_ID: secrethub://company/app/aws/access_key_id
      AWS_SECRET_ACCESS_KEY: secrethub://company/app/aws/secret_access_key
    before_script:
        - apk add --repository https://alpine.secrethub.io/alpine/edge/main --allow-untrusted secrethub-cli
    script:
        - secrethub run -- ./deploy.sh

There are three things to note here: Fist of all, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set to reference the path at which they’re on SecretHub.

Furthermore, the command in the before_script section installs the SecretHub CLI. The CLI will be used later to provision the secrets. Alternatively, you can include the installation in the docker image on which the job runs, to save one step every time your job is executed.

The last thing to note is that the command that requires secrets, ./deploy.sh in this case, is wrapped with the secrethub run command. run replaces the secret references in the environment of the subcommand with the secret values.

For jobs that you’d like to be able to run locally as well (e.g. your tests), consider using environment files. They’re also a good fit if you have secrets for multiple environments, as they support templating.

Step 3: Create a SecretHub service account

SecretHub uses service accounts to grant non-human parties (such as CIs) access to secrets.

To create a service account, run the secrethub service init command:

secrethub service init --permission read company/app

This command will output the generated account credential. Make sure to copy it as it will be needed in the next step.

The --permission read flag will grant the service read access to the specified repo.

Note that you can use the --clip flag to write the output of the command to your clipboard:

secrethub service init --clip --permission read company/app

Step 4: Provide the credential to GitLab CI

  1. Open your GitLab project in the browser and go to the Settings, CI / CD page.
    Go to the settings, CI / CD page in the GitLab web app
  2. Scroll to the Variables section and click on expand.
    Scroll to the variables section and click on expand
  3. Set the variable type to Variable, the key to SECRETHUB_CREDENTIAL and the value to the credential generated in the previous step. Make sure to tick Protected and choose the appropriate scope of this variable.
    Set type, key and value to variable, SECRETHUB_CREDENTIAL and the previously generated key respectively

    Note that GitLab does not support masking the SECRETHUB_CREDENTIAL since it contains a . character.

  4. Click on Save variables.

You have successfully configured your GitLab CI/CD pipeline to fetch secrets from SecretHub. Moreover, you can now rotate your secrets and the pipeline will automatically use their latest version.

See also

Happy coding!