A build artifact is any file or bundle of files created by a build that is worth keeping, sharing, or using later.

Start with the word build. A build is one run of a Jenkins job. During a build, Jenkins follows the recipe in the job configuration: it fetches the code, compiles it, tests it, and packages it. The word artifact is used for the things that come out of the process at the end, the products rather than the process itself.

Not every file created during a build is an artifact. A build creates many temporary files, such as half-finished pieces and scratch notes. These are like the flour dust and dirty bowls in the kitchen: they are useful during the work but nobody wants to keep them. Only the files that people or other systems need afterward are picked out and saved as artifacts.

Examples of build artifacts

• A program package, such as a Java archive file, a Windows installer, or a mobile app file, that users can install.
• A website bundle, the ready-to-publish set of pages, images, and scripts.
• A container image, a sealed box holding a program and everything it needs to run.
• A library, a reusable piece of code packaged so other projects can use it.
• Test reports, files that show which tests passed or failed.
• Coverage and quality reports, which show how much code the tests touched and how clean it is.
• Documentation, such as generated manuals.
• Logs and diagnostic files, saved so people can investigate a failed build.

The whole point of a build is to make something. The artifact is that something, so it deserves careful handling.

Without artifacts, a build would be like a factory whose finished products vanish at closing time. Think about what a team needs after a build finishes.

The most important idea: build once, deploy many

Good teams build their program once, save it as an artifact, and then use that exact same file everywhere: in testing, in staging, and in production. They never rebuild it for each environment. Why? Because every rebuild could differ slightly, for example if a library changed in between. If you test one file but ship another, you have not really tested what you shipped. Using the same artifact throughout removes that gap.

A handful of words unlock everything about artifacts. Learn these and the rest feels natural.

Artifact versus workspace file

This difference confuses many beginners, so let us make it very clear. The workspace is a temporary folder that may be cleaned or reused by the next build. A file that only exists in the workspace can disappear. An artifact is a file that has been deliberately saved, so it stays attached to that specific build even after the workspace is wiped.

Several pieces work together to create, save, and share artifacts. Let us meet them.

A Jenkins system has one controller, the brain, and many agents, the workers. When a build runs on an agent, the agent produces files in its workspace. When Jenkins is told to archive them, the chosen files are sent from the agent to the controller, which stores them alongside the record of that build. By default, this happens inside the folder called JENKINS_HOME on the controller, in a location set aside for each build.

For bigger setups, teams do not want the controller to be a warehouse. They connect Jenkins to a separate artifact repository or cloud storage and let agents upload the finished files straight there.

flowchart LR
  SCM["Git Repository"] -->|"source code"| AGT["Build Agent"]
  AGT --> WS["Workspace with Build Output"]
  WS -->|"archive chosen files"| CTRL["Jenkins Controller"]
  CTRL --- HOME[("Build Record and Archived Artifacts")]
  WS -->|"upload package"| REPO[("Artifact Repository")]
  REPO -->|"download by version"| DEP["Deploy Stage"]
  HOME -->|"download from build page"| USER["Team Member"]
  CTRL -->|"record fingerprint"| FP[("Fingerprint Records")]
  DEP --> PROD["Production Servers"]

Walking through the picture

The agent downloads code from the Git repository into a workspace and builds it. The workspace now holds the build output. From there, two things can happen, and teams often do both. First, Jenkins can archive selected files, sending them to the controller so they are attached to the build page and can be downloaded by team members. Second, the pipeline can upload the finished package to an artifact repository, a proper warehouse where later stages and other teams can fetch it by name and version. A deploy stage then downloads the package from the repository and installs it on production servers. Meanwhile Jenkins can record a fingerprint of each file so that its journey can be traced.

Archiving is the act of saving chosen files as permanent artifacts of a build. Let us see how it works from both the classic and the pipeline styles.

In a classic job

In a freestyle job, the Post-build Actions section contains an option called “Archive the artifacts”. You type which files to keep, using a simple pattern. For example, you can say “all files ending in a certain extension inside the target folder”. Patterns use wildcards, where a star means “anything”, so one short pattern can match many files.

In a pipeline

In a pipeline, a step called archiveArtifacts does the same job. It is normally placed in the post section or at the end of a build stage, and it takes the same kind of file pattern. Because the pipeline is written as text in a Jenkinsfile, the choice of what to keep is versioned and reviewed together with the code.

