Artifacts & packages — the thing you built, handed forward

The word artifact is overloaded, and the overload trips up more engineers than any tool in this track. It names two things that live in different worlds and get confused daily, so name them apart on the first page and keep them apart forever. A pipeline artifact is the output of a build — a zipped web app, a compiled binary, a set of scripts — that one stage of a pipeline produces and hands to a later job; it exists to move a built thing across the pipeline without rebuilding it. A package artifact is a versioned, shareable dependency — a NuGet package, an npm module, a Python wheel — that many projects pull in by name and version; it exists to let a piece of code be reused across a company without copy-and-paste. One is a handoff inside a single run. The other is a shared library the whole organisation depends on.

Build outputs and shared packages are both stored files, but they solve different problems. An Actions artifact carries a particular run's output to a later job or keeps it for download. GitHub Packages hosts versioned packages that other projects can install. Keep that difference clear: use an artifact to hand the tested application to deployment; use a package registry to publish a reusable library.

An Actions artifact passes build output between jobs or preserves it after a run. Use actions/upload-artifact after building and actions/download-artifact in the job that needs those files. Jobs can use separate temporary runners, so files do not move between them unless you explicitly transfer them. For a release, build once, test that output, and deploy the same artifact.

The reason this matters is a principle with a name: build once, deploy many. You build the artifact a single time, then promote that same artifact through staging and into production — rather than rebuilding it separately for each environment. Rebuilding per environment feels harmless and is quietly poisonous: a dependency updates between builds, a compiler flag differs, the machine has changed, and the binary you tested in staging is no longer the binary you shipped to customers. When it then fails only in production, you are debugging a thing that was never tested, and the trail is cold. One build, published once, carried forward unchanged, means the artifact that passed your tests is byte-for-byte the artifact your customers run.

Ship the binary you tested, not a copy.

The YAML is small enough to read in one breath: publish in the build stage, name it, then download it in a stage that depends on the first.

# .github/workflows/warehouse.yml — build once, pass the same output to deploy
name: Warehouse
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - run: npm ci && npm test && npm run build
      - uses: actions/upload-artifact@v7
        with:
          name: warehouse-site
          path: dist/
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v6  # supplies the deployment configuration/script
      - uses: actions/download-artifact@v7
        with:
          name: warehouse-site
          path: dist/
      - run: ./deploy.sh dist/  # deploy the tested files; do not rebuild

A package is reusable code with a name and a version: for example, a shared npm library used by several applications. GitHub Packages can store supported package types and connect package access to GitHub repositories and organizations. The exact setup differs by package ecosystem, so check that ecosystem's registry instructions before publishing.

Unlike a workflow artifact, a package is meant to be consumed as a dependency by other projects. Publish a new version when the library changes, grant consumers only the access they need, and pin each application's dependency to an intentional version. GitHub Packages is not a proxy cache for public registries: configure your package manager's normal registry sources and lockfile separately.

Semantic Versioning gives meaning to MAJOR.MINOR.PATCH: a breaking change increments MAJOR, a backward-compatible feature increments MINOR, and a backward-compatible fix increments PATCH. This is a convention teams adopt; package registries do not prove that a release follows the promise. Write release notes and test compatibility.

A package is worthless to the people who consume it unless its version number carries information, and semantic versioning is the agreement that makes it do so. A version is three numbers, MAJOR.MINOR.PATCH, and each position promises something specific about what changed. Bump the PATCH for a backward-compatible bug fix; bump the MINOR when you add functionality that does not break anyone; bump the MAJOR when you make a breaking change existing callers must adapt to. Read the other way, the number is a message to every consumer: a jump from 2.4.1 to 2.4.2 says "safe, take it"; a jump to 3.0.0 says "read the notes before you upgrade, this will break you." The whole point is that a consumer can decide whether to take an update without reading your code — the number tells them.

Semantic version

A version string of the form MAJOR.MINOR.PATCH in which each field signals the kind of change since the last release: MAJOR for a breaking change, MINOR for a backward-compatible feature, PATCH for a backward-compatible fix. The number is a contract between the package's author and everyone who depends on it.

This is precisely why an internal shared library must be a versioned package and never a copied file. When five projects each hold their own copy of a helper library, a fix to one copy reaches exactly one project; the other four keep the bug, and no one can say which copy any given project is running — the codebase has quietly forked five ways. Move that library into a package registry with a semantic version and the relationship inverts: you publish 1.2.3 once, every project references it by version, a fix ships as 1.2.4 and each team takes it deliberately, and the version in a project's manifest is an exact, auditable statement of which code it runs. Copy-paste hides that; a version number publishes it. That difference — between "somewhere there are five slightly different copies" and "everyone is on 1.2.4" — is the difference between a dependency you can reason about and one you cannot.

Step back and the two halves of this part are the same idea wearing different clothes. Build once and deploy the same pipeline artifact everywhere, and the thing in production is provably the thing you tested. Publish a shared library once under a semantic version and consume it by that version everywhere, and the code in each project is provably the code you think it is. Both are refusals of the same quiet lie — that a thing rebuilt, or a folder copied, is "the same" as the original. It is not, and the gap between "the same" and "a copy of" is where the hardest bugs live: the ones that reproduce nowhere but where they matter.

Build once and promote the tested artifact; publish shared code as a versioned package and grant consumer repositories the correct access. Those are concrete controls that make releases and dependencies easier to audit. You do not need many sentences to signal which one you are — you need the right ones, and this part is where you earn them.