Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 40 ยท Build, Test and Package

Artifacts, Stash and Fingerprints

Keep and move build output in Jenkins: archiveArtifacts, stash and unstash, copyArtifacts, fingerprints, artifact repositories and build retention.

A build produces files that matter: a JAR, a Docker image tarball, a website bundle, a test report. Workspaces are temporary and can be wiped or reused, so you need deliberate ways to keep a file for later, hand it to another stage, or give it to another job. Jenkins offers three tools for this, and they solve different problems: artifacts are kept after the build, stash is a temporary hand-off within one build, and fingerprints track where a file has been used.

This lesson explains each, when to use an artifact repository instead, and how to control disk usage with retention rules. The real Jenkins cannot run on this site, so the Pipeline code is read-only. The runnable examples are JavaScript stand-ins that model storage and hand-off, and they say clearly where the stand-in differs from reality.

Three tools, three jobs

Archive Keep files with the build for later.
Stash Pass files between stages and agents.
Fingerprint Track which builds used a file.

Only archived files survive after the build.

1 / 2

Archiving artifacts

archiveArtifacts copies files from the workspace to the controller's storage for this build. They then appear on the build page for download, and stay until the build is discarded.

GROOVY
pipeline {
  agent any
  stages {
    stage('Package') {
      steps {
        sh './mvnw -B -ntp package -DskipTests'
      }
      post {
        success {
          archiveArtifacts artifacts: 'target/*.jar',
                           fingerprint: true,
                           onlyIfSuccessful: true
        }
      }
    }
  }
}

