Jenkins Job Builder (JJB) is a tool that defines Jenkins jobs as YAML or JSON and pushes them into a Jenkins server through its API. Instead of clicking through Jenkins' web UI to configure each job - and losing that configuration to drift and accidental edits - you write the job definition in version-controlled YAML, run jenkins-jobs update, and JJB renders the XML Jenkins expects and uploads it. It came out of the OpenStack project, which managed thousands of CI jobs and needed them reviewable, templated, and reproducible rather than hand-clicked.
Jobs as YAML
A JJB definition describes a job's SCM, triggers, build steps, and publishers as structured data. JJB expands it into the config.xml Jenkins stores per job.
- job:
name: etl-nightly
project-type: freestyle
scm:
- git:
url: git@github.com:org/etl.git
branches:
- main
triggers:
- timed: "H 2 * * *" # ~02:00 nightly, hashed to spread load
builders:
- shell: "make run"
publishers:
- email:
recipients: data-team@example.comThat YAML lives in your repo, gets code-reviewed like any change, and jenkins-jobs update ./jobs/ syncs it to the server - creating, updating, or (with --delete-old) removing jobs to match the files.
Templates and the job-per-project problem
JJB's real leverage is templating. A job-template defines a parameterized shape, and a project stamps out many concrete jobs from it, so fifty repositories that each need an identical build-test-publish job come from one template plus a list of names. This is how OpenStack kept thousands of jobs consistent.
| Construct | Role |
|---|---|
| job | A single concrete Jenkins job definition |
| job-template | Parameterized job stamped out per project |
| project | Binds a template to concrete parameter values |
| defaults / macros | Reusable blocks shared across jobs |
Where it fits versus pipelines-as-code
JJB predates Jenkins Pipeline and the Jenkinsfile. Modern Jenkins encourages defining a pipeline in a Jenkinsfile committed to the repo it builds, which covers many cases JJB once owned. JJB still earns its place where you manage a large fleet of jobs centrally - especially freestyle jobs or pipeline jobs whose wrapper config you want templated and reviewed apart from each repo. For broader CI/CD context, see Jenkins. JJB handles job configuration; it is not itself a data orchestrator.
Frequently asked questions
Is JJB part of Jenkins? No. It's a separate command-line tool (originally from OpenStack) that talks to Jenkins over its API. You install it independently and point it at your Jenkins server.
JJB or a Jenkinsfile? Use a Jenkinsfile when each repo owns its pipeline. Use JJB when you manage many jobs centrally and want them templated and reviewed in one place. The two can coexist.
How does it avoid configuration drift? The YAML is the source of truth; jenkins-jobs update overwrites server config to match, and --delete-old removes jobs no longer in the files, so manual UI edits don't survive the next sync.
Does it support pipeline jobs? Yes - JJB can define pipeline (workflow) jobs and inject or reference pipeline scripts, though many teams keep the pipeline body in a Jenkinsfile and use JJB only for the job wrapper.