Build history is the saved list of every past run of a job, together with the full record of what happened in each one.

Start with the basics. Jenkins is an automation server, a program that stays switched on and does tasks for you. A job is the saved description of a task, like a recipe. A build is one single run of that job, like one cooking session. Each build gets a number, such as #1, #2, #3, and the numbers only ever go up. The build history is the ordered collection of all those builds for a job, newest first, with a stored record for each.

On a job’s main page, Jenkins shows a panel titled Build History, usually on the left side. Each row shows the build number, a colored ball or icon for the result, and the time. Click any row and you open that build’s own page, with the console log, the changes, the test results, the artifacts, and more. So the build history is both a list and a doorway: a list you can scan, and a doorway into each detailed record.

It is worth stressing what the history is not. It is not a backup of your code, and it is not a permanent archive of your releases. It is a working diary about the runs of your automation. Its greatest value is answering questions of the kind “what happened, when, and why?” quickly, without needing anyone to remember.

What is stored with every entry

Keeping a record of every build was one of the earliest ideas in Jenkins, and it shaped how teams think about quality.

Before build servers, a failed compile was a private embarrassment. A developer saw an error on their own computer, fixed it, and nobody else ever knew. There was no shared record of how often builds broke, how long they took, or which changes caused trouble. When Hudson, later renamed Jenkins, began running builds on a shared server, it also began writing down the result of each run in a place everybody could see.

That simple change had a surprising cultural effect. A build failing in public, with a red ball and a name next to it, made teams care about keeping builds healthy. The history also allowed something new: trends. Instead of asking “does the build work?”, teams could ask “is the build getting slower?” and “are failures becoming more frequent?” The diary turned single events into a story over time.

A small set of ideas explains almost everything about build history. Learn them once and the rest is easy.

The cast of characters

The controller is the main Jenkins server. It keeps the build history. The agent is a separate machine or container that actually runs a build. When a build runs on an agent, the agent sends its console output and results back to the controller, and the controller writes them into the history. That is why the history stays available even when the agent is a short-lived container that disappears the moment the build ends.

The diary is not kept in a database. It is kept in files on the controller, and this simple choice explains many behaviors.

flowchart LR
    Trigger["Trigger: code change, timer or click"] --> Ctrl["Jenkins Controller"]
    Ctrl --> Queue["Build Queue"]
    Queue --> Agent["Agent"]
    Agent -->|"console output and results"| Ctrl
    Ctrl --> Home["JENKINS_HOME on Controller Disk"]
    Home --> Job["Job Folder"]
    Job --> B1["Build 1 Record"]
    Job --> B2["Build 2 Record"]
    Job --> B3["Build 3 Record"]
    Ctrl --> UI["Job Page: Build History Panel"]
    Home --> UI

Reading the diagram

Follow the arrows. A trigger starts a build, and the controller places it in the build queue. An agent runs it and sends the console output and results back over its connection. The controller writes these into the JENKINS_HOME folder, in a directory belonging to the job, and inside it a small folder for each build. When you open the job page, Jenkins reads those folders to draw the build history panel and each detailed page.

Files, not a database

Inside the job’s folder, there is a directory called builds, and inside it one folder per build number. Each build folder holds a few small files. One is an XML file that summarizes the build: its result, its start time, its duration and its causes. Another is the console log as plain text. Others hold changes, test results or pointers to archived artifacts. A small file in the job folder also remembers the next build number to use.

This design has clear benefits. Jenkins is easy to install, because no database is needed. Backups are simple, because copying the home folder copies everything. And you can inspect a record with an ordinary text editor if you must. It also has costs. Thousands of build folders on one disk can slow down pages that list them, and a large history means a large backup. This is why cleaning up old builds is not just tidiness. It is a performance and safety task.

The build number file

Jenkins remembers the next number to assign, so numbers never repeat, even after deletions. If you delete builds 1 to 50, the next run is still build 51 or later, not build 1. This is deliberate: an old link to “build 12” must never accidentally point to a different, newer run. If you ever need to reset numbering, it is a special, careful operation, and it is best avoided on jobs that other systems refer to.

The panel on the job page is packed with small clues. Learning to read it quickly saves hours.

