Chapter 21: Jenkins Pipeline and Jenkinsfile

21.6 Optional: bind a credential by id (pattern only)

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

Every real pipeline needs a secret. A token to push an image. A password for a database test. An SSH key for a server. Think of PhonePe. If one token leaks in a build log, an attacker can push a bad image to production. So the rule is strict. The secret lives only in Jenkins credentials, encrypted. The Jenkinsfile only knows the credential ID, a plain name like registry-login. At run time Jenkins puts the secret in an environment variable for a short time and hides it in the log with stars. In this lesson you will create three kinds of credentials, use them with withCredentials and with the credentials() helper, and prove that the log never shows the value. All values in this lesson are fake lab values.

What we will build

You will add a secret text, a username and password, and an SSH key in Jenkins. You will write three stages that use them safely. You will try to print a secret and see Jenkins mask it. You will learn the Groovy string trap that leaks secrets.

What: every term in plain English

• Credential — A secret stored by Jenkins, like a token, password or key.
• Credential ID — The plain name you use in the Jenkinsfile. Not secret.
• Secret text — One secret string, like an API token.
• Username with password — A pair, like a registry login.
• SSH Username with private key — A key to log in to servers.
• withCredentials — A step that puts a secret in a variable only inside its block.
• credentials() — A helper in environment that binds a credential to a variable.
• Masking — Jenkins replaces the secret with **** in the log.

How: step by step

1. Add a secret text

   Manage Jenkins > Credentials > System > Global > Add > Kind: Secret text > Secret: lab-fake-token-123 > ID: api-token
   

   What it does: Stores a fake lab token.

   Output

   api-token created
   

2. Add a username and password

   Add > Username with password > Username: ci-bot > Password: lab-fake-pass > ID: registry-login
   

   What it does: A fake registry login.

   Output

   registry-login created
   

3. Add an SSH key

   Add > SSH Username with private key > Username: deploy > Key: paste lab key > ID: lab-ssh
   

   What it does: A key for the lab server.

   Output

   lab-ssh created
   

4. Install the plugin

   Manage Jenkins > Plugins > Credentials Binding, SSH Agent
   

   What it does: Gives withCredentials and sshagent.

   Output

   Success
   

5. Use them

   Write the Jenkinsfile from the examples
   

   What it does: Each stage binds only what it needs.

   Output

   (file saved)
   

6. Check the log

   Console Output
   

   What it does: Secrets show as ****.

   Output

   curl -H Authorization: Bearer ****
   

Example 1: Secret text with withCredentials

Stack. Credentials Binding plugin

Goal. Secret text with withCredentials.

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Call API') {
      steps {
        withCredentials([string(credentialsId: 'api-token', variable: 'TOKEN')]) {
          sh 'curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $TOKEN" https://httpbin.org/bearer'
          sh 'echo "token is $TOKEN"'
        }
      }
    }
  }
}

What each line does

• withCredentials([...]) — Opens a block where the secret exists.
• string(credentialsId: 'api-token', variable: 'TOKEN') — Secret text into the TOKEN variable.
• sh '...$TOKEN...' — Single quotes: the shell reads TOKEN. Groovy never sees the value.
• echo token — Even a print is masked.

Green output

[Pipeline] withCredentials
Masking supported pattern matches of $TOKEN
+ curl -s -o /dev/null -w %{http_code} -H Authorization: Bearer **** https://httpbin.org/bearer
200
+ echo token is ****
token is ****
Finished: SUCCESS

Expected result. The value was used and never shown.

Example 2: Username and password with credentials() in environment

Stack. Jenkins, Docker

Goal. Username and password with credentials() in environment.

Jenkinsfile

pipeline {
  agent any
  environment {
    REG = credentials('registry-login')
  }
  stages {
    stage('Login') {
      steps {
        sh 'echo "user is $REG_USR"'
        sh 'echo "$REG_PSW" | docker login registry.example.com -u "$REG_USR" --password-stdin'
      }
    }
  }
  post { always { sh 'docker logout registry.example.com || true' } }
}

What each line does

• credentials('registry-login') — Binds the pair to REG.
• REG_USR and REG_PSW — Jenkins makes these two extra variables.
• --password-stdin — Password goes in through a pipe, not the command line.
• docker logout — Removes the saved login after the build.

Green output

+ echo user is ****
user is ****
+ echo ****
+ docker login registry.example.com -u **** --password-stdin
Login Succeeded
+ docker logout registry.example.com
Removing login credentials for registry.example.com

Expected result. Even the username is masked, because it is part of the credential.

Example 3: The Groovy string trap, and SSH key use

Stack. SSH Agent plugin

Goal. The Groovy string trap, and SSH key use.

Jenkinsfile (bad and good)

pipeline {
  agent any
  stages {
    stage('Bad') {
      steps {
        withCredentials([string(credentialsId: 'api-token', variable: 'TOKEN')]) {
          sh "curl -H 'Authorization: Bearer ${TOKEN}' https://httpbin.org/bearer"
        }
      }
    }
    stage('SSH') {
      steps {
        sshagent(credentials: ['lab-ssh']) {
          sh 'ssh -o StrictHostKeyChecking=accept-new deploy@10.0.1.20 "hostname && uptime"'
        }
      }
    }
  }
}

