zero gravitySOLUTIONS
← All insightsCI/CD & DELIVERY / BUILD EVIDENCE COMPARISON

Caches and release artifacts have different jobs

QUICK ANSWER

A cache accelerates work that can be reproduced; a release artifact identifies the output selected for deployment. Make builds correct without a cache, tie cache validity to inputs, and promote an immutable artifact with verified provenance rather than rebuilding or trusting a convenient filename.

Inside this article 5 sections

A dependency cache and a release artifact may both contain files, but they answer different questions. The cache asks whether previous work can safely save time. The release artifact asks exactly which output was built, checked, and approved for deployment. Treating one as the other weakens both reproducibility and release evidence.

For a SaaS application, the package-manager download cache can disappear without changing the intended result. The container image selected for production cannot be replaced casually by a fresh build from a branch name. Its identity connects the deployed software to the checks that justified the release.

Define cache validity from actual inputs

A cache key should represent the inputs that determine whether the cached content remains usable. For downloaded dependencies, that usually includes the package manager, relevant runtime or platform distinctions, and lockfile identity. For compiled output, the input set is broader: source, compiler configuration, toolchain, and build-time environment can all matter.

Do not cache a whole workspace simply because it is easy. That can retain generated files, credentials, stale configuration, and outputs whose validity is unclear. Select narrow paths with a documented regeneration process. A cache miss should cost time, not correctness.

Cache versus artifact decision sheet
PropertyDependency or build cacheRelease artifact
PurposeAvoid repeatable workIdentify a selected deployable output
Missing dataRegenerate through the normal buildStop promotion or recover the exact artifact
IdentityKey derived from validity inputsImmutable identifier and content digest
TrustTreat restored content according to source and scopeVerify builder, revision, run, and integrity
RetentionPerformance policyRelease and rollback policy
A cached file is not automatically an approved release. A release artifact should remain identifiable independently of cache availability.

Fallback restore keys need special care. A partially matching dependency cache may be useful if the package manager still installs and verifies the exact lockfile state afterward. It is not sufficient reason to skip installation or validation. For compiled output, a broad fallback can be incorrect unless the build system verifies every affected input.

Make a clean-cache build a supported path

Run the normal build with no restored cache periodically and after changes to caching rules. Compare the required tests and output identity where the build is intended to be reproducible. Differences may reveal undeclared inputs, generated files checked into a cache, or network-dependent resolution that bypasses the lockfile.

Distinguish deterministic output from functional equivalence. Timestamps or embedded build identifiers can change bytes even when behavior is unchanged. If exact reproducibility is a requirement, eliminate or control those sources deliberately. Otherwise, document which properties are compared and avoid claiming byte-for-byte reproduction.

Illustrative build evidence record:
source_revision: reviewed immutable commit
lockfile_digest: digest of dependency resolution input
toolchain: declared runtime and package-manager versions
build_run: repository and run identifier
artifact_digest: digest of the produced deployable output
checks: exact reports associated with this run

This record is evidence, not a command. Store it with the artifact or release metadata and verify it before promotion. A source revision alone does not identify a unique output if build-time inputs differ, so include the configuration that materially affects the binary.

Treat cache and artifact provenance separately

Untrusted pull-request jobs can produce convincing-looking reports and files. A privileged job must verify the expected repository, workflow, event, run, and revision before consuming evidence, then validate the content itself. A filename such as release.zip does not establish that the file came from an authorized release build.

Do not put secrets in caches or artifacts. Their access and retention behavior can differ from job secrets, and downloaded diagnostic bundles may reach a wider audience. Use synthetic fixtures and references to protected resources instead of saving entire environment files or credential-bearing workspaces.

Review who can write or influence a cache used by privileged builds. Restored executable content should not silently cross from an untrusted job into a deployment context. Where the trust model is unclear, regenerate the relevant content from reviewed inputs rather than depending on a shared cache for correctness.

Build once and promote the selected output

After a trusted build and its required checks, record the artifact's immutable identity. Deploy that same output to the next environment when the architecture permits. Rebuilding from the same branch or tag can resolve different dependencies, embed different public configuration, or pick up a moved reference.

Separate environment configuration from build output deliberately. Some frameworks inline public values at build time, so one artifact cannot necessarily be promoted unchanged without an explicit runtime configuration design. Record that limitation rather than claiming build-once semantics while quietly rebuilding for each environment.

Verify integrity when downloading or copying the artifact. A digest comparison establishes content identity, while provenance establishes how that content was produced. Neither replaces the other. If an artifact is copied between registries or accounts, confirm the destination identity and target architecture before updating the service.

Keep cache-hit reporting distinct from test success in the workflow summary. An engineer should be able to tell whether dependency files were restored, whether installation verified the lockfile, and whether the required application checks actually ran. A fast green job is not useful evidence if its optimization skipped the operation it was supposed to verify.

Retain enough evidence to roll back

Keep approved artifacts and their configuration references for the rollback period. An expiring workflow artifact may be suitable for a short-lived test report but insufficient as the only copy of a production release. Choose a release store with retention aligned to operations.

Rehearse a cache outage and a missing-artifact failure separately. The first should regenerate work; the second should stop promotion rather than substitute latest. The delivery acceptance guide establishes release evidence, and reproducible experiment guidance explains controlled inputs. Delivery implementation should make both acceleration and artifact identity explicit.

FROM INSIGHT TO ACTIONCustom software development

Make build outputs traceable across environments.

We can implement valid cache keys, clean-build checks, and immutable artifact promotion tied to reviewed source.

Explore software developmentDiscuss your build

Start with your goals.
We’ll work through the next step together.