Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 44 ยท Jenkins

Agents, Docker Agents and Credentials

Choose Jenkins agents by label or Docker image, store secrets in the credentials store, use withCredentials safely, and trigger builds with webhooks, not polling.

A pipeline is only as useful as the machine it runs on and the secrets it can safely use. This lesson covers three practical questions every Jenkins user meets quickly. Where does a stage run (labelled agents and Docker agents)? How does it get a password or token without that password ending up in Git or in the log (the credentials store and withCredentials)? And how does a push to your repository turn into a build (webhooks versus polling, multibranch pipelines)?

You should already know what the controller and agents are from Jenkins: Controller, Agents and Jobs and the pipeline shape from The Declarative Jenkinsfile.

Jenkins itself cannot run here, so all Groovy is read-only. The runnable examples are stand-ins in JavaScript: one shows how secret masking in a log works and where it fails, the other compares polling with webhooks. They illustrate behaviour; they are not Jenkins code.

Choosing an agent

The agent directive selects where a pipeline or a single stage runs. Besides any and none, there are two forms that matter in practice.

By label. Each agent in Jenkins carries labels such as linux, windows or gpu. A pipeline asks for a label expression, and Jenkins waits until a matching agent has a free executor:

GROOVY
pipeline {
    agent { label 'linux && docker' }
    stages {
        stage('Build') {
            steps { sh 'make' }
        }
    }
}

Labels are how you reserve special hardware, operating systems or network zones. Avoid asking for a specific machine name; a label lets you add or replace machines without touching a single Jenkinsfile.

By Docker image. Instead of installing Node, Java or Python on every agent, run the stage inside a container started from an image you name:

GROOVY
pipeline {
    agent none
    stages {
        stage('Build') {
            agent {
                docker {
                    image 'node:22'
                    args '-v $HOME/.npm:/root/.npm'
                }
            }
            steps {
                sh 'node --version'
                sh 'npm ci && npm run build'
            }
        }
        stage('Test') {
            agent { docker { image 'python:3.13' } }
            steps {
                sh 'python --version'
            }
        }
    }
}

The agent that runs the Docker commands still needs Docker installed and a label such as docker. The workspace is mounted into the container, so files written by your steps remain after the container exits. Setting agent none at the top and an agent per stage lets each stage use a different toolchain, and no agent is held while the pipeline waits on an input step. If your build needs a custom environment, agent { dockerfile true } builds an image from the Dockerfile in the repository first. For how images and containers work, see the Docker tutorial, starting with Layers and the Union Filesystem.

The credentials store

Jenkins has a built-in credentials store (Manage Jenkins, then Credentials). You create an entry once, give it an ID such as deploy-token, and your Jenkinsfile refers to it only by that ID. The secret value never appears in Git. The common credential kinds are:

Kind Holds Typical use
Secret text One string API tokens
Username with password Two strings Registry or repository logins
Secret file A file Kubeconfig, service account JSON
SSH username with private key User and key Deploying over SSH, Git over SSH
Certificate A keystore Code signing, client certificates

Credentials can be scoped to the whole system or to a folder, so one team's secrets are not visible to another team's jobs.

withCredentials and environment

The withCredentials step makes a secret available as a variable for the duration of a block, and nowhere else:

GROOVY
steps {
    withCredentials([
        string(credentialsId: 'deploy-token', variable: 'TOKEN'),
        usernamePassword(credentialsId: 'registry-login',
                         usernameVariable: 'REG_USER',
                         passwordVariable: 'REG_PASS')
    ]) {
        sh 'echo "$REG_PASS" | docker login -u "$REG_USER" --password-stdin registry.example.com'
        sh 'curl -fsS -H "Authorization: Bearer $TOKEN" https://deploy.example.com/release'
    }
}

For declarative pipelines there is a shortcut: environment { TOKEN = credentials('deploy-token') } binds the secret for the stage or pipeline. For a username-and-password credential it also creates TOKEN_USR and TOKEN_PSW.

