Archiving means telling Jenkins, “Please keep these files, and attach them to this build forever, or until I say otherwise.”

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, and a build is one single run of that job. While a build runs, it works inside a folder on a machine called an agent. That folder is the workspace, and it is like a temporary desk. Files appear on the desk while the build works, and the desk is often cleaned afterward, or reused by the next build, or lost entirely if the agent is a short-lived container.

An artifact is any file that a build produces and that you want to keep. Common examples are an installable program, a compressed bundle of a website, a container package, a test report, a screenshot from a failed test, a log file, or a file of measurements. Archiving is the step where Jenkins copies chosen files from the workspace to a safe place and attaches them to that build’s record. After that, anyone with the right permission can open the build page and download those files, even years later, no matter what happened to the workspace.

The most important idea is that an archived artifact belongs to a specific build. If build 57 archived a file called shop.zip and build 58 archived a different shop.zip, both files are kept, each attached to its own build. You can always say, “Give me the package that build 57 made.” That is very different from a shared folder, where the newest file overwrites the older one.

What teams commonly archive

The idea of keeping build results is as old as build servers themselves, and it grew from a very practical frustration.

In the early days of automated builds, a build server compiled the code, reported “success,” and that was the end. If a tester wanted to try the result, someone had to log into the build machine and copy files by hand from a folder. Which folder? Which version? Was it overwritten by the next run? Nobody knew for sure. Teams often ended up with folders named final, final2 and really-final, and nobody trusted any of them.

Early Hudson, which later became Jenkins, solved this by adding a simple feature: after a build, choose some files, and the server would store them next to the build’s record. Each build carried its own files, and the web page showed a download link. This tiny idea, “attach the output to the build that made it,” turned the build server from a passing judge into a reliable library of every version ever produced.

A handful of small ideas explain almost everything about artifacts. Learn them once and the rest of the guide is easy.

Job, build, workspace and artifact together

A job is the recipe, and each run of it is a build. During a build, the agent works in a workspace. The controller, the main Jenkins server, keeps the build record. When the build archives artifacts, the files travel from the agent’s workspace to storage managed by the controller, and the build record then lists them.

An artifact starts life on an agent and ends up in storage. Seeing the trip explains how downloads, disk space and speed are connected.

flowchart LR
    Dev["Developer"] -->|"push code"| SCM["Git Repository"]
    SCM -->|"webhook"| Ctrl["Jenkins Controller"]
    Ctrl --> Queue["Build Queue"]
    Queue --> Agent["Agent"]
    Agent --> WS["Workspace with output files"]
    WS -->|"archive step"| Store["Artifact Storage"]
    Store --> Rec["Build Record"]
    Rec --> UI["Build Page with Download Links"]
    Agent -->|"large or long-lived files"| Repo["External Artifact Repository"]
    Users["Testers and Teammates"] --> UI
    Users --> Repo

Reading the diagram

Follow the arrows from the left. 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, which puts a build request into the build queue. When an agent has a free executor, the build runs there and creates files in its workspace. At the archive step, chosen files travel to artifact storage and are listed in the build record. The build page then shows download links. For very large or long-lived files, teams often send them instead to an external artifact repository, a warehouse built for packages. Testers and teammates then fetch what they need from either place.

Where the files live by default

By default, Jenkins stores archived artifacts on the disk of the controller, inside the Jenkins home folder, in a directory that belongs to that specific build. This has advantages and one big drawback. The advantage is simplicity: nothing extra to install, and backups of the home folder include artifacts. The drawback is that the controller’s disk is precious. It also holds job settings, credentials and build history. If artifacts fill that disk, the whole Jenkins can stop working.

Storage options at a glance

Under the friendly download links, Jenkins performs a small, careful copy operation. Knowing its steps explains many surprises.

Step by step

File patterns in plain words

You tell Jenkins which files to keep with a file pattern. A pattern is a short line of text where a star stands for “anything here.” A single star matches any name inside one folder. A double star matches through any number of folders. You can list several patterns separated by commas, and you can also list patterns to exclude. The habit to build is being specific. A pattern that says “everything” will also grab temporary files, downloaded tools and folders full of junk, and your storage will fill with things nobody needs.

