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:

1. Set up SecretHub on your workstation.
2. Have Jenkins installed and have working knowledge of it
3. 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.

1. Log in to the Jenkins server’s web interface
2. Go to Credentials > System > Global Credentials

   

</figure>

1. Click on Add Credentials

   

</figure>

1. Fill in the form, then click OK:
   • Set the Kind field to Secret text
   • Input the previously generated account credential in the Secret field
   • Set the Id field to secrethub_credential
   • Add a suitable description in the Description field

   

</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!