WithCredentials block usage in Jenkins - Commands & Configuration

Introduction

Sometimes your Jenkins pipeline needs to use secret information like passwords or API keys safely. The WithCredentials block helps you use these secrets in your pipeline without exposing them openly.

When your pipeline needs to access a private Git repository using a username and password.

When you want to deploy to a cloud service that requires an API key stored securely in Jenkins.

When running tests that require database credentials without hardcoding them in your code.

When you want to keep secret tokens safe while using them temporarily in a build step.

When you need to pass SSH keys securely to a shell command during deployment.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Use Credentials') {
      steps {
        withCredentials([usernamePassword(credentialsId: 'my-credentials', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
          sh 'echo Using username: $USER'
          sh 'echo Using password: $PASS'
        }
      }
    }
  }
}

This Jenkinsfile defines a pipeline with one stage that uses the withCredentials block.

The credentialsId refers to the stored secret in Jenkins.

usernameVariable and passwordVariable define environment variables to access the secret values inside the block.

Commands inside the block can safely use these variables without exposing secrets outside.

Commands

This command adds a username and password credential to Jenkins from an XML file named credentials.xml. It stores the secret securely with the ID 'my-credentials'.

Terminal

jenkins-cli create-credentials-by-xml system::system::jenkins _ < credentials.xml

Expected Output

Credentials 'my-credentials' created successfully

→

system::system::jenkins - Specifies the Jenkins system scope for the credential

Shows the Jenkinsfile content that uses the withCredentials block to access the stored secret.

Terminal

cat Jenkinsfile

Expected Output

pipeline {

  agent any

  stages {

    stage('Use Credentials') {

      steps {

        withCredentials([usernamePassword(credentialsId: 'my-credentials', usernameVariable: 'USER', passwordVariable: 'PASS')]) {

          sh 'echo Using username: $USER'

          sh 'echo Using password: $PASS'

        }

      }

    }

  }

}

Starts a Jenkins build of the pipeline named 'my-pipeline' which uses the withCredentials block to access secrets safely during the build.

Terminal

jenkins-cli build my-pipeline

Expected Output

Started build #1 for job my-pipeline

Building remotely on agent in workspace /var/jenkins_home/workspace/my-pipeline

[Pipeline] withCredentials

[Pipeline] {

[Pipeline] sh

+ echo Using username: admin

Using username: admin

[Pipeline] sh

+ echo Using password: secret123

Using password: secret123

[Pipeline] }

[Pipeline] // withCredentials

[Pipeline] End of Pipeline

Finished: SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: withCredentials lets you safely use secrets inside a controlled block without exposing them outside.

Common Mistakes

Using secret variables outside the withCredentials block

Secrets are only available inside the block; outside they are empty or undefined, causing errors or exposing no secret.

Always use secret variables only inside the withCredentials block where they are injected.

Hardcoding secrets directly in the Jenkinsfile

This exposes sensitive information in the pipeline code and logs, risking security leaks.

Store secrets in Jenkins credentials store and access them via withCredentials.

Using wrong credentialsId that does not exist in Jenkins

The pipeline will fail because it cannot find the secret to inject.

Verify the credentialsId matches the ID of the stored secret in Jenkins.

Summary

Use withCredentials block in Jenkinsfile to access secrets safely during pipeline execution.

Store secrets in Jenkins credentials store and refer to them by credentialsId in the block.

Secrets are only available inside the withCredentials block and should not be hardcoded.

Practice

1. What is the main purpose of the withCredentials block in a Jenkins pipeline?

easy

A. To display credentials in the console output for debugging

B. To permanently store credentials in the pipeline script

C. To securely inject credentials only inside the block without exposing them elsewhere

D. To create new credentials in Jenkins

Solution

1. Step 1: Understand the purpose of withCredentials

   The block is designed to provide credentials securely only within its scope.

2. Step 2: Analyze other options

   Options A, B, and D describe incorrect or unsafe behaviors not related to withCredentials.

3. Final Answer:

   To securely inject credentials only inside the block without exposing them elsewhere -> Option C

4. Quick Check:

   Secure injection inside block = C [OK]

Hint: Remember: credentials only live inside the block [OK]

Common Mistakes:

• Thinking credentials persist outside the block
• Assuming credentials are printed in logs
• Confusing with credential creation

2. Which of the following is the correct syntax to use a username and password credential with withCredentials in a Jenkins pipeline?

easy

A. withCredentials([usernamePassword(credentialsId: 'cred-id', usernameVariable: 'USER', passwordVariable: 'PASS')]) { ... }

B. withCredentials(usernamePassword('cred-id', 'USER', 'PASS')) { ... }

C. withCredentials { usernamePassword('cred-id', 'USER', 'PASS') ... }

D. withCredentials([usernamePassword('cred-id', 'USER', 'PASS')]) { ... }

Solution

