Build outputs and binary artefacts — what gets uploaded, the upload limits, the retention

A build output is the artifact a CI job produces when it compiles, packs, or signs a piece of software. The artifact is the binary the build produced, not the source the build compiled from. This distinction is the production rule: an artifact is the output of an execution, not the input to it. The downstream job or the downstream deployment must consume the artifact that was uploaded, not rebuild the same artifact from source.

What gets uploaded

A build output is one of:

• A compiled binary. A Go binary, a Rust crate, a C/C++ executable, a JVM .jar or .war. The artifact is the file the compiler produced.
• A packed archive. A tarball (tar.gz), a zip, a .tgz, a packaged directory. The artifact is the archive, which may contain many binaries plus configuration.
• A signed bundle. A Sigstore bundle, a cosign signature, a gpg --sign output, an SBOM (SPDX or CycloneDX). The artifact is the signed bytes; the signature proves provenance.
• A language-specific package. A pip wheel, an npm tarball, a gem package, a maven artifact, a composer archive.

In every case, the rule is the same: the artifact is the bytes the build produced, identified by the path the build wrote them to.

- name: Build
  run: go build -o app ./cmd/app
- name: Upload binary
  uses: actions/upload-artifact@v4
  with:
    name: app-binary
    path: app
    retention-days: 90
- name: Compute digest
  run: sha256sum app > app.sha256
- name: Upload digest
  uses: actions/upload-artifact@v4
  with:
    name: app-digest
    path: app.sha256
    retention-days: 90

The second upload-artifact step uploads the digest alongside the binary. The downstream deployer can verify the binary against the digest before deploying.

The upload limits

The artifact store enforces two limits every production pipeline must respect:

• Per-artifact size limit. The vendor enforces a maximum size for a single artifact. On GitHub Actions, the limit is 10 GB per artifact. Larger artifacts must be split, archived externally, or stored in an OCI registry.
• Per-run storage budget. The vendor enforces a maximum total size across all artifacts in a run. The total budget is bounded per workflow run; a workflow that uploads dozens of large binaries can exceed the budget.

Both limits are vendor policy. The production rule is to read the policy for the vendor the team uses and design the artifact upload within the budget. A pipeline that routinely uploads binaries close to the limit is a pipeline that will fail at the worst time.

flowchart LR
    A["go build -o app"] --> B["app binary"]
    A --> C["app.sha256"]
    B --> D["upload-artifact\nname: app-binary\npath: app"]
    C --> E["upload-artifact\nname: app-digest\npath: app.sha256"]
    D --> F["Artifact store"]
    E --> F
    F --> G["download-artifact in deploy job"]
    F --> H["Human review in PR UI"]

The retention window

Binary artifacts are large. The retention window is the cost multiplier: a 500 MB binary retained for 365 days costs 30x more than the same binary retained for 12 days. The production rule is to set retention explicitly based on the audit and rollback window:

• Audit window. How long must the binary be retrievable for audit purposes? A typical value is 90 days for application builds and 365 days for compliance-bound binaries.
• Rollback window. How long must the binary be retrievable for emergency rollback? A typical value is 30 days; the rollback window is usually shorter than the audit window.

The shorter window wins for routine retention. The longer window is met by archival to long-term storage (S3, internal artifact registry, OCI registry) outside the artifact store.

Production discipline

1. Upload the binary the build produced. Never rebuild from source in a downstream job.
2. Upload the digest alongside the binary. The downstream verifier checks the digest before deploy.
3. Set retention-days explicitly. The default is per-vendor policy; the production rule is the audit window the team needs.
4. Archive to long-term storage for compliance windows longer than the artifact store’s maximum. The artifact store is not a compliance archive.
5. Pin the build inputs for reproducibility. A binary without pinned inputs is a binary that cannot be rebuilt.

Cross-course references

• Git, CI/CD & GitOps — Part XLIV-01 (What an artifact is) covers the artifact model and the audit invariant.
• Git, CI/CD & GitOps — Part XLIV-03 (Terraform plans as artifacts) applies the same pattern to plan files.
• Terraform for Production Sysadmins — Parts IX-XII (State) covers reproducibility of Terraform state and the audit invariant.

Quiz