Useful options

Where do archived artifacts show up?

After a build, the build’s page in Jenkins shows a list of its artifacts with download links. There is also a “last successful build” shortcut for each job, so people can always fetch the newest good artifact from a stable link. Teams can also download all artifacts of a build together as one compressed bundle.

Let us follow a single artifact from the moment code changes to the moment it reaches users.

sequenceDiagram
  participant D as Developer
  participant J as Jenkins Controller
  participant A as Build Agent
  participant R as Artifact Repository
  participant S as Staging Server
  participant P as Production Server
  D->>J: Push commit triggers build
  J->>A: Assign build
  A->>A: Compile, test, package
  A->>J: Archive reports and package
  A->>R: Upload package with version label
  J->>S: Deploy same package from repository
  S-->>J: Tests pass in staging
  J->>P: Deploy same package after approval

An important idea: immutability

Once an artifact is published with a version label, it should never be changed. If version 2.4.1 is out in the world and someone quietly replaces the file behind that label, nobody can trust what “2.4.1” means anymore. If a fix is needed, publish a new version, such as 2.4.2. This rule is called immutability, meaning “cannot be changed”, and it is one of the most valuable habits in artifact management.

Beginners often ask: “I built a file in one stage. How do I use it in the next?” The answer depends on where the next stage runs.

When two stages run on the same agent, they share one workspace, so a file created earlier is simply still there. No special step is needed.

When stages run on different agents, each agent has its own separate workspace, and files do not travel by themselves. Jenkins offers two tools to help.

flowchart LR
  B["Build Stage on Agent 1"] -->|"stash"| BOX[("Temporary Box on Controller")]
  BOX -->|"unstash"| T["Test Stage on Agent 2"]
  B -->|"archive"| KEEP[("Kept with the Build")]
  B -->|"upload"| REPO[("Artifact Repository")]
  REPO -->|"download by version"| D["Deploy Stage on Agent 3"]

Jenkins can keep artifacts, but it was not designed to be a full warehouse. Dedicated repositories do that job much better.

An artifact repository is a specialized server that stores finished packages, organizes them by name and version, controls who may read or write them, and keeps them safely for years. Popular examples include Nexus Repository, JFrog Artifactory, cloud storage services, and container registries for container images.

Why not just keep everything in Jenkins?

Kinds of repositories

A pile of files with names like final, final2, and really-final is a nightmare. Good naming and versioning prevent it.

Every artifact should carry a version, a label that tells you which edition it is. A very common style is semantic versioning, which uses three numbers separated by dots, such as 2.4.1. The first number changes for big, possibly breaking changes, the second for new features, and the third for small fixes. The pattern helps everyone guess how risky an upgrade is.

What to put in the name and label

• The project name, so you know what it is.
• The version number, so you know which edition.
• The build number or commit identity, so you can trace it back to the exact build and code.
• The type or target, such as the operating system it is for.

Two kinds of builds

Many teams separate snapshot artifacts from release artifacts. A snapshot is a work-in-progress build, made from ongoing development, which can be replaced by newer snapshots. A release is a final, blessed build, published once and never changed. Repositories often have separate areas for the two, with stricter rules for releases.

Jenkins can remember the fingerprint of a file, so that it can answer questions like “which build made this?” and “where was it used?”

A checksum is a short code calculated from the exact contents of a file. Even a tiny change to the file produces a totally different checksum. Jenkins can record this fingerprint when it archives a file. Later, when another job downloads or uses that file, Jenkins can record that use too.

This creates a trail. If you find a mysterious file running in production, you can look up its fingerprint in Jenkins and learn which job and build produced it, and which other builds used it. It is like the serial number on a product that lets a manufacturer trace it back to the factory line and the batch of parts.

Traceability from code to production

A complete chain looks like this: a commit identifies the code, the build records that commit, the artifact carries the build’s fingerprint and version, and the deployment records which artifact went to which environment. With this chain, the question “What code is running in production right now?” has a clear, quick answer.

flowchart LR
  C["Commit"] --> B["Build Number"]
  B --> A["Artifact with Version and Fingerprint"]
  A --> R["Repository Entry"]
  R --> D1["Deployed to Staging"]
  R --> D2["Deployed to Production"]
  D2 --> Q{"Question: which code is live?"}
  Q -->|"follow the chain back"| C