The rows

Each row shows a build number, a status ball and a time. Blue or green usually means success, yellow means unstable, red means failure, grey means aborted or not built, and a moving or flashing ball means the build is running right now. A small weather-like icon on the job list summarizes recent health, from sunshine when most builds pass to storms when most fail.

Searching and filtering

The panel includes a search box. You can type a build number, or part of a message, to jump to matching entries. This is handy on a job with thousands of builds, when scrolling would take forever. Some views also let you filter by result, for instance showing only failures, so you can see how often they happen.

Opening a single build

Click a row and you enter that build’s page. The left side lists useful links: the console output, the changes that went into it, test results, any artifacts, and actions such as replaying or rebuilding it. The top of the page states the cause, such as “Started by user Anita” or “Started by timer,” and the duration. Each of these is a small window into that moment of the past.

A build’s entry in the history is created when the build begins and completed when it ends. Following that life shows where each piece comes from.

flowchart TD
    A["Trigger arrives"] --> B["Build number assigned"]
    B --> C["Queued: waiting time recorded"]
    C --> D["Started on an agent"]
    D --> E["Console log written line by line"]
    E --> F["Steps and stages run"]
    F --> G["Result decided"]
    G --> H["Reports, artifacts and changes attached"]
    H --> I["Record saved and shown in history"]
    I --> J{"Retention rule met?"}
    J -->|"Yes"| K["Record deleted"]
    J -->|"No"| L["Record kept"]

Two clocks in every record

Every entry contains two time measurements beginners often mix up. Queue time is how long the build waited before any machine began it. Run time is how long it actually ran. If builds feel slow, the history helps you tell which clock is to blame. Long queue times point to too few agents or executors. Long run times point to the pipeline itself, where tuning may help.

A single build tells you what happened once. A trend tells you where you are heading.

Jenkins can draw graphs across many builds. The most common are the build time trend, which shows how long each build took, and the test result trend, which shows how many tests passed, failed and were skipped in each build. Other plugins add graphs for code coverage, warnings, code size and more. These graphs come straight from the build history, so the longer the history, the more meaningful they become.

Reading the shape of a graph

• A sudden jump often points to one specific change. Look at the builds on either side of the jump and read their change lists.
• A slow climb usually means gradual growth, such as more tests or more data. It calls for planned tuning, not a hunt for a single culprit.
• A sawtooth pattern that goes up and down regularly may reflect a cache being emptied, or a scheduled job competing for machines.
• A flat line at zero failures for a very long time is usually good, but check that the tests still exist and still run.

The most valuable use of build history is playing detective. Here is a repeatable way to find what went wrong and when.

When several changes arrive together

Sometimes a single build contains many code changes, because they were merged during the quiet period, or because several people pushed at once. Then the first bad build has a long list of suspects. A useful trick is to build the suspect changes one by one, in a test branch, to find which one breaks. The history helps by telling you the exact range of changes to examine, so you never need to search the whole project.

When the failure is not the code

Not every red build is a code problem. Look for patterns in the history. If failures cluster on one agent, that agent may be sick. If they cluster at a particular hour, an outside service may be busy or a scheduled job may be competing for machines. If they appear and disappear with no change, a flaky test is likely. The history makes these patterns visible, and patterns point to causes.

History is valuable, but every record uses disk space. Retention rules balance memory against cost.

Left alone, Jenkins may keep every build forever. For a busy job that runs every few minutes, that means tens of thousands of records within a year. Each holds a log and sometimes large files. Sooner or later the disk fills or pages slow down. The cure is a build discarder, a rule that removes old builds automatically.

The choices

A sensible starting point

Records and logs are small, while artifacts are large. So many teams keep a long record history and a short artifact history. For example, they might keep the last two hundred builds, but keep saved files for only the last twenty. Jobs that run very often may keep a smaller number, while release jobs keep everything, or better, copy the release files to a proper repository and let Jenkins forget them after a while.

Global rules and defaults

Instead of setting a rule on every job, teams often apply a standard through shared templates, folder-level settings or configuration files. This prevents the common problem where new jobs are created with no retention at all, and go unnoticed until the disk alarm rings. Standard defaults are one of the cheapest and most effective habits.

