Let’s pin down exactly what gets discarded, and what stays behind.

Every time a Jenkins job runs, it produces a build record — a folder on disk containing the full console log, any archived artifacts, published test reports, and metadata about that specific run. Left completely unmanaged, a busy job running dozens of times a day will accumulate thousands of these build records over a year, consuming ever-increasing amounts of disk space and slowing down anything that has to scan a job’s full history.

The build discarder is a per-job (or, in some setups, globally-applied) policy that tells Jenkins how many old builds to keep, and for how long, before automatically deleting the rest. Once a build falls outside the configured retention window, Jenkins removes its logs, its stored artifacts, and its metadata — freeing up disk space without any manual intervention.

A build discarder policy is made up of a small number of independently configurable limits, working together.

These four settings can be combined freely. A very common real-world pattern is keeping build metadata and logs for a long time (they’re cheap) while discarding the much larger archived artifacts far sooner — giving teams a long historical record of “did this build pass or fail” without the storage cost of keeping every single compiled binary forever.

Understanding the internal evaluation order clears up a lot of confusion about “why wasn’t this build cleaned up yet?”

After each build completes, Jenkins evaluates the job’s configured discarder policy against its full build history. It checks the count-based and time-based limits independently: if a build exceeds either threshold — too old, or beyond the maximum count — it becomes eligible for deletion. Jenkins then separately evaluates the artifact-specific limits, which can cause a build’s artifacts to be deleted even while the build’s log and metadata are retained a while longer.

flowchart TD
    A[Build completes] --> B[Evaluate discarder policy for the job]
    B --> C{Build exceeds max count or max age?}
    C -- Yes --> D[Delete entire build record: logs, metadata, artifacts]
    C -- No --> E{Artifacts exceed artifact-specific limit?}
    E -- Yes --> F[Delete artifacts only, keep logs and metadata]
    E -- No --> G[Retain build fully]
        

It’s important to understand that this cleanup process runs as part of the build lifecycle itself — typically evaluated right after a build finishes — rather than as some separate, occasional maintenance job running independently in the background. This means retention policy changes take effect gradually, applying naturally as new builds complete, rather than immediately purging the entire existing history the moment a setting is changed.

Here’s the full journey a single build’s data takes, from creation to eventual disappearance.

A subtle but important consequence of this lifecycle is that any external system relying on a specific old build’s artifacts (a download link, an audit reference, a rollback script) can silently break once that build is discarded — which is exactly why genuinely important builds, like production releases, are usually explicitly protected from automatic discarding rather than left to the default policy.

Automated retention is close to mandatory at scale, but the specific limits chosen involve real trade-offs.

Retention policy intersects with security in a couple of specific, easy-to-overlook ways.

Build logs and artifacts can sometimes contain sensitive information — a stack trace with embedded configuration values, a build log that happened to print an environment variable, or an artifact that includes internal file paths. A sensible retention policy that eventually removes old builds also, as a side effect, limits how long that potentially sensitive information remains exposed and retrievable.

It’s also worth remembering that discarding a build’s artifacts doesn’t retroactively revoke access to copies that may have already been downloaded or promoted elsewhere — retention policy manages Jenkins’ own storage, not every downstream copy that might already exist.

Keeping an eye on disk usage and cleanup behavior helps teams catch problems before they turn into an outage.

Teams managing large numbers of jobs converge on a handful of proven retention strategies.

A handful of small, consistent habits keep retention policy genuinely useful rather than a source of surprises.

Retention policy shows up in essentially every Jenkins installation that’s been running for more than a few weeks.

No — the discarder policy is evaluated as builds complete over time, so existing builds are gradually pruned as new ones finish, rather than an immediate, one-time bulk deletion the moment the setting is changed.

Yes — this is one of the most common configurations, since logs and metadata are typically much smaller than archived artifacts, so many teams keep logs considerably longer.

It’s excluded from the discarder policy entirely and will never be automatically deleted, regardless of its age or how many newer builds have since been created.

It can — trend graphs and history-based visualizations rely on retained build data, so setting retention too short can noticeably shorten how far back those graphs are able to show meaningful history.

Many organizations achieve this through shared pipeline templates, organization folders, or a globally-applied default configuration, so individual job owners don’t each need to configure retention manually themselves.

The build discarder quietly solves one of the least glamorous but most important operational problems in any long-running Jenkins installation: keeping build history from growing without bound. By combining independent count-based and time-based limits — applied separately to overall build records and to heavier artifacts — teams can strike a balance between useful historical visibility and manageable disk consumption, all without any manual, recurring cleanup effort. The details that matter most are getting the balance right for each job’s actual needs, explicitly protecting genuinely important builds from automatic deletion, and staying aware of any compliance obligations that a generic, storage-driven policy might otherwise violate.