Size, compression and speed

Because artifacts travel from the agent to storage over a network connection, size affects speed. A folder holding twenty thousand tiny files can take far longer to transfer than one compressed bundle of the same total size, since each file carries a little overhead. The simple cure is to compress many small files into a single archive file before the archive step. Compression also saves storage, which helps retention. The trade-off is that a bundle must be unpacked before you can look inside, so keep individual files for small reports that people open in the browser, and use bundles for large collections such as websites or test output folders.

What happens when nothing matches

By default, if the pattern finds no files, Jenkins marks the build as failed, because archiving nothing usually means something went wrong earlier. This is a useful safety net. Sometimes, though, an empty result is normal, such as a screenshot folder that only has files when a test fails. For those cases Jenkins offers an option to allow an empty archive, so the build does not fail just because no screenshots were taken.

Saving files is only half the job. The other half is helping people find the right ones quickly.

On the build page

Open any build that archived files, and the page lists them under a heading for build artifacts. Each file has a link, and there is usually an option to download everything as one compressed bundle. Folders are shown with the same layout the files had in the workspace, so a tidy structure at the time of archiving makes a tidy page later.

The handy permanent links

Jenkins offers stable, ever-fresh links for common needs, called permalinks. Instead of remembering build 57 or build 61, you can use “last build,” “last successful build” or “last stable build,” and Jenkins always points to the newest one of that kind. This makes it easy to share one address that always leads to the latest good package.

Using artifacts from another job

Often one job builds a package and another job tests or deploys it. The second job needs the first job’s files. There are a few ways to connect them. A popular plugin lets a job copy artifacts from another job’s chosen build, for example “the last successful build of the packaging job.” A more modern and more solid approach is to publish the package to an artifact repository, and have the next job download it from there, by version. This avoids tight coupling between Jenkins jobs and makes the package available to people and systems outside Jenkins too.

Jenkins pipelines have two file-moving tools that sound alike and behave very differently. Mixing them up is one of the most common beginner mistakes.

A pipeline often has several stages, and each stage may run on a different agent. Suppose the build stage compiles code on one machine, and the test stage runs on another. The second machine needs the compiled output. That is a job for stash. A stash takes a set of files from one workspace and holds them temporarily so a later stage can unpack them, on any agent, using unstash.

A healthy combination

Many good pipelines use both. They stash the compiled output so that parallel test stages on different agents can all use it. At the end, they archive the final package and test reports so people can download them. Stashing keeps the pipeline moving, and archiving preserves the results.

A fingerprint lets Jenkins answer a very valuable question: “This file is running in production. Which build made it?”

A fingerprint is a short, unique code that Jenkins calculates from the contents of a file. Two files with the same contents get the same code, and even a tiny change gives a completely different code. When you ask Jenkins to record fingerprints for archived files, it stores each code together with the name of the job and build that produced it.

Later, if you find a file somewhere else, you can give its code to Jenkins and ask, “Have you seen this?” Jenkins can then show you the build that made it, and every other build that used it. This works across jobs too. If a package built in one job was consumed by a test job, and later by a deployment job, the fingerprint links all three, so you can follow the file’s whole journey.

Why teams care

• Incident response. When a bug appears in production, you can trace the running package back to its exact build and its exact code.
• Audits. Regulators and customers often ask, “Prove that this release came from your tested pipeline.” Fingerprints and archived files provide that proof.
• Cleaning up safely. Before deleting an old build, you can see whether a later job still depends on its files.
• Integrity checks. A matching code shows that a file has not changed since it was built.

Artifacts are the heaviest part of a build’s record. Without rules, they quietly consume every last byte of disk.

Every archived file takes space, and busy jobs create new builds constantly. Jenkins provides a build discarder, a rule that deletes old builds automatically. The clever part is that it can treat build records and artifacts separately. You might keep the log and result of the last hundred builds, because they are tiny, but keep the artifacts of only the last ten, because they are large. This gives you a long history of what happened, without a mountain of old packages.

The life of an artifact over time