Besides automatic rules, Jenkins lets you tend the history with your own hands. Each action has good uses and small dangers.

Display names and descriptions

A list of numbers is hard to read. Was the release build number 431 or 432? Jenkins lets a build carry a display name and a description. A pipeline can set them automatically, for instance to the version number and the branch. Then the history panel shows meaningful labels, and a glance is enough to find the right entry. This small habit makes the history far more useful, especially for release jobs.

Deleting with care

Deleting a build cannot be undone, and it leaves a gap in the numbers. Do it only when there is a real reason, such as a leaked secret. If the build is referenced by other jobs, through artifacts or fingerprints, check before deleting. When in doubt, mark it as kept, or leave it for the retention rule to handle.

A single job’s history answers questions about one job. Teams also need a wider view across many jobs.

The global build history

Jenkins offers a page that combines builds from many jobs into one timeline. It shows which jobs ran, when, and how long they took, laid out on a horizontal time axis. This view is excellent for spotting crowding: a moment when many jobs overlap and compete for machines, or a quiet gap when machines sit idle. It answers questions like “why was everything slow at nine?” in a single glance.

Views and dashboards

Jenkins lets you group jobs into views, tabbed lists that show each job’s latest status and weather icon. Plugins add dashboards that display the build state on a large screen in the team room, often in bright colors, so a broken build is impossible to miss. Some show only failing jobs, and some show who is responsible.

The history of one machine

Every agent also has its own build history, listing the builds that ran on it. This is a hidden gem. If one agent seems to cause trouble, its history shows all its builds side by side, and you can see whether it fails more than its neighbors.

In pipeline jobs, the history goes deeper than one ball per build. Every stage of every run can be seen.

A pipeline divides a build into stages, named phases such as Build, Test and Deploy. Jenkins can draw a grid where each row is a build and each column is a stage, with a colored box in every cell. At a glance you see that Compile passed on every build, Test failed on builds 61 and 63, and Deploy was skipped on several. The average time for each stage appears at the top of its column, so you can see which stage is the slowest.

flowchart LR
    subgraph Build60["Build 60"]
        A1["Compile: pass"] --> A2["Test: pass"] --> A3["Deploy: pass"]
    end
    subgraph Build61["Build 61"]
        B1["Compile: pass"] --> B2["Test: fail"] --> B3["Deploy: skipped"]
    end
    subgraph Build62["Build 62"]
        C1["Compile: pass"] --> C2["Test: pass"] --> C3["Deploy: pass"]
    end

Reading the diagram

Each box group is one build, and inside it the stages run from left to right. In build 60, everything passed. In build 61, Compile passed but Test failed, so Deploy was skipped, which is the fail-fast behavior. In build 62, everything passed again. A failure now has an address: build 61, stage Test. That is far more precise than “the build is red.”

Why stage views help

• Faster diagnosis. You open the log of the failed stage, not the whole log.
• Bottleneck spotting. The slowest stage stands out, so tuning effort goes where it counts.
• Pattern spotting. A stage that fails often, such as an integration test that depends on an outside service, becomes obvious.
• Shared understanding. Non-experts can follow a colored grid far more easily than a long text log.

A build history is a detailed diary. Anyone who can read it may learn a lot, so it deserves care.

Audit trails

Build history is also an audit trail: a record of who ran what and when. Auditors and security teams value it because it can prove that a release passed its tests, and show who approved it. For this reason, some teams protect history from tampering, and export important records to systems that cannot be edited. Treat the history as evidence, and protect it as you would other evidence.

The history helps you watch your builds, but the history also needs watching. Its size affects how fast Jenkins feels.

Long console logs

A build that prints millions of lines creates a huge log, slows the browser when viewed, and consumes storage. Common causes are tools set to verbose mode, or loops that print in every step. Keep logs meaningful: print progress and errors, not every detail. Some plugins can compress or trim logs, and larger teams ship logs to a dedicated logging system where they are searchable and can be stored more cheaply.

Metrics tools

