A build is one single run of a job. It has a number, a start time, an end time, a result and a record of everything that happened.

Jenkins is an automation server, a program that stays switched on and does tasks for you when something triggers it. The description of what to do is saved as a job. A job says where the code lives, which steps to perform, and when to start. But a job is only a description. Nothing happens until Jenkins actually runs it, and each time it runs, that run is called a build.

So the relationship is simple. One job can have hundreds or thousands of builds over its life. The job is the recipe. The build is one cooking session. When you look at the history of a job in Jenkins, the list on the left side of the page is a list of builds, each with its own number such as #1, #2, #3, and so on.

Many people also use the word “build” to mean “compiling code,” because that is what the word means in traditional programming. In Jenkins the meaning is wider. A Jenkins build may compile code, but it may also run tests, scan for security problems, create a package, deploy to a server, or do something that has nothing to do with software, such as taking a backup. Whatever the steps are, the whole run is one build.

What is stored with every build

Jenkins has several words that sound alike. Once you see how they nest inside each other, they stop being confusing.

The words job, project, pipeline, build, stage and step are used loosely in blogs and chats, and that causes real confusion. Here is a clean way to hold them in your head. Start with the biggest thing and move to the smallest.

Types of jobs that create builds

How Jenkins builds relate to build tools

Programming languages come with their own build tools, programs that know how to turn source code into something runnable. Java teams often use Maven or Gradle, JavaScript teams use npm, and many C and C++ projects use Make. These tools understand the details of one language. Jenkins does not try to replace them. Instead, it calls them as steps, and it adds everything around them that a single tool cannot provide: a trigger to start the work, a machine to run it on, a place to store the log, a decision about the final result, and a memory of every past run. You can picture the build tool as a skilled carpenter and the Jenkins build as the whole workshop, with its schedule, its tool cabinet, its notice board and its record book.

This split is also why Jenkins works with so many languages. Because the language-specific work is delegated to the right tool, the same Jenkins build can compile Java on one job, package a mobile app on another, and check thousands of settings files on a third. The outer shape of the build stays the same, and only the steps inside change.

Before following a build on its journey, meet the supporting characters. Each one plays a small, clear role.

Triggers: how builds begin

A build never starts by magic. Something must trigger it, and Jenkins records the reason. The common triggers are these.

• Webhook: your code host sends a message the moment code changes. This is the fastest and most efficient way.
• Polling: Jenkins asks your code host every few minutes, “Anything new?” It works but wastes effort and adds delay.
• Schedule: a timer starts the build, for example every night at midnight.
• Manual: a person clicks a button, possibly choosing parameters first.
• Upstream job: another job finishes and starts this one, forming a chain.
• Remote call: a script or another tool calls Jenkins through its web interface.

A build touches several parts of the system. Seeing them together makes the rest of the guide easy to follow.

flowchart LR
    Dev["Developer"] -->|"push code"| SCM["Git Repository"]
    SCM -->|"webhook"| Ctrl["Jenkins Controller"]
    Ctrl --> Queue["Build Queue"]
    Queue -->|"free executor"| Agent["Agent with Executors"]
    Agent --> WS["Workspace Folder"]
    Agent -->|"console log and results"| Ctrl
    Ctrl --> Home["Build Records in JENKINS_HOME"]
    Agent --> Art["Artifact Repository"]
    Ctrl -->|"result message"| Chat["Email and Chat"]

Reading the diagram

Follow the arrows. A developer pushes code to a Git repository, the shared place where the team keeps its source code. The repository sends a webhook to the Jenkins controller. The controller creates a build request and puts it in the build queue. When an agent has a free executor, the build moves there. The agent prepares a workspace folder, does the work, and streams its console log and results back to the controller. The controller stores the build record inside a folder called JENKINS_HOME. Any files worth keeping go to an artifact repository, which is a warehouse for finished packages. At the end, the controller sends a message to email or chat.

Where the build record is stored

Jenkins does not use a traditional database for its build history. Inside the home folder, each job has a directory, and inside it each build has its own folder holding files such as a summary of the result, the log, and the changes list. This makes backups simple, because copying a folder copies everything. It also means that thousands of old builds can slowly fill the disk and slow down the pages that list them, which is why cleaning up old builds matters. We cover that in a later chapter.

Every build follows the same road from the moment it is asked for to the moment it is finished and remembered.

flowchart TD
    T["Trigger: webhook, timer or click"] --> Q["Build enters the queue"]
    Q --> QP["Quiet period and scheduling"]
    QP --> A["Agent and executor assigned"]
    A --> W["Workspace prepared"]
    W --> C["Source code checked out"]
    C --> S["Stages and steps run"]
    S --> R["Result decided"]
    R --> P["Post actions: reports, notifications, cleanup"]
    P --> H["Record kept in build history"]