flowchart LR
    C["Created in workspace"] --> A["Archived with the build"]
    A --> U["Used: downloads and later jobs"]
    U --> R{"Is it a release?"}
    R -->|"Yes"| P["Published to repository and kept long-term"]
    R -->|"No"| D["Discarded by retention rule"]

Reading the diagram

Every artifact starts life as a file created in the workspace. It is then archived with the build, and for a while it is used: testers download it and later jobs consume it. Then comes a decision point. If the file is a release, it is published to a repository and kept for the long term, because support teams and auditors may need it years from now. If it is an ordinary build output, it is discarded by the retention rule once newer builds have replaced it. Drawing this life story for your own jobs, even on a napkin, is the fastest way to choose sensible retention numbers.

Keeping one build forever

Sometimes a specific build is precious, such as the exact build that produced a public release. Jenkins lets you mark an individual build as “keep this build forever,” which protects it and its artifacts from automatic cleanup. Use this sparingly, since forever is a long time, and consider copying the final package to an artifact repository instead.

Measuring the problem

To keep disk use under control, look at the size of each job’s artifacts, and multiply by the number of builds you keep. That simple multiplication often reveals a surprise, such as one job using half the disk. Trimming that single job, by archiving fewer files or discarding sooner, may solve the whole problem.

As teams grow, the controller’s disk stops being a good place for packages. Specialized storage takes over.

An artifact repository is a system built specifically to store and serve packages. It gives each package a name and a version, keeps every version, lets other tools download by version, and often adds features like access control, cleanup rules and security scanning. Well-known products exist for this purpose, and cloud providers offer storage services that can play the same role.

flowchart LR
    B["Jenkins Build"] -->|"publish package with version"| R["Artifact Repository"]
    B -->|"reports and logs"| J["Jenkins Build Page"]
    R --> T["Test Job"]
    R --> S["Staging Deployment"]
    R --> P["Production Deployment"]
    R --> U["Other Teams and Tools"]

Reading the diagram

The build produces two kinds of output. The versioned package goes to the artifact repository, where every later step downloads it by version: the test job, the staging deployment, the production deployment and even other teams. The lighter reports and logs stay on the Jenkins build page, next to the run that created them. This split keeps the controller light while making the package available to everyone who needs it.

Why this pattern is popular

• The controller stays healthy. Large files never fill its disk.
• Versions are first-class. Everyone refers to “version 1.4.57” instead of “the last successful build of job X.”
• Everything downstream uses the same file. The package that was tested is exactly the package that is deployed, which is the golden rule of delivery: build once and promote the same artifact.
• Access can be tailored. The repository can give production systems read access without giving them any access to Jenkins.
• Lifecycle rules are richer. Snapshots can expire quickly while releases are kept for years.

Cloud storage plugins

There are Jenkins plugins that send archived artifacts to cloud object storage instead of the controller’s disk. From the user’s point of view nothing changes: the build page still lists files and offers downloads. Behind the scenes, the files live in the cloud, which gives more room and cheaper long-term storage. This is a good middle path for teams that want to keep using the built-in archive feature without risking the controller disk.

Archiving can be turned on from a web form or from a pipeline recipe. Both do the same thing.

In a classic job

In a freestyle job, open the job’s configuration page and add a post-build action named for archiving artifacts. A box appears where you type the file pattern. Further options let you exclude patterns, allow an empty archive, archive only when the build succeeds, record fingerprints, and choose whether to keep only the latest build’s artifacts. Save the job, and every future build will archive matching files.

In a pipeline job

In a pipeline, archiving is a step placed in a stage or in the closing section. The step takes the same kinds of choices: the file pattern, exclusions, whether an empty result is allowed, and whether to record fingerprints. Placing it in the closing section that always runs means failure evidence is still saved when the build fails. Because the pipeline recipe lives beside the code, the archive rules are reviewed and versioned like any other change.

Choices worth understanding

A worked example: planning archiving for one small team

Imagine a team of six building a web shop. Their pipeline compiles the site, runs tests, and produces a zipped copy of the website. Here is how they might plan their archiving, in words. The zipped website is named with the version and build number, so every copy is easy to tell apart, and it is archived with fingerprints turned on. The test report files are archived from every build, because they are small and useful for spotting trends. Screenshots from the browser tests are archived only when tests fail, in a closing section that always runs, and the option to allow an empty archive is switched on, since a passing run has no screenshots at all.