Jenkins can publish numbers about itself through plugins for popular monitoring systems. A common setup lets Prometheus, a widely used metrics collector, gather figures such as build counts, durations and results, while Grafana draws charts and raises alerts. This gives you months of trends that survive even when old builds are deleted, because the numbers live in the monitoring system, not in the Jenkins folder. It is a wise way to keep a long-term view without a heavy history.

Build history is a gift that comes with upkeep. Knowing both sides helps you use it wisely.

Trade-offs to think about

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

Patterns worth copying

Habits to avoid

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

Best practices

• Set retention on day one. Decide how many builds and how many days to keep before the disk fills.
• Keep records longer than files. Logs and results are small, artifacts are large.
• Name builds meaningfully. Use display names and descriptions such as version and branch.
• Read the trends weekly. Look at duration, success rate and flaky tests, and pick one improvement at a time.
• Use stage names that never change. Stable names keep history comparable.
• Keep logs meaningful. Print progress and errors, not every detail.
• Never print secrets. Use the credentials store and review scripts.
• Export what you must keep. Move releases and audit evidence to long-term storage.
• Watch the controller disk. Alert at a comfortable level, such as seventy or eighty percent.
• Record why builds failed. A short note beats a rerun that hides the cause.
• Give every job an owner. A name on the page makes red builds get fixed.

Common mistakes

• Keeping everything forever. It is easy at first and painful later.
• Deleting history in a hurry. Emergency cleanups often remove the very evidence you need.
• Trusting a green trend without checking totals. Removed tests can make failure counts look wonderful.
• Ignoring queue time. Slow feedback is sometimes waiting, not running.
• Assuming Jenkins is the archive. It is a working diary, not a vault.
• Giving everyone delete rights. Records can vanish by accident.
• Leaving personal data in logs. Test data with real customer details can leak through history.
• Renaming stages casually. The history splits into two stories.

Using history in team reviews

Some of the best uses of build history happen away from the keyboard. Many teams hold a short review every week or two, and the build history is the main exhibit. They ask a few simple questions. How many builds failed this week, and what were the top causes? Which job is the slowest, and did it get slower? How long did it take, on average, to fix a broken build? Which flaky tests appeared again? Each answer comes straight from the history. The team then picks one improvement, such as parallelizing a slow stage or repairing a flaky test, and checks next week whether the numbers moved. Over months, this small ritual turns the history from a passive diary into a steady engine of improvement.

History of settings is a separate story

People often ask, “Who changed this job’s settings, and when?” The build history cannot answer that, because it records runs, not edits. A separate plugin can keep a history of configuration changes, showing who edited what and letting you compare versions. Keeping job settings in pipeline files stored in Git gives the same benefit for free, since Git records every change with an author and a date. Together, the three histories tell a complete story: Git says what changed in the code and the recipe, the configuration history says what changed in the server, and the build history says what happened when things ran.

A worked example: history rules for one small team

Imagine a team of eight building a web shop. Their main job runs on every code change, roughly a hundred times a day. They decide to keep the newest three hundred builds, which is about three days of history, plus any build marked as kept. Artifacts are kept for only the newest thirty builds. Every night, a scheduled job runs the full test suite, and its history is kept for ninety days, because those results are useful for trend charts. Release builds are named with the version number, marked to keep forever, and their files are copied to a repository. Metrics such as duration and success rate flow to a monitoring tool, so yearly charts survive even as old builds are deleted. Finally, an alert fires when the controller disk passes seventy percent full.

Notice what this plan achieves. Every kind of record has a life span that matches its usefulness. The disk stays healthy. Releases are protected. Long-term trends are preserved elsewhere. And nobody has to remember to clean anything by hand.

Sometimes builds vanish, pages crawl or numbers look strange. A calm routine finds the cause quickly.

Common situations and their usual causes

Every serious engineering team leans on build history, often without noticing. Here is how the ideas show up in practice.

Lessons that repeat across teams

Look across these examples and a few lessons appear again and again. Successful teams treat the history as a tool, not as clutter. They read trends, not only single results. They keep detailed records briefly and summary numbers long. They protect secrets and control who may delete. They give builds meaningful names so the story reads clearly. And they set retention before the disk makes them. None of this needs a large budget. A small team can follow every one of these habits from the first week.

Build history is the logbook of your automation. Read it well and it answers almost every “what happened?” question.