Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Allows credentials to be bound to environment variables for use from miscellaneous build steps.

Plugin Information

View Credentials Binding on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

You may have a keystore for jarsigner, a list of passwords, or other confidential files or strings which you want to be used by a job but which should not be kept in its SCM, or even visible from its config.xml. Saving these files on the server and referring to them by absolute path requires you to have a server login, and does not work on slaves. This plugin gives you an easy way to package up all a job’s secret files and passwords and access them using a single environment variable during the build.

To use, first go to the Credentials link and add items of type Secret file and/or Secret text. Now in a freestyle job, check the box Use secret text(s) or file(s) and add some variable bindings which will use your credentials. The resulting environment variables can be accessed from shell script build steps and so on. (You probably want to start any shell script with set +x, or batch script with @echo off. JENKINS-14731).

For more details of how this works, check the Injecting Secrets into Jenkins Build Jobs article at CloudBees.

From a Pipeline job, define your credentials, then check Snippet Generator for a syntax example of the withCredentials step. Any secrets in the build log will be masked automatically.

A typical example of a username password type credential (example from here) would look like: 

withCredentials([usernamePassword(credentialsId: 'amazon', usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD')]) {
  // available as an env variable, but will be masked if you try to print it out any which way
  // note: single quotes prevent Groovy interpolation; expansion is by Bourne Shell, which is what you want
  sh 'echo $PASSWORD'
  // also available as a Groovy variable
  // or inside double quotes for string interpolation
  echo "username is $USERNAME"


Version 1.19 (2019-05-31)

  • JENKINS-42950 - Getting issue details... STATUS  Expanded secret masking to include some variants commonly produced by shells when metacharacters are involved.

Version 1.18 (2019-02-25)

  • JENKINS-42950 - Getting issue details... STATUS  Better documentation about limitations and best practices.
  • JENKINS-49337 - Getting issue details... STATUS  Avoiding blocking the Pipeline interpreter during block cleanup even if Remoting hangs.
  • Avoid printing a stack trace when a credentialsId  is not found.

Version 1.17 (2018-10-29)

  • Improved stream flush behavior in light of JEP-210.

Version 1.16 (Mar 19, 2018)

Version 1.15 (Feb 05, 2018)

Version 1.14 (Jan 17, 2018)

  • JENKINS-37871 - Getting issue details... STATUS  Adjusted order of freestyle build wrapper relative to other wrappers.
  • JENKINS-48118 - Getting issue details... STATUS  Metadata fixes useful for plugin-compat-tester.

Version 1.13 (Aug 08, 2017)

  • JENKINS-28399 Binding type for SSH user private key credentials.

  • JENKINS-41760 Corrupted output when no credentials were specified, or a supposed secret was in fact blank.

  • JENKINS-43199 File descriptor leak when using build wrapper.

Version 1.12 (Jun 15, 2017)

  • Binding type for certificate credentials.
  • New APIs AbstractOnDiskBinding and UnbindableDir.

Version 1.11 (Mar 30, 2017)

  • JENKINS-42999 Allow non-file-based credentials to be used from withCredentials outside a node block.
  • Japanese localization.

Version 1.10 (Nov 07, 2016)

  • JENKINS-24805 Mask passwords in freestyle builds, not just in Pipeline builds.
  • Masking did not work correctly if some secrets were a substring of others.
  • JENKINS-38831 Track credentials usage.
  • Adding symbols to binding types for better readability in Pipeline (and probably also Job DSL).

Version 1.9 (Aug 19, 2016)

  • JENKINS-37541 prevent NPE while reading back SecretBuildWrapper
  • Migrate to new parent pom 

Version 1.8 (Jun 10, 2016)

Version 1.7 (Mar 03, 2016)

Version 1.6 (Oct 16, 2015)

  • JENKINS-30941 Fixed regression in 1.5 affecting ZIP file bindings.
  • Resource leak potentially affecting ZIP file bindings.
  • JENKINS-30326 updated dependency on credentials plugin to 1.23

Version 1.5 (Aug 06, 2015)

  • JENKINS-29255 Set restrictive file permission on Secret File binding, to make it easier to use an SSH private key this way.

Version 1.4 (Apr 01, 2015)

  • Updated to Jenkins 1.596.1 and Workflow 1.5.
  • JENKINS-27486 withCredentials step should mask any passwords accidentally printed to the log.
  • JENKINS-27631 withCredentials step should not store passwords even temporarily in program.dat in the build directory.
  • JENKINS-27389 withCredentials step was exposing variables to external processes but not to Groovy code using env.PASSWORD syntax.
  • Improved help for withCredentials.
  • Improved error diagnostics for withCredentials.

Version 1.3 (Jan 20, 2015)

  • JENKINS-26051 Added withCredentials Workflow step. Blog
  • JENKINS-23468 Allowed username & password to be bound to separate variables.
  • SPI changes to permit the above two features.

Version 1.2 (Oct 07, 2014)

  • SECURITY-158 fix.

Version 1.1 (Aug 11, 2014)

  • Add support for parameterized credentials (from credentials plugin 1.16.1)

Version 1.0 (Jun 16, 2014)

First general release.

  • Supporting username/password credentials.
  • Marking added environment variables as “sensitive”, so other code showing them should display the values masked.

Version 1.0 beta 1 (Oct 01, 2013)


  1. Unknown User (walterk82)

    How do I use the Parameter expression option with version 1.1?

    I get the validation message "A valid parameter expression consists of the parameter name enclosed within ${ and }" but what is the parameter name?

    1. Unknown User (jglick)

      You would need to define a parameter and specify its name. The Credentials plugin offers a parameter type.

      1. Unknown User (wowberk)

        Tengo varias credenciales con ID X1 X2 X3 y tengo tambien un active Choice Parameter con nombre GRUPOPWD con Grovy Script
        return [

        and return 

        FATAL: Could not find credentials entry with ID '${ GRUPOPWD }'
        org.jenkinsci.plugins.credentialsbinding.impl.CredentialNotFoundException: Could not find credentials entry with ID '${ GRUPOPWD }'
        at org.jenkinsci.plugins.credentialsbinding.MultiBinding.getCredentials(MultiBinding.java:153)
        at org.jenkinsci.plugins.credentialsbinding.impl.UsernamePasswordMultiBinding.bind(UsernamePasswordMultiBinding.java:76)
        at org.jenkinsci.plugins.credentialsbinding.impl.SecretBuildWrapper.setUp(SecretBuildWrapper.java:88)
        at hudson.model.Build$BuildExecution.doRun(Build.java:157)
        at hudson.model.AbstractBuild$AbstractBuildExecution.run(AbstractBuild.java:490)
        at hudson.model.Run.execute(Run.java:1735)
        at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:43)
        at hudson.model.ResourceController.execute(ResourceController.java:97)
        at hudson.model.Executor.run(Executor.java:405)
        Finished: FAILURE

  2. Unknown User (kakapo4)

    Is it possible to generate the credentials key from a regular choice or string parameter?

    E.g. I have a job that does some database maintenance. It has a "Database" parameter which gives the user a choice of the database to work on. E.g "DB1", "DB2" etc

    I'd like to be able to select the credentials to use based on the selected Database.E.g. to have credentials "DB1_Credentials", "DB2_Credentials" etc. The credentials to use would be identified by concatenating the Database with "_Credentials".

    It looks at present like I'd have to add a matching credentials parameter and rely on the user selecting the one that matches their selected Database.

    1. Unknown User (jglick)

      You could do it that way. For such a customized use case I would recommend using Workflow.

  3. Unknown User (sand33p)


    When using the credentials-binding plugin to provide a build job with a username/password global credential pair, the password is exposed as plain text in the build log of the Jenkins job by executing the 'set' command using the 'Execute Windows batch command' build step type.

    Is there a way of masking the password?


    1. Unknown User (jglick)

      @echo off (IIRC), or use the Mask Passwords plugin.

      1. Unknown User (arpitgold)

        I have installed Mask Password plugin, but it is still showing password as clear text. Can you please explain how to use mask password plugin?


        1. Unknown User (jglick)

          That is a question for the Mask Password plugin. Better to use the users’ list rather than wiki comments.

  4. Unknown User (gdameron)

    The Mask Passwords plugin has a security hole: Global passwords are masked in the console, but NOT masked if the job echo's it to a file, and the file is archived. You can see the clear-text password if you click the archive link under "Last Successful Artifacts".

    Does the Credentials Binding Plugin protect passwords any better?

    1. Unknown User (jglick)

      IIRC there is a filed issue. For the Workflow step, yes it works.

  5. Unknown User (venkat)

    Hi, i have added credentials from user's section as i am using jenkins security. So the credentials added by admin in 'credentials' main screen are coming as dropdown list in job but the credentials added under 'user\configuration' are not listing in jobs drop down. Do i need to follow any different way to access credentials under 'user' ? I am using credentials@1.22 and credentailsBinding 1.4.

    1. Unknown User (jglick)

      Not sure if user credentials are supported yet, probably needs investigation.

  6. Unknown User (jhyland87)

    Cab you tell me how secure this is? Id like to store the credentials the application uses to connect to the database, then use them in the job to configure the database. But we could only use this in production if the credentials are encrypted

  7. Unknown User (jhyland87)

    Whats the point of using the Credentials parameter option, of all it does it print out the UUID? What can that be used for?

  8. Unknown User (janfabry)

    The pipeline example could use an update. For example, it was not clear to me that you could bind multiple credentials in one call, and that you don't need the $class: 'SomeBinding' syntax anymore. The pipeline steps documentation is not so clear about this (doesn't document all symbols). The snippet generator does the right thing, but I'm not sure how many people would look there.

    An example that could be used on this page

    // Basic example
    withCredentials([usernamePassword(credentialsId: 'amazon',
                         usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD')]) {
        //available as an env variable, but will be masked if you try to print it out any which way
        sh 'echo $PASSWORD'
        echo "${env.USERNAME}"
    // You can also request multiple credentials in a single call
    withCredentials([usernamePassword(credentialsId: 'amazon',
                         usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD'),
                     string(credentialsId: 'slack-url',
                         variable: 'SLACK_URL'),]) {
        sh 'echo $PASSWORD'
        echo "${env.SLACK_URL}"
    // Older code might not use the new syntax (usernamePassword, string, ...) yet, and directly call the class:
    withCredentials([[$class: 'UsernamePasswordMultiBinding', credentialsId: 'amazon',
                      usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD']]) {
        //available as an env variable, but will be masked if you try to print it out any which way
        sh 'echo $PASSWORD'
        echo "${env.USERNAME}"
  9. Unknown User (kalkrishnan)

    Does this work on Windows? I installed the plugin, but cannot see an option to bind credentials in my pipeline.

    1. Unknown User (kalkrishnan)

      Infact I dont see a Build Environment section at all in the pipeline view.

  10. Unknown User (tmacpherson92)

    Is there a way to disable or configure the password masking feature? This is causing a number of issues for us, as it seems that not only are passwords masked, but usernames as well. This causes commonly used words (such as "jenkins", "android", "artifactory", "admin", etc.) to appear as **** in our console output, as we have credentials with usernames like that. This causes a number of problems with our auditability.

  11. Unknown User (munishm)

    I am getting error on saving my job. Job uses aws binding credentials:

    org.kohsuke.stapler.WrongTypeException: Got type array but no lister class found for type class java.lang.String
    Caused: java.lang.IllegalArgumentException: Failed to convert the credentialsId parameter of the constructor public com.cloudbees.jenkins.plugins.awscredentials.AmazonWebServicesCredentialsBinding(java.lang.String,java.lang.String,java.lang.String)
    Caused: java.lang.IllegalArgumentException: Failed to instantiate class com.cloudbees.jenkins.plugins.awscredentials.AmazonWebServicesCredentialsBinding from {"accessKeyVariable":"AWS_ACCESS_KEY_ID","secretKeyVariable":"AWS_SECRET_ACCESS_KEY","credentialsId":["661501ac-9aa3-4402-9a11-54eef1fc0e7a",""],"stapler-class":"com.cloudbees.jenkins.plugins.awscredentials.AmazonWebServicesCredentialsBinding","$class":"com.cloudbees.jenkins.plugins.awscredentials.AmazonWebServicesCredentialsBinding"}
    Caused: java.lang.Error: Failed to instantiate class com.cloudbees.jenkins.plugins.awscredentials.AmazonWebServicesCredentialsBinding from {"accessKeyVariable":"AWS_ACCESS_KEY_ID","secretKeyVariable":"AWS_SECRET_ACCESS_KEY","credentialsId":["661501ac-9aa3-4402-9a11-54eef1fc0e7a",""],"stapler-class":"com.cloudbees.jenkins.plugins.awscredentials.AmazonWebServicesCredentialsBinding","$class":"com.cloudbees.jenkins.plugins.awscredentials.AmazonWebServicesCredentialsBinding"}
    Caused: javax.servlet.ServletException

    Error screenshot in attachment.

    I have observed that the Credentials section of job changes to CredentialsID. When i created it for the first time it had Credentials Description.
    Has anyone faces issue like this before? This is bugging in for few hours by now.
    What is the fix for this.

  12. Unknown User (jurgenweber)

    can you make this work before SCM? Or in combination with the 'preSCMbuildstep' and 'EnvInject' plugins?

  13. Unknown User (moshe_zvi)

    Is it possible to globally bind credentials to a common environment variable?

    Currently, if I want a credential injected to several jobs, I need to configure the binding in each job separately. 

    It would be nice to be able to globally bind it to a variable (or more, if it's e.g. a username/password combo). 

    I don't think it's a vulnerability, since you can do it anyway from within the jobs (assuming you have access to those jobs). 

  14. Unknown User (matthiasb)

    Sine the last release of this (or in combination with other) plugins we have an issue that we get the following error when we use user own credentials, the same thing with Jenkins global passwords works without any problems:

    org.jenkinsci.plugins.credentialsbinding.impl.CredentialNotFoundException: c5f0107c-13a7-4f59-a089-a3122131bb69

    Is it possible, what here is a critical change in the plugin or is there maybe a conflict with other plugins?
    We use Jenkins 2.89.4 and 2.107.2 in combination with 1.15 und 1.16. 
    We are normally pretty up to date with the plugins.

  15. Unknown User (haroldo_bonette)

    It seems that user and password are not being masked on Blue Ocean UI.

    It does get masked on pipeline.log but for the command bellow it will be shown on Blue Ocean UI:

    withCredentials([usernamePassword(credentialsId: 'MYUSER', usernameVariable: 'USER', passwordVariable: 'PWD')]) {
    bat "psexec -u ${USER} -p ${PWD} \\\\D1220001020A cmd /c \"del /q E:\test.txt\""

    Password is exposed on UI to anyone with access to the project as it can be seen in image bellow:

    Credentials Binding Plugin version 1.17

    Jenkins ver. 2.138.3

    1. Unknown User (jglick)

      Sounds like a bug in Blue Ocean, but anyway read the inline help for the step in Pipeline Syntax which explains why you should not write your script that way to begin with.

      1. Unknown User (haroldo_bonette)

        Hi Jesse, thanks for your reply, I will try to report it under Blue Ocean.

        Btw I checked the inline help but I am still not sure why I should not write the script like this, could you help me to get it clarified? 


        1. Unknown User (jglick)

          A topic for the users’ list, stackoverflow.com, etc. Please do not use comments in Confluence. (I wish we could disable them.)

  16. Unknown User (anthonygreen)

    How is the certificate credentials binding intended to work?
    Having imported a certificate and added certificate binding to the job, there is no documentation on how to use the 3 fields:
    Keystore Variable, Password Variable, Alias Variable