Reproducible build artifacts

Build & Artifact Management

A reliable release pipeline guarantees that given the same commit SHA, lockfile, and toolchain versions, the build produces a predictable, verifiable artifact free of local machine state or baked-in environment secrets.

Pinning All Build Inputs

Eliminate "works on my runner, breaks next week" drift by pinning every layer of the build environment:

1. Toolchain & OS base versions:
   • Pin Node/Python/Go/PHP/Java/Rust versions explicitly in both local version files (.nvmrc, .node-version, rust-toolchain.toml, package.json#engines) and CI/Dockerfile base images (node:22.14.0-bookworm-slim@sha256:... rather than floating node:latest).
2. Frozen dependency installation:
   • Always install dependencies in CI and container builds using frozen lockfile flags (npm ci, pnpm install --frozen-lockfile, yarn install --immutable, composer install --no-interaction --no-progress --prefer-dist, cargo build --locked).
   • If the lockfile is out of sync with the manifest, fail the build immediately rather than silently resolving newer transitive versions during a release.
3. Separate build-time vs. runtime dependencies:
   • Prune devDependencies or use multi-stage builds so compilers, test runners, and local CLI tools do not bloat the shipped runtime artifact or widen its vulnerability surface.

Strict Separation of Build, Config & Secrets

• Never bake environment-specific secrets or URLs into a shared artifact:
  • Server-side applications must read environment configuration and secrets at runtime startup (and validate them immediately with a strict schema check on boot).
  • For static/SPA frontend bundles where VITE_* / NEXT_PUBLIC_* variables are inlined at build time, never pass private keys into public env vars, and either inject runtime configuration via a small non-cached /config.json / HTML meta payload or explicitly document per-environment bundle builds.
• Verify .dockerignore and package allowlists (files in package.json):
  • Exclude .git, .env*, node_modules, test fixtures, coverage reports, and local build caches from build contexts so local secrets or gigabytes of junk never enter an image layer or tarball.

Cache Discipline: Speed Without Corruption

CI and Docker layer caches exist only to accelerate reproducible steps—never to mask missing build inputs:

• Bind cache keys to exact input hashes: Key dependency caches by OS + arch + runtime_version + hashFiles('<lockfile>'). Key build caches (e.g., Turbo/Nx/Vite/Gradle/Cargo) by source + config + lockfile hashes.
• Order Dockerfile layers from least-frequently changed to most-frequently changed: Copy only package.json + lockfile and run npm ci before COPY src/ ./ so source code edits do not invalidate the dependency installation layer.
• Immutable artifact identification: Tag every built artifact with both its semantic/release version and its immutable git SHA (app:1.4.2, app:sha-9f8a7b6), and record the registry digest (sha256:...) in the release log.