The artifacts value is an Ant-style pattern: * matches within a folder and ** matches across folders, so dist/** takes everything under dist. Useful options include allowEmptyArchive (do not fail if nothing matches), excludes, and fingerprint. By default, a pattern that matches nothing fails the step, which is helpful: it flags the case where your package step quietly produced nothing.

Archive things that people or later jobs will genuinely need: release packages, installers, reports, coverage output. Do not archive the whole workspace or node_modules; that fills the disk and slows every build. Archived files are stored on the controller, which is one more reason to keep them modest, or to push large ones to a repository (see below).

Stash and unstash

Archiving is for keeping. When you only need to pass files from one stage to another, especially when the stages run on different agents, use stash and unstash:

GROOVY
pipeline {
  agent none
  stages {
    stage('Build') {
      agent { label 'linux' }
      steps {
        sh 'npm ci && npm run build'
        stash name: 'dist', includes: 'dist/**'
      }
    }
    stage('Test on Windows') {
      agent { label 'windows' }
      steps {
        unstash 'dist'
        bat 'dir dist'
      }
    }
  }
}

Two rules decide when stash is right:

  • A stash exists only for the life of the build. When the build ends, it is gone, so use it for hand-offs, not storage.
  • Stash is meant for small to moderate amounts of data. Moving gigabytes through the controller is slow. For large files, use an artifact repository or a shared volume.

Also remember that file permissions and symbolic links can be affected by the transfer, and that in Declarative a stage with agent none at the top needs its own agent to do any file work.

Artifacts from other jobs: copyArtifacts

A downstream job sometimes needs the output of an upstream job, for example a deploy job that deploys the package built by a build job. The Copy Artifact plugin provides a step:

GROOVY
copyArtifacts(
  projectName: 'app-build/main',
  selector: lastSuccessful(),
  filter: '*.jar',
  fingerprintArtifacts: true
)

The selector chooses which build: the last successful one, a specific build number, or the build that triggered the current one. Pinning an exact build number is more reproducible ("deploy build 218") than "the latest", which can change between the moment you approve and the moment you deploy. For serious delivery pipelines, many teams stop passing files between jobs and publish to a repository instead, as described below.

Fingerprints

A fingerprint is a checksum (an MD5 hash) of a file, recorded by Jenkins. When several builds touch a file with the same checksum, Jenkins links them. That lets you answer practical questions: "Which build produced this JAR?", "Which deployment jobs used it?", "Which of our applications use library build 77?" You turn it on with fingerprint: true on archiveArtifacts, or with the fingerprint step for files you use but did not produce:

GROOVY
fingerprint 'libs/shared-core-2.3.1.jar'

On the Jenkins UI, each fingerprint has a page listing every build that recorded it. Fingerprints are for traceability, not for security: an MD5 hash is not a modern integrity guarantee, so for tamper protection use signatures and published SHA-256 checksums in your artifact repository.

Artifact repositories

The Jenkins artifact store is convenient but is not a package repository. It has no versioning scheme, no dependency resolution and no clean way to serve artifacts to other tools. When a file has a life beyond one build, publish it to a real repository:

  • Maven repositories for JARs, npm registries for Node packages, PyPI-style indexes for Python wheels, container registries for images (see Docker Agents and Building Images).
  • Products such as Nexus and Artifactory host several formats at once.

The build still archives a small copy (a report, a manifest of what was published) for convenience, while the repository stores the real artifact under a version number. Deploy jobs then ask the repository for "version 1.4.2", which is much more robust than "the last successful build of that job".

Retention with buildDiscarder

Left alone, Jenkins keeps every build and every archived file forever. Set a policy per job:

GROOVY
options {
  buildDiscarder(logRotator(
    numToKeepStr: '30',          // keep the last 30 builds
    daysToKeepStr: '60',         // ...no older than 60 days
    artifactNumToKeepStr: '5'    // keep artifacts for only the last 5
  ))
}

Keeping logs and results longer than artifacts is a sensible split: logs are small and tell the history, while artifacts are large. You can mark a particular build as "keep this build forever" (for example, the one you released), and the discarder will skip it. Revisit Jenkins Architecture for how build records are laid out in JENKINS_HOME.

A stand-in artifact store

The model below keeps builds in memory. Each build has files; archiving copies files into a permanent area keyed by build number; stash puts files into a temporary area that is wiped when the build ends; a retention rule removes artifacts of old builds. The "files" are just names and sizes. The real implementation stores files on disk and transfers them over the agent connection, but the lifetimes are the same.

JS A stand-in archive, stash and retention

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Only the JARs were archived, never node_modules, and after retention the two newest builds keep their artifacts. All stashes were already gone when their builds finished, which is what makes them a hand-off tool and not storage.

A stand-in fingerprint index

The last example computes a content hash (a simple stand-in for the MD5 Jenkins records) for each file that builds touch, then answers "which builds produced or used this file?". The file contents and builds are made up.

JS A stand-in fingerprint index

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The index links the build that produced the library with every build that used exactly those bytes, which is what Jenkins shows on a fingerprint page.

Never archive secrets. Files in archiveArtifacts are downloadable by anyone who can read the build, so scan for .env files, key files and credentials before the archive step. See Credentials and Secrets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How long does a stash live?

    A stash is a hand-off within a single build. When the build finishes, it is deleted. Use archiveArtifacts to keep files.
  2. 2. Which step is most suitable for moving a small build output from a Linux stage to a Windows stage in the same build?

    stash and unstash transfer files between stages, including stages on different agents, for the life of the build.
  3. 3. What does a fingerprint let you do?

    A fingerprint is a checksum recorded by Jenkins; matching checksums link the builds that touched the same file. It is for traceability, not security.
  4. 4. Why use an artifact repository such as Nexus or Artifactory?

    Repositories store versioned packages and serve them to other builds and deployments, which the Jenkins artifact store is not designed for.

Summary

  • archiveArtifacts keeps files with a build; patterns use * and **, and a pattern that matches nothing fails the step unless you allow an empty archive.
  • stash and unstash hand files between stages and agents for the life of one build.
  • copyArtifacts fetches output of another job; pin an exact build when reproducibility matters.
  • Fingerprints record checksums so you can trace where a file was produced and used.
  • Real, versioned artifacts belong in an artifact repository.
  • Use buildDiscarder with separate limits for builds and artifacts to protect the disk.

Next, run builds inside containers in Docker Agents and Building Images.