The two clocks of a build

Every build has two time measurements that beginners often mix up. Queue time is how long the build waited before any machine started it. Run time is how long it actually ran. If your builds feel slow, look at both. A long queue time tells you that you need more agents or executors. A long run time tells you that the pipeline itself needs tuning, such as running tests in parallel or reusing downloaded files.

A build does not end with only “good” or “bad.” Jenkins uses a small set of results, and each one means something specific.

Failure versus unstable

This difference is the one that catches most beginners. A failure means the build hit a hard stop: a command returned an error, the code did not compile, or a required file was missing. An unstable build means everything ran to the end, but a quality check inside it reported a problem. Test results are the classic case. The tests ran, and some of them said “wrong.” Jenkins does not treat this as a crash, so it uses a softer color to say, “The machinery worked, but the product has issues.”

Health and trends

Jenkins also gives each job a health score shown as a weather icon. It looks at the last few builds. Mostly successful builds show sunshine. A mix shows clouds. Many failures show a storm. This gives a fast feeling for a job without opening any details, and it is a helpful signal on team dashboards.

Now open the hood and look at what actually happens while the build runs.

The workspace

The workspace is a folder on the agent where the build does its work. The build downloads source code into it, compiles files there, and writes temporary results there. Think of it as the cook’s private counter. Two builds of the same job may reuse the same workspace, which is faster because old downloads are still there, but that can carry leftover files from one build into the next and cause strange results. Many teams therefore choose to wipe the workspace at the start or the end, or to use a brand new one for every build.

Stages and steps

In a pipeline build, the work is divided into stages with clear names. The Jenkins page draws a row of boxes, one per stage, and colors each box. At a glance, anyone can see that “Compile” passed, “Test” passed and “Deploy” failed. Inside each stage sit the steps. Some useful stage features are worth knowing.

• Parallel stages run side by side to save time, such as testing on two operating systems together.
• Conditions make a stage run only sometimes, for example only on the main branch.
• Input steps pause the build until a person approves, useful before a release.
• Timeouts stop a stage that takes too long, so one stuck build cannot hang forever.
• Retries repeat a step a few times when it fails for reasons such as a brief network problem.

Post actions

A pipeline can define post actions, closing steps that run depending on the outcome. Some run always, some only on success, some only on failure, and some when the status changes from the previous build. This is where teams send chat messages, publish reports and clean up. Because post actions run even after a failure, they are the safest place for cleanup work.

The console log

The console log is the running text output of the build. It is the first place to look when something goes wrong. Good habits make it much easier to read.

• Read from the bottom upward. The final error message is often only a symptom, and the true cause is a few lines above.
• Look for the first error, not the last. One early failure can cause a wave of later ones.
• Use clear stage names so the log can be jumped through quickly.
• Keep the output short and meaningful. A log with a million lines of noise hides the one line that matters.
• Never print secrets. Jenkins masks stored credentials in logs, but a value printed some other way will not be protected.

A build takes things in and gives things out. Knowing both sides helps you design builds that are clear and repeatable.

flowchart LR
    In1["Source code version"] --> B["One Build"]
    In2["Parameters chosen"] --> B
    In3["Environment variables"] --> B
    In4["Credentials"] --> B
    B --> Out1["Console log"]
    B --> Out2["Result status"]
    B --> Out3["Artifacts"]
    B --> Out4["Test reports"]
    B --> Out5["Notifications"]

Inputs

The most important input is the exact version of the source code. A good build always knows precisely which change it was built from, so you can say “build 57 came from this exact code.” Parameters let a person or another job choose options at start time. Environment variables are named values that Jenkins provides automatically, such as the build number, the job name and the workspace path, and steps can read them. Credentials supply secrets when needed.

Outputs

The most visible output is the result status. But the useful outputs are often the files. Artifacts are files the build deliberately saves, such as an installable package or a document. Test reports are read from files that the tests create, and Jenkins turns them into charts and trends across builds. Notifications tell people the outcome. And fingerprints, short unique codes for files, let Jenkins track which build produced which file, so you can later trace a program running in production back to the build that made it.

Making builds reproducible

A build is reproducible when running it again on the same code gives the same result, no matter which day it is or which machine runs it. This is the quiet superpower that makes automation trustworthy. Without it, a green mark means little, because nobody knows whether it would be green tomorrow. Several habits work together to achieve it.