What each line does

• sh "...${TOKEN}..." — Double quotes: Groovy puts the secret into the command text. Jenkins warns.
• Fix — Use single quotes and $TOKEN so the shell reads it.
• sshagent(credentials: ['lab-ssh']) — Loads the key into an SSH agent only for this block.
• accept-new — Trusts a new host once, then checks it later.

Green output

Warning: A secret was passed to "sh" using Groovy String interpolation, which is insecure.
         Affected argument(s) used the following variable(s): [TOKEN]
[Pipeline] stage (SSH)
[ssh-agent] Using credentials deploy (lab-ssh)
+ ssh -o StrictHostKeyChecking=accept-new deploy@10.0.1.20 hostname && uptime
lab-web-01
 10:52:11 up 3 days,  2:10,  0 users,  load average: 0.04, 0.03, 0.00
Finished: SUCCESS

Expected result. Read the warning. Always use single quotes with secrets.

Example 4: Secret file credential for a kubeconfig

Stack. Credentials Binding, kubectl

Goal. Secret file credential for a kubeconfig.

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Cluster check') {
      steps {
        withCredentials([file(credentialsId: 'lab-kubeconfig', variable: 'KUBECONFIG')]) {
          sh 'kubectl get nodes -o wide'
          sh 'ls -l "$KUBECONFIG"'
        }
        sh 'echo "after block: ${KUBECONFIG:-gone}"'
      }
    }
  }
}

What each line does

• file(credentialsId: ...) — A Secret file credential. Jenkins writes it to a temp file.
• variable KUBECONFIG — kubectl reads this variable to find its config.
• ls -l — Shows the temp path, masked.
• after block — The temp file is deleted and the variable is gone.

Green output

+ kubectl get nodes -o wide
NAME        STATUS   ROLES           AGE   VERSION
lab-node1   Ready    control-plane   12d   v1.30.2
+ ls -l ****
-r-------- 1 jenkins jenkins 5521 Oct 25 10:58 ****
+ echo after block: gone
after block: gone
Finished: SUCCESS

Expected result. Files like kubeconfig or a service account JSON work the same way. They exist only inside the block.

Verify: did it work?

1. Search the log for secrets

   curl -s -u admin:API_TOKEN http://localhost:8080/job/badge-scm/lastBuild/consoleText | grep -c lab-fake
   

   What it does: Counts raw secret hits in the log. Must be 0.

   Output

   0
   

2. List credential IDs

   Manage Jenkins > Credentials
   

   What it does: Shows IDs, never values.

   Output

   api-token, registry-login, lab-ssh
   

When it is red 1

ERROR: Could not find credentials entry with ID 'api-tokn'

Cause. The ID is misspelled or in another folder scope.

Fix, step by step

1. Copy the ID from the Credentials page.
2. Check folder credentials.

When it is red 2

Warning: A secret was passed to "sh" using Groovy String interpolation

Cause. Double quotes with a secret.

Fix, step by step

1. Switch to single quotes.
2. Use $VAR not ${VAR} in Groovy.

When it is red 3

No such DSL method 'sshagent' found

Cause. SSH Agent plugin missing.

Fix, step by step

1. Install it.
2. Restart Jenkins.

When it is red 4

Permission denied (publickey)

Cause. Wrong key or the public key is not on the server.

Fix, step by step

1. Add the public key to authorized_keys.
2. Check the username.

Cleanup

1. Delete lab credentials

   Manage Jenkins > Credentials > api-token > Delete (repeat)
   

   What it does: Removes the fake lab secrets.

   Output

   Deleted
   

2. Rotate real tokens

   Make a new token at the provider, update the credential, revoke the old one
   

   What it does: Rotation limits damage if a token leaks.

   Output

   Token revoked
   

Practice tasks

Homework: try at home

Recap

• Secrets live in Jenkins credentials.
• The Jenkinsfile only has the ID.
• Use withCredentials or credentials().
• Always single quotes in sh.
• Rotate tokens and log out after use.

FAQ

Is masking enough?

No. A script can still leak a secret by encoding it. Limit who can edit Jenkinsfiles.

Folder or global credentials?

Folder credentials limit a secret to one team.

Can I use a vault?

Yes, with plugins for HashiCorp Vault or AWS Secrets Manager.

Why not environment variables on the agent?

They are not masked and anyone on the agent can read them.

What about cloud keys?

Prefer IAM roles on the agent instead of stored keys.

Interview questions

1. How do you use secrets in a Jenkinsfile?

   Store them as credentials and bind by ID with withCredentials or credentials(), using single quoted sh.

2. What is the Groovy interpolation risk?

   Double quoted strings put the secret value into the command text, which can leak in process lists.

3. How do you log in to a registry safely?

   Pipe the password with --password-stdin and log out in post always.

4. How do you SSH from Jenkins?

   sshagent with an SSH key credential and host key checking.

5. A token leaked in a log. What now?

   Revoke it, rotate it, delete the build log, find the cause.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards