Artifacts, stash/unstash, archiveArtifacts, Fingerprints, Test Reports, Coverage, and Build Evidence: Concepts, Architecture, and Mental Model

1. The practical problem: a green build is not an evidence strategy

Earlier chapters separated controller state, Pipeline state, agent workspaces, and external side effects. This chapter adds another boundary: build evidence. A compiler may create a ZIP in an agent workspace, a test tool may write XML, and a coverage tool may create a report, but those files are not automatically durable just because a stage succeeded.

Operators need to answer concrete questions later: Which source revision produced this binary? Which build archived it? What digest did that build record? Which test report was ingested? Was the file merely passed to a later stage, or retained after the run? Did a downstream consumer use the exact same bytes? Those questions require different Jenkins mechanisms.

2. Mental model: output → transfer/retention decision → evidence

An agent first creates files in a workspace. From there you choose the lifecycle deliberately. A small file needed later in the same Pipeline run can be stashed and later unstashed into another workspace. A file that must remain attached to the build can be archived. A test or coverage XML file can be parsed into a typed Jenkins report. A file can additionally be fingerprinted so Jenkins can correlate production and use across builds. Long-lived release binaries usually belong in a repository manager rather than in Jenkins alone.

flowchart TD
 A[Exact SCM revision] --> B[Build on agent workspace]
 B --> C[Output file + SHA-256]
 C --> D{What lifecycle is required?}
 D -->|same run transfer| E[stash]
 E --> F[unstash on another workspace]
 D -->|retain with build| G[archiveArtifacts]
 G --> H[Build artifact record]
 G --> I[Jenkins fingerprint record]
 C --> J[JUnit / coverage XML]
 J --> K[Typed report ingestion]
 C --> L[External artifact repository]
 H --> M[Producer job + build + source SHA]
 I --> M
 K --> M
 L --> N[External coordinates + digest + repository evidence]

The arrows are causal, not decorative. The source revision identifies what was built; the workspace produces bytes; Jenkins either transfers, archives, parses, or fingerprints evidence; external publication has its own acceptance state and must be verified separately.

3. Define the states before changing them

4. stash/unstash: temporary transfer, not a release store

The Pipeline: Basic Steps documentation defines stash as a way to save files for later use on another node or workspace in the same Pipeline run. By default, stashes are deleted when the run completes. Declarative preserveStashes can retain a bounded number of completed-run stashes specifically for restart-from-stage use, but that still does not turn stash into a general artifact repository.

Stash also has a performance boundary. Files are packaged for transfer; large payloads can consume significant controller resources unless an external Artifact Manager redirects the data path. For large or release-critical objects, prefer a proper artifact repository or purpose-built transfer mechanism.

stage('Package') {
  node('lab-linux-a') {
    sh 'tar -czf out/app.tgz app/'
    stash name: 'package-for-test', includes: 'out/app.tgz'
  }
}
stage('Verify elsewhere') {
  node('lab-linux-b') {
    deleteDir()
    unstash 'package-for-test'
    sh 'sha256sum out/app.tgz'
  }
}

5. archiveArtifacts: retain bytes with the producing build

archiveArtifacts copies matching workspace files into the configured Jenkins artifact manager and associates them with the build. The default artifact manager stores them under controller-managed build state; an installed external Artifact Manager can transparently move storage elsewhere. Either way, the build is the logical owner.

archiveArtifacts artifacts: 'out/*.tgz,out/SHA256SUMS', fingerprint: true

Archive only intended outputs. A broad pattern such as **/* can capture source trees, caches, secret files, debug dumps, or enormous directories. Treat the include/exclude pattern as a data-classification boundary.

6. Fingerprints: relationship tracking, not authenticity

Jenkins fingerprints use an MD5 checksum as a lookup key to track where files were produced and consumed. This is valuable for answering “which build used the file produced by build 42?” It is not a modern authenticity or integrity guarantee. MD5 is not appropriate as a cryptographic provenance mechanism.

For integrity evidence, also calculate a modern digest such as SHA-256 and archive the checksum manifest. For stronger supply-chain provenance, use signatures/attestations and repository-side immutable coordinates in later release workflows. Keep the Jenkins fingerprint because it solves a different problem: build relationship discovery.

7. Typed reports are more useful than raw XML alone

A raw reports/junit.xml file is inspectable evidence, but the JUnit plugin parses it into test-case state, counts, trends, and build annotations. Coverage behaves similarly: a maintained Coverage plugin can parse supported formats and create coverage metrics and quality gates. Parsing is a separate state from file creation—“the XML exists” does not prove “Jenkins ingested it.”

8. Retention is part of architecture

Retaining every artifact, log, source file, and report forever turns Jenkins storage into an unbounded operational liability. Conversely, deleting evidence too aggressively can make incidents or audits impossible to reconstruct. Choose retention by evidence class: short-lived transfer data, CI diagnostics, release candidates, release artifacts, and compliance records have different lifetimes.

When release retention exceeds what Jenkins should own, publish the exact already-verified bytes to an external repository and retain the external coordinates and digest in Jenkins. Promotion should move or reclassify those same bytes, not silently rebuild from the branch name.

9. Read-only inspection checklist

• Record job full name, build number/URL, exact source SHA and Jenkinsfile revision.
• Record agent/node label, workspace path, artifact filename/path, size and SHA-256.
• List configured build retention before assuming an artifact will remain forever.
• Inspect stash names only as same-run transfer evidence; do not treat them as external release coordinates.
• Record JUnit and Coverage plugin versions before interpreting typed results.
• Inspect fingerprint relationships, but label them correctly as Jenkins dependency tracking.
• If an external repository is involved, verify its coordinates and digest independently from Jenkins.

10. Common wrong approaches

Knowledge check

Official references and version notes

• Pipeline: Basic Steps reference — current stash/unstash semantics and guidance for cross-stage transfer.
• Running Pipelines — Declarative stage restart and preserveStashes behavior.
• Recording tests and artifacts — archiveArtifacts, fingerprinting, and JUnit publishing patterns.
• Jenkins fingerprints — dependency/use tracking and the MD5-based fingerprint record.
• JUnit plugin — maintained test-result ingestion and build/test history.
• Coverage plugin — maintained coverage ingestion, quality gates, and source-retention choices.
• Coverage Pipeline step reference — current recordCoverage parameters and supported parsers.
• Artifact Manager on S3 plugin — optional example of external artifact-manager integration; not required by the labs.
• Jenkins LTS changelog — current LTS and tested Java configurations.