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.