Look closely at the quotes in the example. The shell command is in single quotes, so Jenkins passes $TOKEN through and the shell expands it. With double quotes, Groovy would interpolate the secret into the command text before it is run, which can leak it into logs and process listings. Jenkins warns about this. The rule: never interpolate secrets with Groovy "${...}"; let the shell read the variable.

Masking, and its limits

Jenkins hides bound secret values in the console log by replacing them with ****. That is a convenience, not a vault. The masker searches the output for the exact secret text. Anything that changes the text slips past it: an encoded copy (base64), a reversed or split copy, or a value printed one character per line.

The stand-in below implements the same idea and then shows what it misses. Read the output carefully: the "masked" log is not safe if your script transforms the secret.

JS A log masker and what slips past it

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Lines one and two are masked. The base64, reversed and split versions pass straight through, which is why the rule is "do not print secrets at all", not "rely on masking". Also remember that masking happens in the console output only: a secret written into a file that you archive as an artifact, or printed by set -x before the masker sees it in some other form, is not protected.

Webhooks versus polling

Jenkins has to learn that something changed in Git. There are two ways.

Polling. The job asks the repository on a schedule, with triggers { pollSCM('H/5 * * * *') }. The H means "a hash-based minute", so jobs do not all poll at the same instant. Polling needs no network path from the Git host to Jenkins, but it is wasteful (most polls find nothing) and builds start up to a full interval late.

Webhooks. The Git host sends an HTTP request to Jenkins when a push happens, and Jenkins starts the build immediately. This needs Jenkins to be reachable from the Git host and normally a plugin for that host (GitHub, GitLab or Bitbucket integration). It is cheaper and faster, so it is the default choice; keep a slow poll only as a safety net.

sequenceDiagram
    participant Dev as Developer
    participant Git as Git host
    participant J as Jenkins
    Dev->>Git: push
    Git->>J: webhook (HTTP POST)
    J->>Git: fetch changes
    J->>J: run pipeline

With a webhook the build starts at once; with polling it waits for the next check.

Try it: polling delay

This model polls every five minutes. Commits arrive at the minutes listed, and one poll that sees several commits starts a single build. The webhook column starts a build per push, instantly.

JS Polling versus webhooks

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Polling makes 12 checks to find 3 builds and makes the commits at minutes 12 and 14 share a build; webhooks start four builds with no waiting. Neither is wrong: batching can be a feature on a busy repository.

Multibranch pipelines

A multibranch pipeline job scans a repository and creates a sub-job for every branch (and pull request) that contains a Jenkinsfile. New branches get a pipeline automatically, and deleted branches are cleaned up. The Jenkinsfile can use when { branch 'main' } so that only the main branch deploys. Each branch has its own history, and the scan itself can be triggered by a webhook or run periodically. This is the usual setup for teams who use feature branches, and the next projects in this track return to it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is agent { label 'linux && docker' } better than naming one specific machine?

    A label describes capability. Any matching agent can serve the build, so the fleet can change freely.
  2. 2. Which shell command line avoids leaking the secret through Groovy string interpolation?

    With single quotes Groovy does not interpolate. The shell reads the environment variable, so the secret is not placed in the command text by Jenkins.
  3. 3. A script prints the base64 encoding of a bound secret. What does Jenkins' console masking do?

    Masking replaces occurrences of the exact value. A transformed copy is a different string and is not recognised.
  4. 4. What is the main advantage of a webhook over pollSCM?

    The Git host notifies Jenkins when something happens, so there is no wait for the next poll and no wasted checks.

Summary

  • Pick agents by label for capability, or by Docker image to bring your own toolchain; agent none plus per-stage agents avoids holding machines while waiting.
  • Store secrets in the credentials store and refer to them by ID; use withCredentials or credentials('id') to bind them for as short a time as possible.
  • Use single-quoted sh strings so the shell, not Groovy, expands secrets.
  • Masking replaces only the exact secret text in the console; never print or transform secrets.
  • Prefer webhooks to polling; a multibranch pipeline creates a pipeline for every branch that has a Jenkinsfile.

Next: GitLab CI/CD Basics.