DevOps, CI/CD & Containers

Jenkins Setup and Jobs: Controller, Agents, Credentials and Triggers

Beginner11 min readUpdated

Jenkins is still the automation server behind a large share of enterprise build pipelines, and most of the pain people associate with it comes from an installation that was never configured properly. This guide sets up a controller you can defend, explains agents, labels and executors, shows how credentials and plugins are managed, and compares freestyle jobs with pipelines and polling with webhooks.

What you will learn

  • Install a Jenkins LTS controller with Docker or a package and complete the security setup
  • Describe the controller and agent architecture and connect an agent over SSH or inbound
  • Store and reference credentials without ever putting a secret in a job configuration
  • Create a working build job and explain why pipelines have replaced freestyle jobs
  • Choose between webhooks, SCM polling and scheduled triggers, and back up JENKINS_HOME

Jenkins has been running builds since 2011 and shows no sign of disappearing, largely because it will automate anything: it has no opinion about your language, your operating system or your deployment target, and its plugin ecosystem covers roughly every tool a build has ever needed. That flexibility is also its weakness. A default installation is an unauthenticated automation server that executes arbitrary shell commands, and a Jenkins instance that grew organically for five years is usually a collection of hand-clicked jobs nobody dares touch.

This guide sets up the opposite of that: a controller with sane security, work running on agents rather than on the server itself, credentials in the credential store, and configuration you can reconstruct. It assumes you already know why you want continuous integration; the aim here is a working, defensible installation and the vocabulary to operate it.

The pieces and how they fit

A Jenkins installation has three parts.

The controller is the web application. It serves the UI and REST API, stores configuration and build history, schedules builds and hosts the plugins. It should not build anything itself.

An agent (older documentation says "slave", and some plugin fields still do) is a machine or container that runs builds. Each agent advertises a number of executors — concurrent build slots — and a set of labels such as linux, jdk21 or docker. Jobs request a label, and Jenkins schedules them onto a matching agent with a free executor.

A job — Jenkins now calls them items — is a unit of automation: a pipeline, a freestyle project, a multibranch pipeline, a folder that groups them. Everything a job produces during a run lives in a workspace, a directory on the agent that is reused across builds of the same job on the same agent.

The controller and agents talk over a TCP connection that carries a remoting protocol. Two directions are possible: the controller connects out to the agent over SSH, or the agent connects in to the controller on a dedicated port. Which one you use is a firewall question, not a capability question.

Installing the controller

Jenkins ships as a weekly release and an LTS line; the LTS releases receive backported fixes for twelve weeks and are what you should run in production. The 2.5x LTS line requires Java 17 or 21 — Java 11 support ended years ago and the newest releases will refuse to start on it.

The container image is the quickest route and keeps the host clean:

docker volume create jenkins_home

docker run -d --name jenkins \
  -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  --restart unless-stopped \
  jenkins/jenkins:lts-jdk21

Port 8080 is the web UI; 50000 is the inbound agent port, which you only need to publish if agents connect to the controller. The named volume is JENKINS_HOME, and it is the only state that matters — if you can restore that volume, you can restore Jenkins.

On a Linux host, the packaged installation puts JENKINS_HOME at /var/lib/jenkins and runs under systemd as the jenkins user:

sudo apt-get install -y openjdk-21-jre fontconfig
# add the Jenkins apt repository and key as documented, then:
sudo apt-get install -y jenkins
sudo systemctl enable --now jenkins
systemctl status jenkins

Either way, the first page asks for an unlock key printed in the log and stored in secrets/initialAdminPassword:

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
# or, for a package install
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Accept the suggested plugins, create the first administrator account with a real password, and set the Jenkins URL correctly — plugins build links from it, and a wrong value produces webhooks and emails that point nowhere.

Locking it down

A fresh Jenkins is not safe to expose. Work through this list before anyone else gets an account.

  1. Put TLS in front of it

    Run Jenkins behind nginx or another reverse proxy that terminates HTTPS. Jenkins can serve TLS itself, but a proxy gives you certificate renewal, HTTP/2 and a place to add rate limiting. Set the proxy to forward the original host and scheme headers, or Jenkins will warn that its reverse proxy setup is broken.
  2. Choose a security realm

    The built-in user database is fine for a handful of people. For anything larger, connect LDAP, Active Directory or a SAML/OIDC provider through a plugin so that leaving the company removes access. Never enable signup on an instance reachable from outside.
  3. Switch to matrix authorisation

    The default "logged-in users can do anything" is convenient and wrong. Matrix-based security, or role-based strategy with the Role Strategy plugin, lets you grant read to everyone, build to developers and administer to two people. Grant permissions to groups, not individuals.
  4. Set controller executors to zero

    Manage Jenkins → Nodes → Built-In Node → set the number of executors to 0. Builds then have nowhere to run except agents, which is exactly the point.
  5. Keep CSRF protection and script security on

    Both are enabled by default and both are occasionally disabled by someone debugging an integration. Neither should stay off. Groovy that pipelines run outside the sandbox must be approved explicitly under In-process Script Approval.
  6. Patch on a schedule

    Jenkins and its plugins publish security advisories regularly. Subscribe to the advisory feed, apply plugin updates monthly and LTS upgrades at least quarterly. An unpatched Jenkins with network access to production is a serious liability.

