Jenkins customers commonly ask for tips about how to inject secrets into their build jobs. This article summarizes the current best-practices for accomplishing this.
Install the Credentials Plugins
If you haven’t already, install the latest versions of these plugins into your Jenkins instance.
- Credentials plugin - provides a centralized way to define credentials that can be used by your Jenkins instance, plugins and build jobs.
- Credentials Binding plugin - allows you to configure your build jobs to inject credentials as environment variables.
- Plain Credentials plugin - a plugin dependency required by the Credentials Binding plugin.
Note: If you do not see these plugins in your list of available plugins, try refreshing the list of available plugins using the [Check now] button on the Advanced tab of the plugin management page. Also, be sure to restart Jenkins after installing the plugins.
Defining Credentials and Secrets
After installing the credentials plugins, your Jenkins sidebar will contain a new *Credentials* page that can be used to define credentials and secrets. The easiest way to define secrets for use in your build jobs is to:
- Click the **Credentials** link in the sidebar
- Click on the **Global credentials** domain
- Click [**Add Credential**]
- Select a credential kind that can be used from your build jobs (later, using a credentials binding). The following types of credentials are most useful to use from your build jobs.
- Username with password - a username/password pair
- Secret file - an uploaded file
- Secret text - a raw secret string
Note: be sure keep the default “Global” scope for credentials that need to be accessible to build jobs.
Note: be sure to specify the ID for the credential because that is how it is referenced in the job when using the
parameter expression option.
Using Credentials and Secrets from Build Jobs
After installing the Credentials Bindings plugin, the *Build Environment* section of your build job *Configuration* page will include a new option to “Use secret text(s) or file(s)”. Enabling this option allows you add credential bindings where the *Variable* value will be used as the name of the environment variable that your build can use to access the value of the credential.
Normally you will start your script with
so that commands you run are not echoed to the log, in case you mention the values of secrets in those commands.
The credential value will vary based on the kind of credential:
Secret text bindings are injected as a raw secret string
Shell example: Echo a secret text binding
# MY_SECRET is injected from a secret text binding as defined in Credentials. echo "My secret is $MY_SECRET"
Username with password bindings are injected as a **username:password** formatted string
Shell example: Split a username and password binding into variables named MY_USERNAME and MY_PASSWORD.
# MY_SECRET_USER injected from username and password binding # The username and password can be conjoined or separated MY_USERNAME=`echo $MY_SECRET_USER` #separated example MY_PASSWORD=`echo $MY_SECRET_USER_PASSWORD` #separated example MY_USERNAME and MY_PASSWORD=`echo $MY_CREDENTIALS` #conjoined example
Secret file bindings are injected as filesystem path to the uploaded secret file
Shell example: Read the data from a secret file binding into a local variable
# MY_SECRET_FILE path injected from secret file binding MY_FILE_DATA=`cat $MY_SECRET_FILE` echo "The secret file data is: $MY_FILE_DATA"
Using Folders to control Credential usage
In larger build environments, it may be preferable to avoid putting all credentials into the Global domain (where they can be used by any build) and instead make it so that only some build jobs have access to certain credentials. This can be accomplished using the Folders plugin. The Credentials plugin is folder-aware and will enhance the Configure page for Folders with a Credentials section. Credentials defined on a folder can only be used by builds within that folder.
You can further secure access to credentials to only specific users in your organization by combining the Credentials and Folder plugins with theRole Based Access Control plugin (available via CloudBees Jenkins Enterprise or DEV@cloud).