The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
For a list of other such plugins, see the Pipeline Steps Reference page.
withCredentials
: Bind credentials to variables Allows various kinds of credentials (secrets) to be used in idiosyncratic ways. (Some steps explicitly ask for credentials of a particular kind, usually as a credentialsId
parameter, in which case this step is unnecessary.) Each binding will define an environment variable active within the scope of the step. You can then use them directly from any other steps that expect environment variables to be set:
node {
withCredentials([usernameColonPassword(credentialsId: 'mylogin', variable: 'USERPASS')]) {
sh '''
set +x
curl -u "$USERPASS" https://private.server/ > output
'''
}
}
As another example (use Snippet Generator to see all options):
node {
withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
sh '''
set +x
curl -H "Token: $TOKEN" https://some.api/
'''
}
}
Note the use of single quotes to define the script
(implicit parameter to sh
) in Groovy above. You want the secret to be expanded by the shell as an environment variable. The following idiom is potentially less secure, as the secret is interpolated by Groovy and so (for example) typical operating system process listings will accidentally disclose it:
node {
withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
sh /* WRONG! */ """
set +x
curl -H 'Token: $TOKEN' https://some.api/
"""
}
}
At least on Linux, environment variables can be obtained by other processes running in the same account, so you should not run a job which uses secrets on the same node as a job controlled by untrusted parties. In any event, you should always prefer expansion as environment variables to inclusion in the command, since Jenkins visualizations such as Blue Ocean will attempt to detect step parameters containing secrets and refuse to display them.
The secret(s) will be masked (****
) in case they are printed to the build log. This prevents you from accidentally disclosing passwords and the like via the log. (Bourne shell set +x
, or Windows batch @echo off
, blocks secrets from being displayed in echoed commands; but build tools in debug mode might dump all environment variables to standard output/error, or poorly designed network clients might display authentication, etc.) The masking could of course be trivially circumvented; anyone permitted to configure a job or define Pipeline steps is assumed to be trusted to use any credentials in scope however they like.
Beware that certain tools mangle secrets when displaying them. As one example, Bash (as opposed to Ubuntu’s plainer Dash) does so with text containing '
in echo mode:
$ export PASS=foo"'"bar
$ env|fgrep PASS
PASS=foo'bar
$ sh -xc 'echo $PASS'
+ echo foo'bar
foo'bar
$ bash -xc 'echo $PASS'
+ echo 'foo'\''bar'
foo'bar
Mangled secrets can only be detected on a best-effort basis. By default, Jenkins will attempt to mask mangled secrets as they would appear in output of Bourne shell, Bash, Almquist shell and Windows batch. Without these strategies in place, mangled secrets would appear in plain text in log files. In the example above, this would result in:
+ echo 'foo'\''bar'
****
This particular issue can be more safely prevented by turning off echo with set +x
or avoiding the use of shell metacharacters in secrets.
For bindings which store a secret file, beware that
node {
dir('subdir') {
withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
sh 'use $FILE'
}
}
}
is not safe, as $FILE
might be inside the workspace (in subdir@tmp/secretFiles/
), and thus visible to anyone able to browse the job’s workspace. If you need to run steps in a different directory than the usual workspace, you should instead use
node {
withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
dir('subdir') {
sh 'use $FILE'
}
}
}
to ensure that the secrets are outside the workspace; or choose a different workspace entirely:
node {
ws {
withCredentials([file(credentialsId: 'secret', variable: 'FILE')]) {
sh 'use $FILE'
}
}
}
Also see the Limitations of Credentials Masking blog post for more background.
bindings
aws
accessKeyVariable
AWS_ACCESS_KEY_ID
will be used.
String
secretKeyVariable
AWS_SECRET_ACCESS_KEY
will be used.
String
credentialsId
String
roleArn
(optional)
String
roleSessionDurationSeconds
(optional)
int
roleSessionName
(optional)
String
token
variable
String
credentialsId
String
$class: 'AwsBucketCredentialsBinding'
usernameVariable
String
passwordVariable
String
credentialsId
String
certificate
ps e
.
keystoreVariable
String
credentialsId
String
aliasVariable
(optional)
String
passwordVariable
(optional)
String
ConjurSecretApplianceCredentials
credentialsId
String
sPath
(optional)
String
variable
(optional)
String
conjurSecretCredential
credentialsId
String
variable
(optional)
String
conjurSecretUsername
credentialsId
String
passwordVariable
(optional)
String
usernameVariable
(optional)
String
conjurSecretUsernameSSHKey
credentialsId
String
secretVariable
(optional)
String
usernameVariable
(optional)
String
dockerCert
variable
{ca,cert,key}.pem
files will be created.
DOCKER_CERT_PATH
, which will be understood by the docker client binary.
String
credentialsId
String
file
variable
String
credentialsId
String
gitUsernamePassword
gitToolName
Specify the Git tool installation name
String
credentialsId
Shell example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) { sh 'git fetch --all' }
Batch example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) { bat 'git submodule update --init --recursive' }
Powershell example
withCredentials([gitUsernamePassword(credentialsId: 'my-credentials-id', gitToolName: 'git-tool')]) { powershell 'git push' }
String
$class: 'KeychainPasswordAndPathBinding'
keychainPathVariable
String
passwordVariable
String
inSearchPathVariable
String
credentialsId
String
kubeconfigContent
variable
String
credentialsId
String
kubeconfigFile
variable
String
credentialsId
String
OSFBuilderSuiteOpenCommerceAPICredentials
clientIdVariable
String
clientPasswordVariable
String
credentialsId
String
sshUserPrivateKey
keyFileVariable
String
credentialsId
String
passphraseVariable
(optional)
String
usernameVariable
(optional)
String
string
ps e
.
variable
String
credentialsId
String
OSFBuilderSuiteTwoFactorAuthCredentials
serverCertificateVariable
String
clientCertificateVariable
String
clientPrivateKeyVariable
String
credentialsId
String
usernameColonPassword
:
).
ps e
.
variable
String
credentialsId
String
usernamePassword
ps e
.
usernameVariable
String
passwordVariable
String
credentialsId
String
$class: 'VaultCertificateCredentialsBinding'
keyStoreVariable
String
passwordVariable
String
credentialsId
String
vaultFile
variable
String
credentialsId
String
$class: 'VaultSSHUserPrivateKeyBinding'
usernameVariable
String
privateKeyVariable
String
passphraseVariable
String
credentialsId
String
vaultString
variable
String
credentialsId
String
$class: 'VaultTokenCredentialBinding'
addrVariable
String
tokenVariable
String
credentialsId
String
vaultAddr
String
namespaceVariable
(optional)
String
vaultNamespace
(optional)
String
$class: 'VaultUsernamePasswordCredentialBinding'
usernameVariable
String
passwordVariable
String
credentialsId
String
zip
variable
String
credentialsId
String
azureServicePrincipal
credentialsId
String
clientIdVariable
(optional)
String
clientSecretVariable
(optional)
String
subscriptionIdVariable
(optional)
String
tenantIdVariable
(optional)
String
azureStorage
credentialsId
String
blobEndpointUrlVariable
(optional)
String
storageAccountKeyVariable
(optional)
String
storageAccountNameVariable
(optional)
String
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.