• Record the exact code version. Every build should know the precise change it was built from, not just a branch name that may move.
• Pin tool and library versions. Name the exact versions to use, so an upstream release cannot silently change your results.
• Start clean. Use a fresh workspace or a fresh container so leftovers cannot leak from an earlier run.
• Avoid hidden inputs. A build that quietly depends on the current date, a random number or a live outside service will behave differently each time.
• Keep the recipe in version control. When the Jenkinsfile lives beside the code, an old build can be understood by reading the recipe from that moment in history.

Passing information between builds

Jenkins lets one job start another and pass values along. A common chain is build, then test, then deploy, each its own job connected by triggers. The job that starts another is called the upstream job, and the one that gets started is the downstream job. Modern teams often prefer one pipeline with several stages instead of many small chained jobs, because everything is visible in one place, but chains are still common in older setups.

The same recipe can be cooked in different ways. Parameters and variables let one job serve many situations without copying it.

Parameterized builds

A parameterized build asks questions when it starts. The question might be a text box, a yes or no checkbox, or a dropdown list. For example, a deployment job might ask, “Which environment: test or staging?” and “Which version?” The answers become variables that the steps can use. This lets one job handle many cases, and it also leaves a record, because every build stores the answers it was given.

Environment variables

Jenkins gives every build a set of environment variables automatically. These include the build number, the job name, the address of the build page, the workspace folder, and, for multibranch jobs, the branch name. You can also define your own. Steps read these values so they do not need to guess who they are or where they are running.

Credentials

Builds often need a password, a token or a key, for example to download a private package or to publish a file. Jenkins has a credentials store where secrets are saved once and given a name. The build asks for the credential by name, and Jenkins supplies the value only while the build needs it, masking it in the log by replacing it with stars. Never write secrets into the job settings as plain text, never commit them into code, and never print them on purpose.

What happens when many builds want to run at the same moment? Jenkins has clear rules for waiting, sharing and running in parallel.

How the queue behaves

Every build that cannot start at once waits in the queue. Jenkins shows the reason next to each waiting item, such as “Waiting for next available executor” or “Waiting for a machine with label linux.” If several triggers for the same job arrive while it is already waiting, Jenkins usually merges them into one queued build rather than stacking up copies. That is why ten quick commits may produce a single build that contains all ten changes.

Running builds side by side

Each executor runs one build at a time. More executors on more agents mean more builds in parallel. A single job can also be told to allow or forbid concurrent builds. When forbidden, a second build of the same job waits until the first one finishes. This is important for jobs that touch a shared resource, such as a deployment to one server, where two runs at the same moment could clash.

Builds across branches and pull requests

Modern teams rarely work on only one line of code. They create branches, separate copies of the code where new work can happen without disturbing everyone else, and they open pull requests, formal requests to merge that work back into the main line. A multibranch pipeline gives every branch and every pull request its own build history. The developer sees a green or red mark right next to the proposed change, and reviewers can decide with confidence. When the branch is merged and deleted, its jobs disappear on their own.

This has a helpful effect on team habits. Problems are found before the code joins the main line, when they are still cheap to fix. It also means the number of builds can grow very quickly, so retention rules and enough agents become more important as the team adopts this style.

Choosing the right agent

Labels route builds to the right machines. A build may ask for “linux and docker” or for an agent with a graphics card. Good labels keep special machines free for jobs that truly need them. Static agents stay switched on and are good for special hardware. Dynamic agents are created for one build and thrown away afterward, often as short-lived containers, giving every build a clean, identical start.

flowchart LR
    Ctrl["Jenkins Controller"] -->|"needs an agent"| K8s["Kubernetes API Server"]
    K8s --> P1["Agent Pod 1"]
    K8s --> P2["Agent Pod 2"]
    P1 -->|"connects back"| Ctrl
    P2 -->|"connects back"| Ctrl
    P2 -->|"build finished"| Gone["Pod deleted"]

Reading the diagram

When a build is waiting, the controller asks the Kubernetes API server, the front door of a container platform, for a new agent. Kubernetes starts an agent pod, a small group of containers, which connects back by itself. The build runs inside it. When the build ends, the pod is deleted and nothing is left behind, so the next build never inherits mess from this one.

Every build leaves a record. Without cleanup, those records pile up and slowly make Jenkins heavy.

Because each build stores a log, results and sometimes large files, a busy job can create a great deal of data. Jenkins provides a build discarder, a rule that deletes older builds automatically. You can keep only the most recent number of builds, or only builds newer than a certain number of days, or both. You can also say that artifacts should be deleted sooner than the log, since artifacts are usually the biggest part.

Useful actions on a finished build

