Inject secrets into builds

When creating Freestyle and Pipeline jobs, use credentials to access various build tools, such as your source code management (SCM) tool, artifact directory, and so on. These credentials are highly sensitive and should not be visible in the build logs. To prevent exposing sensitive credentials and secrets, CloudBees recommends using the following approach to injecting secrets into builds.

Prerequisites

Install the latest versions of the following plugins into your CloudBees CI instance:

Credentials plugin: provides a centralized way to define credentials that can be used by your CloudBees CI instance, plugins, and build jobs.
Credentials Binding plugin: allows you to configure your build jobs to inject credentials as environment variables.

If these plugins are not listed, try to refresh the list of available plugins using Check now on the Advanced tab of the Plugin Management page. Also, be sure to restart CloudBees CI after you install the plugins.

Define credentials and secrets

The first step to inject secrets into builds is to add the secrets to the Jenkins Credentials Provider in CloudBees CI. Afterward, you can inject them as environment variables for builds to use.

The default global scope is required for credentials that need to be accessible to build jobs.

To define credentials and secrets in your build jobs:

Select your user name in the top navigation bar.
Select Credentials in the left pane.
Under Stores from parent, select (global) in the Domains column.
Select Add Credentials in the left pane.
Select a credential type from the Kind options and enter the required information.

The following examples illustrate some of the different types of credentials that are most useful to use in build jobs:
- Username with password
- Secret file
- Secret text
Select OK.

Specify the ID for the credential because that is how it is referenced in the job when using the parameter expression option.

The complete list of secret types may vary from one instance to another as plugins contribute to secret types.

Use credentials and secrets in pipelines

The credentials you created in CloudBees CI are injected in a Pipeline using the withCredentials step. Depending on the credential type, the syntax varies. The best way to find the exact syntax you need for a given credential type is to use the Pipeline Snippet Generator.

To generate the withCredentials step with the Pipeline Snippet Generator:

From a Pipeline job configuration page, select Pipeline Pipeline Syntax.
Select the withCredentials: Bind credentials to variables Sample Step.
Enter a Username Variable and Password Variable.
Select the global credentials you created.
Select Generate Pipeline Script.
Copy the Pipeline script and paste it into the script area in the Pipeline job configuration page.
Select Save.

The variable you defined in the withCredentials step will then be available in the withCredentials scope. For example:

withCredentials([usernamePassword(credentialsId: 'mycompany-github-creds', passwordVariable: 'pass', usernameVariable: 'user')]) {
    // the code here can access $pass and $user
}▼

When you work with sensitive credentials in a Pipeline, it is important to understand how string interpolation works, so that sensitive credentials are not displayed. See String interpolation for more information.

Use credentials and secrets in non-pipeline jobs

The credentials you create in CloudBees CI are injected in a non-pipeline job in various ways, depending on the credential type.

To inject secrets into non-pipeline jobs:

Select the Use secret text(s) or file(s) checkbox in the Build Environment section of your non-pipeline build job.
Select a secret type from the Add dropdown menu.
Enter the Variable(s) and select the Credentials you want to use.

This option allows you to add credential bindings where the Variable value is used as the name of the environment variable that your build can use to access the value of the credential.
You can use the variables you have created in your build steps as illustrated in the following examples:
- Secret text bindings are injected as a raw secret string:
- Username and password (conjoined) bindings are injected as a username:password formatted string:
- Username and password (separated)
- Secret file bindings are injected as filesystem paths to the uploaded secret file:
Select Save.

Use folders to control credentials usage

In larger build environments, it may be preferable to avoid putting all credentials into the Jenkins Credentials Provider, where they can be used by any build. Instead, you can limit access to certain credentials by using the Folders plugin. The Credentials plugin is folder-aware and enhances the left navigation pane with a folders section under credentials.

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 the CloudBees Role-Based Access Control (RBAC) plugin. By combining RBAC with the Folders and Credentials plugins, administrators can control the builds that have access to credentials and the users who have access to builds that use the credentials. See Restricting access and delegating administration with Role-Based Access Control for more information.