Injecting Secrets into Jenkins Build Jobs

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
    • usernamepassword.png
    • Secret file - an uploaded file
    • secretfile.png
    • Secret text - a raw secret string
    • secrettext.png

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

set +x

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

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).

Alternative ways to inject build variables

Have more questions? Submit a request


  • 0
    Michael Klöckner
    It worked like a charm for me even on an OSS Jenkins installation. I just had to install another plugin to make it work: CloudBees Credetnials Plugin.
  • 0
    Alan Villa

    Is it possible to inject credentials when invoking Ant in Jenkins?

  • 0
    Peter Carr

    re: Ant,

    It possible to load a properties file from an ant script; in theory you could load a secret file.

    Note: I am not using this yet from Jenkins ... because I am browsing this thread to learn how!

  • 0
    Paul Grove

    As this article states this is "current best-practices" maybe then some effort should be made to kill the bugs of the credential bind plugin that makes the best practice insecure. See open for 2 years. Due to this the plugin is disabled in our company, leading to yet more hack workarounds that sap our time. Please fix!

  • 0
    Jj Cm

    Totally agree with Paul.

    The issue seems to be solved, and credentials are now masked on the console output of a job log. However, a simple "echo $MY_SECRET > secret.txt" shows the secret into a text file on the workspace.

    Please fix !


  • 1
    Jesse Glick

    Jj Cm: as designed. Masking only exists to reduce the chance of accidental disclosure.

  • 0
    Cola Vn


    I've been trying to use the same thing for my username and password but when I echo, I get **** as the output.

    I've followed all of the instructions above and I've created the credentials as global in the credential management page. Is there any mistake im making?

    Much thanks! :D


  • 1
    Arnaud Heritier

    Hi Cola,

      Like said Jesse this is as designed. We are masking them in the console to reduce the chance of accidental disclosure.

    Best regards


  • 1
    Cola Vn

    Hi Arnaud,


    Thanks for the response. However, where can we use these variables then? They're set as env variables but I'm not able to access them. When I say access, forget echo, but if I need to send them along with a curl call, how do I use them? My requirement is to send them via a curl call, the echo was just for testing.



  • 0
    Manuel Hutter

    Hi Jesse & Arnaud,

    I have the same problem as Cola. How do I use my secret text in a CURL request?

    Currently all I get is the ID of the secret, but not the secret itself...

  • 0
    Jesse Glick

    @Manuel I am not sure how that could happen. If you are a CloudBees customer, please file a support request.

Please sign in to leave a comment.