• Replay: run a pipeline build again with a small change to the script, without editing the repository, useful for trying a fix.
• Rebuild: start a new build with the same parameters as an old one.
• Keep this build forever: protect one important build from automatic cleanup.
• Changes: see exactly which code changes went into the build, and who made them.
• Test results: open charts and lists of passed and failed tests.
• Delete build: remove one record by hand.

A build runs commands, reads secrets and can reach production systems. That power must be handled carefully.

Permissions for builds

Jenkins can control who may see a job, who may start a build, who may cancel one, and who may change or delete it. A common setup lets all developers see and start builds, lets team leads edit jobs, and lets only administrators change system settings. This is least privilege: each person gets only the access needed.

A team that cannot see its builds will only notice trouble when a customer does. A few simple measurements turn surprises into early warnings.

Notifications

Builds should tell people the outcome without being asked. Common choices are email, team chat rooms and messages on the pull request itself. The key is to notify the right people at the right moment. Send failures to the author of the change and to the team that owns the job, and send a “fixed” message when a red job turns green again. Too many messages cause people to mute them, so send fewer, clearer ones.

Metrics tools

Jenkins can publish numbers about itself through plugins for popular monitoring tools. A common setup exposes metrics that Prometheus, a widely used metrics collector, reads regularly, while Grafana draws charts and sends alerts. OpenTelemetry, an industry standard for traces and metrics, can also follow one build through many systems. Set alerts on symptoms that matter, such as a growing queue, a falling success rate or a nearly full disk.

Build health from the team’s point of view

Numbers on a dashboard are only useful when people act on them. Healthy teams agree on a few simple habits around their builds. They decide who looks at a red build first, usually the author of the latest change. They agree on how quickly a broken build should be fixed or reverted, often within the hour. They review the slowest and flakiest jobs once a month and pick one improvement each time. And they celebrate small wins, such as cutting a twenty-minute build to ten, because faster builds make everyone’s day smoother.

It also helps to keep a short public page that explains, in plain words, what each important job does, who owns it, and what to do when it turns red. New teammates can then help from their very first week, instead of waiting for the one person who remembers how things work. Good builds are as much about people and habits as they are about machines and settings.

Automated builds bring large benefits, and like every tool they come with costs that are worth knowing.

Trade-offs to think about

A pattern is a proven way to solve a common problem. An anti-pattern is a habit that looks helpful and causes pain later.

Patterns worth copying

Habits to avoid

These are lessons that experienced teams usually learn the hard way. You can learn them the easy way, by reading them now.

Best practices

• Keep builds fast. Aim for feedback in minutes. Cache downloaded files, run tests in parallel, and put quick checks first.
• Keep builds repeatable. The same code should give the same result on any agent. Use clean workspaces, pinned versions and container images.
• Keep builds small and focused. A build should have one clear purpose that its name explains.
• Name things clearly. Use readable job names, stage names and step descriptions so a log tells a story.
• Use webhooks, not polling. They give faster feedback and lower the load on everyone.
• Set retention rules on day one. Decide how many builds and how many days to keep before the disk fills.
• Use timeouts and retries wisely. Timeouts stop stuck builds, and small retries absorb brief network trouble, but retries should never hide real bugs.
• Save what matters. Archive artifacts and test reports so results can be inspected later.
• Record the cause of failures. Keep a short note of why a build failed before rerunning it.
• Back up and rehearse. Save the Jenkins home folder or its configuration files, and practice restoring them.

Common mistakes

• Ignoring red builds. A failing build that stays red sends the message that quality does not matter.
• Sharing one workspace between unrelated builds. Leftover files cause mysterious passes and failures.
• Storing huge artifacts on the controller. The disk fills and the whole system stops.
• Giving everyone administrator rights. It is convenient until someone deletes something important.
• Testing only on the main branch. Problems are far cheaper to fix before code is merged.
• Not knowing which code a build used. Always record the exact code version so any build can be traced.
• Letting builds depend on the time of day or on outside services. These are the classic causes of flaky results.

Every team meets red builds, stuck builds and strange builds. A calm, repeatable routine makes them far less scary.

A simple routine for a failed build

Common situations and their usual causes

Builds are the heartbeat of almost every modern engineering team. Here is how the ideas look in practice.

Lessons that repeat across companies

Look across these examples and a few lessons appear again and again. Successful teams treat builds as a product for developers and measure how quickly and reliably they run. They standardize early with templates and shared libraries. They automate the running of Jenkins itself, including backups and agent creation, so no single hero engineer holds everything up. They keep builds fast, because slow feedback trains people to stop waiting for it. And they treat a broken build as everyone’s problem. None of this needs a large budget. A small team can follow every one of these habits from the first week.

A build is the moment when Jenkins stops being a description and starts doing real work.