For retention, they keep the build records and logs of the last two hundred builds, keep the zipped website for the last fifteen builds only, and delete screenshots after two weeks. When a version is approved for release, the pipeline publishes that exact zip file to a repository, and the Jenkins copy is allowed to expire normally. Notice what this plan achieves. Nothing valuable is lost, disk use stays predictable, every file is traceable, and nobody has to remember a manual step.

Artifacts often contain valuable or sensitive things. Who can see them, and what is inside them, both matter.

Permissions

Jenkins can control who may see a job, who may view its builds, and who may download artifacts. A common setup lets all developers view and download from ordinary jobs, while restricting release jobs to a smaller group. Follow least privilege, meaning each person gets only the access their work needs.

Artifacts quietly grow every day. A few simple measurements keep that growth from becoming an emergency.

Logs that help

The build’s console log says which files were archived and how many. If a build “succeeded” but the expected package is missing from the page, this line is the first place to look. Good pipelines also print a short summary just before archiving, such as the names and sizes of the files about to be saved. That habit makes surprises visible at once.

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 disk and build figures, while Grafana draws charts and raises alerts. Set alarms on symptoms that matter, such as disk usage passing a limit, not on every tiny twitch.

Archiving is simple and powerful. It also has costs that grow quietly, so it pays to know both sides.

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

• Archive only what people need. Use specific patterns and exclusions.
• Archive failure evidence too. Put logs and screenshots in a closing section that always runs.
• Name files with versions. A version or build number in the file name prevents confusion.
• Fingerprint releases. Make every deployed file traceable to its build.
• Publish packages to a repository. Keep Jenkins for evidence and short-term needs.
• Set retention on day one. Decide how many builds and how many days of artifacts to keep, before the disk fills.
• Use different rules for different files. Short for bulky artifacts, longer for logs, longest for releases.
• Compress many small files. One bundle is faster to move and easier to store.
• Print what you archive. A short listing in the log makes surprises visible.
• Watch disk space. Set alarms early and check which jobs use the most.
• Protect sensitive files. Review contents, restrict downloads and shorten retention.

Common mistakes

• Archiving nothing at all. Then no one can retrieve last week’s version.
• Archiving the whole workspace. It fills the disk with clutter.
• Confusing stash with archive. Stashed files disappear when the build ends.
• Trusting Jenkins as the permanent archive. It is a working record, not a vault.
• Forgetting the empty-archive option. Builds fail only because an optional folder was empty.
• Ignoring failed builds. The most valuable evidence is exactly what a failed build produces.
• Leaving secrets in archived files. They stay downloadable for as long as the build is kept.
• Never checking sizes. One growing report can quietly use half the disk.

Sooner or later, an expected file is not on the build page, or the disk is suddenly full. A calm routine finds the cause quickly.

A simple routine for a missing artifact

Common situations and their usual causes

Archiving artifacts looks small, yet nearly every serious engineering team depends on it. Here is how the ideas appear in practice.

Lessons that repeat across teams

Look across these examples and a few lessons appear again and again. Successful teams treat build outputs as valuable records, not as leftovers. They save only what people need, and they name it clearly. They separate short-lived evidence from long-lived releases, and they store each in the right place. They record fingerprints so that any running file can be traced. And they watch disk space long before it becomes a crisis. None of this needs a large budget. A small team can follow every one of these habits from the very first week.

Habits of teams that never lose a file

Teams that rarely get burned by missing artifacts share a few quiet habits. They write down, for every job, what it archives, where the file goes next and how long it lives, often in a single short page that anyone can read. They test their recovery path now and then, by picking an old release at random and making sure it can still be found and downloaded. They review the biggest jobs once a month, because storage problems grow slowly and then arrive suddenly. And they treat a change to an archive rule like a change to code: someone reviews it, and the reason is written down. These habits cost very little time, and they turn artifacts from a hidden risk into a reliable safety net that the whole team trusts.

Archiving artifacts is how a Jenkins build carries its results out of the kitchen before the cleaning crew arrives.