Jenkins: controller, agents, jobs and plugins
Jenkins is a free, open-source automation server written in Java. The controller holds the configuration, schedules work and shows the results; agents are the machines that actually run the builds. Work is defined as jobs, most often Pipeline jobs, and almost every feature comes from a plugin.
The main parts
Older documentation calls the controller the *master* and agents *slaves*. The Jenkins project replaced those names. You will still see them in old scripts and blog posts.
Jobs
| Job type | When it is used |
|---|---|
| Freestyle project | Steps configured by clicking in the web interface. Fine for simple tasks, but hard to review and copy |
| Pipeline | Steps written as code in a Jenkinsfile and stored in Git. The normal choice today |
| Multibranch Pipeline | Finds every branch (and pull request) with a Jenkinsfile and builds each one automatically |
What starts a build
- A webhook: GitHub calls Jenkins the moment someone pushes. This is the usual set-up.
- Poll SCM: Jenkins checks the repository for changes on a schedule.
- A timer, written in cron-style syntax, for nightly builds.
- A person pressing Build Now, or another job finishing.
Reading a build
Each run gets a build number (#57, #58…) and a result. Success means every step passed. Failure means a step failed, usually a command that exited with a non-zero status. Unstable usually means the build worked but some tests failed. Aborted means it was stopped. The Console Output page shows every command and its output, and the answer to 'why did it fail?' is almost always near the bottom.
[Pipeline] sh + ./run-tests.sh FAILED: OvertimeCalcTest.roundsToTwoDecimals script returned exit code 1 [Pipeline] End of Pipeline Finished: FAILURE
Plugins and credentials
Jenkins does very little on its own. Git integration, Pipeline support, test reports and links to other tools all come from plugins, and there are well over a thousand of them. Passwords, tokens and ssh keys are kept in Jenkins' credentials store and given to a build by ID, so they never appear in the Jenkinsfile and are masked in the console output.
In Jenkins, what is the name for the machine that actually runs the build steps, as opposed to the controller?
Show a hint
The controller hands the work to it.
Show the solution
An agent (also called a node).
Examples are for learning. Run commands and jobs only on a system you are authorised to use, such as a training or test system, and never on production without approval.
Common mistakes
Builds there can slow down or endanger the server everyone depends on. Run them on agents.
Freestyle settings are hard to review and easy to lose. Keep pipelines as code in a Jenkinsfile in Git.
Use the credentials store and refer to the ID. Jenkins then hides the value in the logs.
What you will see at work
- When a build fails, open Console Output and scroll to the bottom before asking anyone. The failing command is usually right there.
- Agents are chosen by label, so 'it fails on the zos agent but not on linux' is a useful clue.
- Plugin updates can break builds. Teams test Jenkins upgrades like any other change.
Key terms
Check your understanding.
Take this lesson's quiz and save your progress. Free.