# What Is a Build Artifact? — Definition, Uses and the Document Mistake

Canonical: https://commareports.com/glossary/build-artifact
Published: 2026-09-11

> A build artifact is a file a CI job produces and stores for later retrieval. What belongs in artifact storage, what doesn't, and why storing a report there gives it an expiry date.

# Build artifact

**A build artifact is a file or directory produced by a CI job and
stored by the CI system for later retrieval — by a downstream job, or by
a person clicking through the build UI.** Compiled binaries, packaged
installers, SBOMs, test result XML, coverage data and generated HTML
reports are all routinely stored this way.

## Artifact, cache, or package

The three get conflated, and the distinction decides how each is billed
and expired:

| Kind         | Missing means                                        | Lifetime                     |
| ------------ | ---------------------------------------------------- | ---------------------------- |
| **Cache**    | Slower build, same result                            | Evicted by size or idle time |
| **Artifact** | Downstream job fails, or a human has nothing to open | Retention policy             |
| **Package**  | A published dependency is gone                       | Immutable, usually forever   |

Most teams push a report into the middle row because that is the row the
CI provider offers, then discover it behaves like a cache.

## Where artifact storage is the right answer

- Build outputs a later job downloads — compiled assets, container
  contexts, test fixtures.
- Machine-readable results the pipeline itself consumes:
  [JUnit XML](/glossary/junit-xml), [SARIF](/glossary/sarif) uploaded to
  code scanning, lcov sent to a coverage service.
- Large binaries nobody reads, kept just long enough to debug a failure.

Here, short retention is a feature. Keeping a 400 MB build context for
90 days is a bill, not a safeguard.

## Where it is the wrong answer

A test report, a coverage tree, a security scan, a benchmark — anything
a person opens and later cites — fails as an artifact for three separate
reasons:

1. **It expires.** Under a policy you frequently do not control
   ([artifact retention](/glossary/artifact-retention)).
2. **It does not render.** GitHub Actions serves artifacts as a zip;
   there is no viewer, so the "report link" in the PR is a download
   ([why it is always a zip](/fix/github-actions-artifact-html-not-viewable)).
3. **It is gated on repo access.** A client, an auditor or a contractor
   who cannot authenticate to your CI cannot open it at all.

## Splitting the two jobs

Keep uploading artifacts for machines. Publish documents to an address
you own:

```bash
# every run, against a report id stored as a CI variable
curl -sS -X PATCH "https://commareports.com/api/v1/reports/$COMMA_REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data @<(jq -Rs '{html: .}' htmlcov/index.html)
```

One id, one URL, for the life of the project. Each run appends a
revision rather than overwriting, so any two builds can be diffed and
the link in a year-old incident doc still resolves. Per-provider setup is
in [publish from CI](/docs/ci).

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited
revision history. Nothing expires.

**[Create a permanent report URL →](https://commareports.com/)**

### Related

- [Artifact retention](/glossary/artifact-retention) · [The CI artifact link expired](/fix/ci-artifact-expired)
- [Publish from CI](/ci) · [GitHub Actions HTML reports](/ci/github-actions-html-report)
- [HTML report](/glossary/html-report) · [Glossary](/glossary)