How to manage secrets in Jenkins
This guide shows you how you can use SecretHub for your pipeline secrets. You’ll be able to define the required secrets in the Jenkinsfile
.
Before you begin
Before you start, make sure you have completed the following steps:
- Set up SecretHub on your workstation.
- Have Jenkins installed and have working knowledge of it
- Have Docker installed on your Jenkins server
This guide uses Jenkins version 2.190.1
Step 1: Write your secrets to SecretHub
If you haven’t done so already, store your secrets on SecretHub. You can use the following commands to get everything set up:
-
secrethub repo init
to create a repository -
secrethub mkdir
to create a directory -
secrethub write
to write some secrets
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 the Jenkinsfile
To configure your Jenkins pipeline add a file named Jenkinsfile
to your repository:
pipeline {
agent {
dockerfile true
}
environment {
SECRETHUB_CREDENTIAL = credentials('secrethub_credential')
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'
}
stages {
stage('deploy') {
steps {
sh 'secrethub run -- ./deploy.sh'
}
}
}
}
In the agent
block, it is specified that the Docker container should be based on a Docker image. We’ll set that up in the next step.
In the environment
block, the credential used for authenticating to the SecretHub API is read and assigned to the environment variable named SECRETHUB_CREDENTIAL
.
Furthermore, AWS environment variables are set to reference a path on SecretHub.
In the stages
block, you see the deploy step wrapped in the secrethub run
command.
run
replaces the secret references in the environment of the subcommand (./deploy.sh
in this case) 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: Add SecretHub to the Dockerfile
The previous Jenkinsfile requires the SecretHub CLI to be installed.
To make sure that this is the case, you can configure the Jenkins agent to run the pipeline in a Docker container with SecretHub installed on it.
To achieve this, place a Dockerfile
similar to this one in your project’s root directory:
FROM alpine
RUN apk add --repository https://alpine.secrethub.io/alpine/edge/main --allow-untrusted secrethub-cli
This file ensures that the SecretHub CLI is installed in the container in which the job is executed.
Note that Jenkins will use this container image for the pipeline since this has been previously specified in the Jenkinsfile’s agent
block.
Step 4: Create a SecretHub service account
Your own SecretHub account is meant to be used only by you. To give the Jenkins server access to your secrets you can create a service account for it.
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 automatically grant the service read access to the specified repo.
Note that you can use the --clip
flag to automatically write the output of the command to your clipboard:
secrethub service init --clip --permission read company/app
Step 5: Provide the service credential to the server
The next step is to provide the generated credential to the Jenkins server in order to authenticate the pipeline to SecretHub.
- Log in to the Jenkins server’s web interface
- Go to Credentials > System > Global Credentials
</figure>
- Click on Add Credentials
</figure>
- Fill in the form, then click OK:
- Set the
Kind
field toSecret text
- Input the previously generated account credential in the
Secret
field - Set the
Id
field tosecrethub_credential
- Add a suitable description in the
Description
field
- Set the
</figure>
For a detailed explanation of how credentials are handled in Jenkins, check out Using credentials.
You have successfully configured your Jenkins pipeline to automatically fetch secrets from the SecretHub API, and thus also simpified secret provisioning when running code locally or in production!
See also
- If you run Jenkins on AWS, check out the AWS integration.
- For more information about the run command, check out the documentation.
- For more details about SecretHub services check out the documentation.
Happy coding!