Jenkins / Evidence, reuse, and authority / Lesson 8

Stash, archives, and durable candidate identity

Move files between workspace scopes while choosing retention and integrity deliberately.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish stash transfer from retained build artifacts and release storage.
Explain why fingerprints and friendly filenames are not sufficient security identity.

Choose a file mechanism by its promise

A workspace holds temporary execution state. stash can save selected files for use elsewhere in the same Pipeline run, while archiveArtifacts retains selected build outputs according to configured storage and retention. A release repository may need stronger distribution and lifecycle guarantees than either mechanism alone. Parcel’s compiled package, test report, and dependency cache have different consumers and retention horizons. Decide what must survive agent loss, run completion, and later recovery. Do not let convenience choose the only copy of an approved package.

Declare producer and consumer boundaries

A stash name identifies a selected file set within the intended run context. unstash restores it into the current workspace, so a consumer still needs an allocated file context and correct paths. The fragment below illustrates transfer without assuming both stages share a node. It is not executed and requires the producer to have created dist/parcel.zip first. Stash availability across restarted stages or retained builds depends on configured options and plugins; do not generalize same-run transfer into permanent release storage.

groovy A same-run file transfer illustration

// Producer workspace already contains the declared package.
stash name: "compiled-parcel", includes: "dist/parcel.zip"
// Later, in an allocated consumer workspace:
unstash "compiled-parcel"

This is a sequence of illustrative step fragments, not a complete Pipeline. No archive is created or restored. The comments describe separate workspace contexts that a real definition must provide.

Retain the right files with the right access

Artifact archiving selects files, not a complete trustworthy release by itself. Review patterns, empty-selection behavior, storage backend, access control, and build-discard policy. Fingerprinting supports Jenkins file-use tracking under its documented mechanism; do not present it as authenticated provenance or a replacement for a consumer’s cryptographic package verification. Avoid broad archive patterns that include temporary credential files, configuration dumps, or unrelated data. A retained package still needs source, producer, and approval relationships so consumers choose the intended output rather than the latest convenient file.

File movement has control-plane costs

Large stashes can impose compression and transfer work on the controller depending on artifact-manager support and configuration. Keep orchestration data small and use appropriate artifact storage for large outputs. No universal size threshold fits every installation, so inspect actual storage and transfer behavior with the platform owner. Increasing controller heap is not the first response to a poorly bounded file set. Separate dependency-download acceleration from release artifacts, and ensure losing a cache cannot erase the only retained candidate.

Compare declared bytes locally

The complete local model hashes a synthetic package payload and compares a modified payload with the expected digest. It demonstrates byte identity only; expected metadata generated in the same program is not authenticated provenance. A real consumer must obtain expected identity through a trusted release channel and verify the bytes actually downloaded. Retention, digest equality, and authorization are separate checks. A perfectly retained and correctly hashed candidate can still be the wrong revision or lack approval for the target environment.

python Compare synthetic package bytes

import hashlib
package = b"parcel-package-lab\n"
expected = hashlib.sha256(package).hexdigest()
print(hashlib.sha256(package).hexdigest() == expected)
print(hashlib.sha256(package + b"changed").hexdigest() == expected)

Expected output

True
False

No Jenkins fingerprint, stash, archive, filesystem package, or storage service is accessed. The expected hash is local teaching data rather than an independently trusted release record.

Common errors and fixes

A stash is the only retained rollback package.

Why it happens: Same-run transfer was mistaken for durable release storage.
How to fix it: Retain approved candidates under the required recovery lifecycle.
Prevent it next time: Review artifact retention against the rollback horizon.

An archive pattern includes bound credential files.

Why it happens: File selection is broader than the intended public evidence.
How to fix it: Remove the exposure and coordinate credential response with its owner.
Prevent it next time: Review archive and stash patterns alongside credential-binding scope.

A Jenkins fingerprint is called complete supply-chain verification.

Why it happens: Usage tracking was stretched into authenticated origin and policy approval.
How to fix it: Verify package identity and provenance through an appropriate trusted channel.
Prevent it next time: Document what each metadata mechanism proves and excludes.

Check your understanding

1. Can stage B assume an earlier stash is already present in its directory?

Show worked solution

No. The consumer must restore the declared stash in an appropriate workspace and know the restored paths. The name represents a transfer record, not automatic shared storage or a guarantee that the selected files were produced correctly.

2. Why retain packages longer than ordinary intermediate reports?