Build Artifacts

The plain-language idea

A pipeline is usually made of more than one job — build, test, deploy — and by default those jobs don't share a filesystem. Each one starts on a fresh runner with nothing on it. If your deploy job needs the production build, the naive approach is to just run the build again inside the deploy job. That works, but it means the thing you actually ship was never the thing your test job verified — it's a second, separately-produced build that merely should be identical.

An artifact is how you avoid that: one job builds the output, uploads it as a named artifact, and any later job in the same run can download that exact artifact — the same files, byte for byte, that already passed whatever came before. "Build once, deploy the same bytes everywhere" is the whole point. It also means a slow build step only runs once per pipeline run instead of once per job that needs its output.

See it in a real thing: build once, deploy the same artifact

This repo's own ci.yml doesn't split build and deploy into separate jobs — pnpm build is the last step of the single verify job, and deployment happens separately via Vercel's own GitHub integration. But the artifact pattern is exactly what you'd add if you wanted an explicit deploy job in the same workflow, rather than handing off to an external platform:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 11.5.0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - name: Upload production build
        uses: actions/upload-artifact@v4
        with:
          name: production-build
          path: .next
          retention-days: 1

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download production build
        uses: actions/download-artifact@v4
        with:
          name: production-build
          path: .next
      - name: Deploy
        run: ./scripts/deploy.sh

needs: build is what makes this work — it tells GitHub Actions the deploy job can't start until build finishes successfully, and it's what gives deploy something to download. Without needs, the two jobs would run in parallel and deploy would fail immediately with nothing to fetch. Notice deploy never runs pnpm install or pnpm build at all — it has no reason to; the artifact already contains everything the build step produced.

What people usually miss

Watch out

• An artifact is scoped to one workflow run, not shared across runs or branches. You can't upload an artifact on Monday and download it in Tuesday's run — for that you'd want a cache (which is explicitly designed to survive across runs) or a real package registry, not an artifact.
• Re-running the build in the deploy job isn't just wasteful, it's a correctness gap. Even with a fully deterministic build, "run the same command again" and "reuse the exact output that was already tested" are different guarantees — dependency resolution, environment drift, or a mid-run registry publish can make two builds of the "same" commit produce different bytes.
• path on upload and download doesn't have to match, but it's the easiest thing to get wrong. If build uploads from .next and deploy downloads to a different directory expecting the same structure, the deploy step fails on a missing file with an error that looks like a build problem, not an artifact-path mismatch.

The genealogy: the other half of caching

Caching and artifacts solve two different problems that look similar. A cache is for something that's expensive to reproduce but shouldn't have changed — dependencies keyed on a lockfile hash, reused across many runs. An artifact is for something a job just produced in this specific run that a later job in the same run needs exactly as-is. Reach for caching when the question is "has this changed since last time?" and for an artifact when the question is "how does this job's output get to that job?"