1. Step 1: Recall correct withCredentials syntax

   The correct syntax uses a list with usernamePassword specifying named parameters.

2. Step 2: Check each option

   Only withCredentials([usernamePassword(credentialsId: 'cred-id', usernameVariable: 'USER', passwordVariable: 'PASS')]) { ... } uses named parameters and list syntax correctly; others miss brackets or parameter names.

3. Final Answer:

   withCredentials([usernamePassword(credentialsId: 'cred-id', usernameVariable: 'USER', passwordVariable: 'PASS')]) { ... } -> Option A

4. Quick Check:

   Named params + list = A [OK]

Hint: Use named parameters inside a list for credentials [OK]

Common Mistakes:

• Omitting square brackets around credentials
• Not using named parameters
• Wrong block structure

3. Given this Jenkins pipeline snippet:

withCredentials([string(credentialsId: 'token-id', variable: 'TOKEN')]) {
  sh 'echo $TOKEN'
}

What will happen when this pipeline runs?

medium

A. The token will be printed as plain text in the Jenkins UI

B. The secret token value will be printed in the console output

C. The pipeline will fail because $TOKEN is not accessible

D. The shell command will print the token value but it will be masked in logs

Solution

1. Step 1: Understand withCredentials behavior

   The secret is injected as an environment variable inside the block and Jenkins masks it in logs.

2. Step 2: Analyze the shell command output

   The echo $TOKEN prints the token, but Jenkins hides it in console output to protect secrets.

3. Final Answer:

   The shell command will print the token value but it will be masked in logs -> Option D

4. Quick Check:

   Secrets masked in logs = A [OK]

Hint: Secrets print masked, not visible in logs [OK]

Common Mistakes:

• Assuming secrets print as plain text
• Thinking environment variables are unavailable
• Confusing console output with UI display

4. Identify the error in this Jenkins pipeline snippet:

withCredentials([usernamePassword(credentialsId: 'cred-id', usernameVariable: 'USER')]) {
  sh 'echo $USER $PASS'
}

medium

A. Missing passwordVariable parameter causes $PASS to be undefined

B. Credentials ID is incorrect format

C. The sh step cannot access environment variables

D. The withCredentials block must not use a list

Solution

1. Step 1: Check withCredentials parameters

   The snippet provides only usernameVariable but misses passwordVariable.

2. Step 2: Understand impact on shell command

   Since passwordVariable is missing, $PASS is undefined and will cause an empty or error output.

3. Final Answer:

   Missing passwordVariable parameter causes $PASS to be undefined -> Option A

4. Quick Check:

   Both username and password variables needed = D [OK]

Hint: Always specify both usernameVariable and passwordVariable [OK]

Common Mistakes:

• Forgetting passwordVariable
• Assuming shell can't access env vars
• Wrong credentialsId format

5. You want to use multiple credentials (a username/password and a secret text) inside a Jenkins pipeline securely. Which is the correct way to use withCredentials to access both?

hard

A. withCredentials(usernamePassword(credentialsId: 'cred1', usernameVariable: 'USER', passwordVariable: 'PASS')) {
withCredentials(string(credentialsId: 'cred2', variable: 'TOKEN')) { ... }
}

B. withCredentials([usernamePassword(credentialsId: 'cred1', usernameVariable: 'USER', passwordVariable: 'PASS'), string(credentialsId: 'cred2', variable: 'TOKEN')]) { ... }

C. withCredentials([usernamePassword('cred1', 'USER', 'PASS'), string('cred2', 'TOKEN')]) { ... }

D. withCredentials([usernamePassword(credentialsId: 'cred1', usernameVariable: 'USER', passwordVariable: 'PASS')]) { withCredentials([string(credentialsId: 'cred2', variable: 'TOKEN')]) { ... } }

Solution

1. Step 1: Understand multiple credentials usage

   You can pass multiple credentials as a list inside a single withCredentials block.

2. Step 2: Compare options

   withCredentials([usernamePassword(credentialsId: 'cred1', usernameVariable: 'USER', passwordVariable: 'PASS'), string(credentialsId: 'cred2', variable: 'TOKEN')]) { ... } correctly uses a list with both credential types together. Options A and D nest blocks unnecessarily. withCredentials([usernamePassword('cred1', 'USER', 'PASS'), string('cred2', 'TOKEN')]) { ... } uses wrong syntax.

3. Final Answer:

   withCredentials([usernamePassword(credentialsId: 'cred1', usernameVariable: 'USER', passwordVariable: 'PASS'), string(credentialsId: 'cred2', variable: 'TOKEN')]) { ... } -> Option B

4. Quick Check:

   Multiple creds in one list = B [OK]

Hint: Use one list with all credentials inside withCredentials [OK]

Common Mistakes:

• Nesting multiple withCredentials blocks unnecessarily
• Using incorrect parameter syntax
• Passing credentials without a list