How to use SecretHub with CircleCI

This guide shows you how you can load secrets from SecretHub into your CircleCI jobs, using the SecretHub CircleCI Orb. You’ll be able to reference secrets in your .circleci/config.yml file without exposing them or having to manually enter them in a GUI.

Before you begin

Before you start, make sure you have completed the following steps:

1. Set up SecretHub on your workstation.

Step 1: Import the SecretHub Orb

To use the SecretHub orb in your CircleCI pipeline, import it in your .circleci/config.yml. Make sure you set the version of your CircleCI configuration syntax to 2.1:

version: 2.1
orbs:
  secrethub: secrethub/cli@1.1.0

Step 2: Load secrets into your job

With the orb ready to go, you can now use it to load secrets into your CircleCI jobs.

The simplest use case is to just replace your run steps with secrethub/exec. Whatever you set as its command will be executed, but with the secrets it needs automatically loaded in as environment variables:

version: 2.1
orbs:
  secrethub: secrethub/cli@1.1.0

jobs:
  deploy:
    docker:
      - image: 'cimg/base:stable'
    environment:
      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
    steps:
      - checkout
      - secrethub/exec:
          step-name: Deploy my app
          command: ./deploy-my-app.sh

workflows:
  deploy:
    jobs:
      - deploy

In the environment stanza, the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables use the secret reference syntax (secrethub://) to refer to a secret in SecretHub.

Reference tags can be declared at any level in the file, in CircleCI Contexts, or in the project settings, as long as they’re somehow available as environment variables to the command.

Any secrets (accidentally) printed to stdout or stderr will get masked automatically, so they won’t end up in any CircleCI job logs.

💡 Loading secrets into other orb commands

If you need to load secrets into other orb commands instead of plain run steps, you can do so by overriding the job’s shell:

version: 2.1
orbs:
  aws-cli: circleci/aws-cli@1.3.0
  secrethub: secrethub/cli@1.1.0

jobs:
  deploy:
    environment:
      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
    executor: aws-cli/default
    shell: secrethub run -- /bin/bash
    steps:
      - secrethub/install
      - checkout
      - aws-cli/setup
      - run: aws s3 sync . s3://my-app-bucket

workflows:
  deploy:
    jobs:
      - deploy

Just like before, you specify which secrets the job needs in the environment stanza.

But now, instead of using the secrethub/exec command, you wrap the job’s shell with secrethub run, so that any commands (including the ones in third-party orbs) will be wrapped in secrethub run -- and get access to the referenced secrets.

Also, just like secrethub/exec, any (accidentally) printed secrets will get masked from the logs.

💡 Loading secrets into other orb jobs

To provide other orb jobs with secrets, you can use the secrethub/env-export command as a ‘pre-step’ to the job to make secrets available for the scope of the respective orb job:

version: 2.1
orbs:
  docker: circleci/docker@1.5.0
  secrethub: secrethub/cli@1.1.0

workflows:
  publish:
    jobs:
      - docker/publish:
          image: company/app
          pre-steps:
            - secrethub/env-export:
                secret-path: company/app/docker/username
                var-name: DOCKER_LOGIN
            - secrethub/env-export:
                secret-path: company/app/docker/password
                var-name: DOCKER_PASSWORD

💡 Using the SecretHub CLI directly

For more control, you can also use the secrethub/install command to just install the SecretHub CLI so you can use plain CLI commands like secrethub read or secrethub inject directly in your run steps:

version: 2.1
orbs:
  secrethub: secrethub/cli@1.1.0

jobs:
  deploy:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - checkout
      - setup_remote_docker
      - secrethub/install
      - run: >
          docker login -u $(secrethub read company/app/docker/username) -p $(secrethub read company/app/docker/password)
          docker build -t company/app:${CIRCLE_SHA1:0:7} .
          docker push company/app:${CIRCLE_SHA1:0:7}

workflows:
  deploy:
    jobs:
      - deploy

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.

Step 4: Provide the credential to CircleCI

1. Open the CircleCI web app and go to your project’s settings page

1. Click on Environment Variables under Build Settings

1. Click on Add Variable
2. Set the variable name to SECRETHUB_CREDENTIAL and paste the key from the previous step into the value field

1. Click on Add Variable

You have now successfully configured your CircleCI pipeline to fetch secrets from SecretHub.

Happy coding!