Adding agents

The simplest durable agent is a Linux host reached over SSH. Prepare it with a JRE and whatever build tools you need, create a jenkins user with a home directory, and add the controller's public key to its authorized_keys. Then in Manage Jenkins → Nodes → New Node, choose a permanent agent and fill in:

  • Remote root directory — a working directory such as /home/jenkins/agent, with plenty of disk. Workspaces live here.
  • Labels — descriptive and specific: linux jdk21 maven docker. Jobs select agents by label expression, so linux && docker works.
  • Usage — "use this node as much as possible", or "only build jobs with label expressions matching this node" for specialised hardware.
  • Launch method — Launch agents via SSH, pointing at the host with the SSH credential you stored in Jenkins.

For agents behind a firewall that cannot accept inbound connections, use the inbound method instead. The controller gives you a command line to run on the agent:

java -jar agent.jar \
  -url https://jenkins.example.com/ \
  -secret @/etc/jenkins/agent-secret \
  -name build-node-2 \
  -workDir /home/jenkins/agent

Run that under systemd so it reconnects after a reboot. A third option, and the one that scales best, is ephemeral agents: the Docker or Kubernetes plugin starts a fresh container per build and destroys it afterwards, so no state leaks between builds and there is no agent to patch. It costs a little startup time per build and is worth it as soon as you have more than a handful of jobs.

Credentials

Never put a password in a job configuration, a build script or an environment variable typed into the UI. Jenkins has a credential store, encrypted with a key in JENKINS_HOME/secrets, and every plugin that needs a secret reads from it.

Credentials have a kind — username with password, SSH private key, secret text (for API tokens), secret file, certificate — and a scope. Global scope makes a credential visible to all jobs; system scope restricts it to Jenkins itself, such as an agent connection key. Store credentials in a folder rather than globally whenever a team owns a group of jobs: a folder-scoped credential is invisible to jobs outside it, which is the cheapest form of isolation Jenkins offers.

Each credential has an ID. Give it a stable, meaningful one — nexus-deploy, github-app-ci — because that ID is what job configuration references:

withCredentials([usernamePassword(credentialsId: 'nexus-deploy',
                                  usernameVariable: 'NEXUS_USER',
                                  passwordVariable: 'NEXUS_PASS')]) {
    sh 'mvn -s settings.xml deploy'
}

Jenkins masks the values in the console log, but masking is a safety net rather than a guarantee: a script that base64-encodes a secret and prints it will leak it. Prefer credentials with the narrowest possible rights and rotate them on a schedule.

Freestyle jobs and why pipelines replaced them

A freestyle project is configured entirely through web forms: source code management, build triggers, build steps, post-build actions. Creating one is instructive because it shows the anatomy of a build.

Create a new Freestyle project, then:

  • Source Code Management — Git, with the repository URL and a credential; specify the branch.
  • Build Steps — "Invoke top-level Maven targets" with goals clean verify, or "Execute shell" with the commands you would run locally.
  • Post-build Actions — publish JUnit results from **/target/surefire-reports/*.xml, archive target/*.jar, send an email on failure.

That job works and takes five minutes. Its limits appear quickly. The configuration lives only in the controller's XML, so it is not versioned with the code and cannot be reviewed. It cannot express a sequence of stages with parallelism and conditional promotion. It does not survive a controller rebuild unless you restored the whole JENKINS_HOME. And branches need duplicated jobs.

A pipeline job solves all four by moving the definition into a Jenkinsfile committed alongside the source. The build is then reviewed like code, branches carry their own pipeline, and a controller can be rebuilt from nothing by pointing new jobs at the repositories. Use freestyle jobs for small maintenance chores; use pipelines for anything that builds a product. The Jenkinsfile guide covers the syntax in depth.

Triggering builds

Four triggers cover practically everything.

Webhooks are the right default. The Git host calls https://jenkins.example.com/github-webhook/ (or the generic webhook endpoint) on every push, and the build starts within a second with no wasted polling. This requires the controller to be reachable from the Git host, which in a private network usually means an allowlisted ingress path.

SCM polling asks the repository whether anything changed, on a schedule such as H/5 * * * *. It is the fallback when webhooks are impossible. The H is a Jenkins extension meaning "hash this job's name into the interval", which spreads polls out instead of having every job hit the server on the minute.

Scheduled builds (H 2 * * *) run regardless of changes, which is what you want for nightly integration suites, dependency-vulnerability scans or long performance runs.

Upstream triggers start a job when another finishes, forming a chain. Inside a single pipeline, stages replace this; across repositories — a library that triggers its consumers — it remains useful.

Plugins, upgrades and configuration as code

Plugins are how Jenkins does anything, and they are also its main operational risk: each one is code running with full privileges, and a plugin abandoned by its author becomes a blocker at the next Java upgrade. Keep the list short — install what a job needs, uninstall what nothing references, and check for updates on a schedule rather than when something breaks.

The plugins nearly every installation uses: Pipeline (the workflow-aggregator suite), Git, Credentials Binding, Matrix Authorization, JUnit, Warnings Next Generation, Docker Pipeline, and Configuration as Code.

That last one deserves attention. JCasC lets the controller's own configuration live in a YAML file, so the instance can be recreated instead of restored:

jenkins:
  systemMessage: "Managed by configuration as code — do not edit through the UI"
  numExecutors: 0
  mode: EXCLUSIVE
  securityRealm:
    local:
      allowsSignup: false
  authorizationStrategy:
    globalMatrix:
      entries:
        - group:
            name: "authenticated"
            permissions: ["Overall/Read", "Job/Read"]
        - group:
            name: "developers"
            permissions: ["Job/Build", "Job/Cancel"]
unclassified:
  location:
    url: "https://jenkins.example.com/"
    adminAddress: "[email protected]"

Point the CASC_JENKINS_CONFIG environment variable at the file, keep it in Git, and controller configuration becomes reviewable. Combine it with a plugin list pinned by version and a rebuild becomes a fifteen-minute job.

Backups and disk

Everything Jenkins knows is under JENKINS_HOME. A backup that covers *.xml at the top level, jobs/*/config.xml, users/, nodes/ and — critically — secrets/ is enough to rebuild the instance. Build history and workspaces are large and mostly disposable; excluding jobs/*/builds and workspace keeps the backup small enough to run nightly.

#!/usr/bin/env bash
set -euo pipefail
JENKINS_HOME=${JENKINS_HOME:-/var/lib/jenkins}
STAMP=$(date +%F)
tar -czf "/backup/jenkins-${STAMP}.tar.gz" \
    -C "$JENKINS_HOME" \
    --exclude='jobs/*/builds' \
    --exclude='workspace' \
    --exclude='caches' \
    . 