Artifacts pile up. Without a cleanup plan, they slowly eat all the disk space.

Every build that archives artifacts adds more files. A job that runs fifty times a day, each time saving a big package, can fill a disk in weeks. When the controller’s disk is full, Jenkins can slow down or stop, which stops every team.

Discard old builds

The job configuration has a “discard old builds” option. You can keep builds for a number of days, or only a certain number of the newest builds. There is also a separate limit for how many builds keep their artifacts, so you can keep the build history and logs for a long time while deleting the heavy files sooner. That is a clever way to save space while keeping the story of what happened.

Retention in the repository

Artifact repositories have their own cleanup rules. A common policy is to delete old snapshots aggressively, for example keeping only the last ten, while keeping released versions for years, since customers may still run them. The best policy depends on your legal and business needs, for example how long you must be able to reproduce a shipped version.

Moving files around costs time and network effort. Smart habits keep it cheap.

At large scale, remember that many builds times big files equals a lot of network traffic. A company with hundreds of builds per hour, each uploading a package of several hundred megabytes, needs storage and network capacity to match. Measure how long the archive and upload steps take, and watch for slow growth.

What if a disk breaks, a server fails, or an upload gets cut halfway? Good design expects trouble.

An artifact is what actually runs on your servers and in your customers’ hands. If it is tampered with, the damage can be huge.

Threats to think about

• Tampering. An attacker swaps a good package for a harmful one somewhere between build and deployment.
• Leaked secrets. A password or key accidentally ends up inside an archived file, such as a log or configuration bundle.
• Vulnerable ingredients. The package contains an outside library with a known security hole.
• Unauthorized access. The wrong person downloads, changes, or deletes packages.

Protective habits

A special caution about viewing artifacts in the browser

Jenkins protects its users by applying strict safety rules when someone opens an archived file directly in the browser. For example, a web page saved as an artifact may show with its scripts blocked, because a build could produce harmful pages. If you need to publish reports as viewable pages, use the proper plugin for that or a separate hosting place, rather than loosening the safety rules for the whole server.

A healthy artifact process is watched like a patient in a clinic.

Jenkins shows the artifact list and sizes on each build’s page, and its console output records the archive and upload steps. Many teams also send numbers to tools such as Prometheus and view them on Grafana dashboards, and keep logs in a central search system. Repository products usually show their own usage reports, download counts, and cleanup history.

Keeping artifacts is essential, but every design choice has a price.

Choosing where to keep artifacts

A pattern is a proven habit. An anti-pattern is a tempting shortcut that usually hurts later.

Patterns that work

Anti-patterns to avoid

These habits separate a calm delivery process from a chaotic one.

Best practices

1. Build once and promote the same artifact through all environments.
2. Give every artifact a clear version, ideally semantic, plus the build number and commit identity for tracing.
3. Never overwrite a released version. Publish a new one.
4. Archive only what people need, using careful file patterns and excludes.
5. Publish deliverables to an artifact repository, and keep short-lived reports in Jenkins.
6. Turn on fingerprints for important files to make tracing easy.
7. Verify checksums after upload and download, and sign important packages.
8. Set retention rules in both Jenkins and the repository so storage never fills up.
9. Protect release builds from automatic cleanup by keeping them in the repository.
10. Keep secrets out of artifacts, and check logs and bundles for accidental leaks.
11. Scan packages for known weaknesses before publishing.
12. Use least privilege so builds can write only where they must and deployments can only read.
13. Monitor size, speed, and disk use, and set alerts before problems become outages.
14. Back up the controller’s storage and the repository, and practice restoring.

Common mistakes

Build artifacts sit at the center of nearly every real delivery pipeline. Here are common ways teams use them.

A typical growth story

A small team begins by archiving one program file in Jenkins and downloading it by hand. Soon the disk fills, so they set retention limits. Then a release goes wrong and nobody can find the old version, so they adopt an artifact repository and semantic versions. Later they add fingerprints and commit information for tracing, followed by security scans and signing before publishing. At each step the change was small, and the team never had to start over.

You started in a bakery holding a loaf of bread and finished with a full picture of how Jenkins produces, keeps, and shares the results of its work.