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:
- 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
- Open the CircleCI web app and go to your project’s settings page

- Click on
Environment Variables
underBuild Settings

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

- Click on
Add Variable
You have now successfully configured your CircleCI pipeline to fetch secrets from SecretHub.
Happy coding!