Encrypt the archive: it contains the secrets directory, and with it every credential Jenkins holds. Then test a restore at least once — a backup nobody has restored is a hypothesis.

Disk is the other recurring problem. Set a build-retention policy on every job and clean workspaces on agents that host many jobs; a controller that runs out of disk corrupts job configuration on write.

Common mistakes

  • Running builds on the controller. It gives every build read access to all credentials and takes the server down when a test consumes all memory.
  • Configuring everything by clicking. After a year nobody can say why a job works. Move build logic into a Jenkinsfile and controller settings into JCasC.
  • Secrets pasted into build steps. They end up in job XML, in backups and in console logs. Use the credential store and withCredentials.
  • Never upgrading. Plugin and core advisories accumulate, and jumping four LTS versions at once is far harder than doing one each quarter.
  • Unbounded build history. Default retention keeps everything forever, and console logs plus archived artifacts will fill the disk.
  • One giant shared agent. Jobs fight over ports, caches and disk. Ephemeral container agents remove a whole class of "it only fails on node 3" mysteries.
  • No ownership. A Jenkins that everyone uses and nobody maintains decays predictably. Name an owner and give them time for it.

Key takeaways

  • Run the LTS line on Java 17 or 21, keep the controller for scheduling and the UI only, and set its executor count to zero.
  • Secure the instance before opening it up: TLS via a proxy, a real security realm, matrix authorisation, CSRF and script security left on, and a patching schedule.
  • Agents connect outbound over SSH or inbound over the agent port; ephemeral Docker or Kubernetes agents give clean builds without machines to maintain.
  • Put every secret in the credential store, scope it to a folder where possible, and reference it by a stable ID.
  • Freestyle jobs are a useful five-minute demonstration; pipelines defined in a versioned Jenkinsfile are what production automation should use.
  • Trigger with webhooks where possible, fall back to hashed polling, and use scheduled builds for nightly work.
  • JENKINS_HOME is the whole system: back it up including secrets/, encrypt the archive, cap build retention, and keep the configuration reproducible with JCasC.

Sources and further reading

Frequently asked questions

Should builds ever run on the Jenkins controller?
No. A build running on the controller has access to JENKINS_HOME, which contains every credential, every job definition and the encryption keys that protect them. Set the controller's number of executors to zero and run all work on agents. This is the single most valuable hardening step on a default installation, and it also stops a runaway build from taking the whole server down.
Is Jenkins still worth choosing over hosted CI services?
It depends on constraints rather than fashion. Hosted services are simpler when your code is already on their platform and your builds need nothing unusual. Jenkins earns its keep when builds must run inside a private network, need specialised hardware or licensed toolchains, or must integrate with systems that have no cloud connector. The trade is that you own the upgrades, backups and security.
How many executors should an agent have?
Start with one executor per CPU core and reduce it if builds are memory-hungry or fight over disk. An executor is one concurrent build slot, so an agent with four executors runs four builds at once on the same filesystem. Test suites that bind fixed ports or use a shared database will collide, which is usually why teams end up at one or two executors per agent.
What exactly needs backing up?
JENKINS_HOME holds everything: job configurations, plugin jars and their settings, the credential store, user records and build history. The critical parts are the top-level XML files, the jobs directory excluding builds and workspaces, the users directory and the secrets directory. Without secrets, the encrypted credentials in the backup cannot be decrypted, so it must be included and protected accordingly.