Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: Automated Release Pipeline

Build an automated release pipeline: tag a version, verify it, build artifacts, publish to npm and ghcr.io with provenance, create release notes from labels and require approval.

Releasing by hand means remembering twelve steps and getting one wrong on a Friday. In this capstone you automate the whole path from "we are ready" to "users can install version 1.4.0". You will combine tags, workflows, environments, packages, release notes and security features from the previous lessons.

The pipeline files are read-only, since they need a real repository. The stand-in at the end generates release notes from labelled pull requests, so you can see the idea behind .github/release.yml.

The release flow

flowchart LR
  A["Maintainer pushes tag v1.4.0"] --> B["Verify: tag matches package.json"]
  B --> C["Build and test"]
  C --> D["Approval: environment release"]
  D --> E["Publish npm package"]
  D --> F["Push image to ghcr.io"]
  D --> G["Create GitHub release"]

One tag fans out to every published artifact, after a human approval.

The design rules:

  1. The tag is the trigger and the source of truth for the version.
  2. Verify before publishing: fail early if the tag and the package version disagree.
  3. Build once, publish many: build artifacts in one job and reuse them via artifacts.
  4. Approval gate on an environment, so a stray tag cannot publish.
  5. Least privilege: only the publishing jobs get write permissions.
  6. Provenance: sign what you ship.

Step 1: prepare the repository

  • Create an environment named release (Settings -> Environments) with required reviewers and a restriction that only tags matching v* may deploy to it.
  • Add a tag ruleset for v* so only maintainers can create or delete release tags.
  • For npm, create an automation token with publish rights and save it as the environment secret NPM_TOKEN (or use npm trusted publishing with OIDC where your registry supports it).
  • Add .github/release.yml with label categories (see the releases lesson).

Step 2: verify and build

YAML
name: Release

on:
  push:
    tags: ["v*.*.*"]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.v.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - id: v
        run: |
          TAG="${GITHUB_REF_NAME#v}"
          PKG="$(node -p "require('./package.json').version")"
          if [ "$TAG" != "$PKG" ]; then
            echo "Tag $TAG does not match package.json $PKG" >&2
            exit 1
          fi
          echo "version=$TAG" >> "$GITHUB_OUTPUT"

  build:
    needs: verify
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: npm pack
      - uses: actions/upload-artifact@v4
        with:
          name: package
          path: "*.tgz"

The verify job compares the tag (without its v) to the version in package.json and passes the result to later jobs as a job output. Building and testing run again at the tag, so a release never ships untested code.

Step 3: publish behind an approval

YAML
  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: package
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm publish *.tgz --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

  publish-image:
    needs: [verify, build]
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ needs.verify.outputs.version }}
      - uses: actions/attest-build-provenance@v2
        with:
          subject-name: ghcr.io/${{ github.repository }}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

Both jobs target the release environment, so the run pauses once for approval and then both proceed. --provenance links the npm package to the workflow that built it, and the attestation does the same for the container image, which gives users a way to verify both (see supply-chain safety and Packages). Note that the permissions are set per job, not at the top, so the build job cannot publish.

The image job lists verify in needs so it can read the verified version from needs.verify.outputs.version. A job can only read outputs of jobs it names (directly or through needs), so add every job whose output you use.

Step 4: create the GitHub release

YAML
  github-release:
    needs: [publish-npm, publish-image]
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: package
      - env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PRE=""
          case "$GITHUB_REF_NAME" in *-*) PRE="--prerelease" ;; esac
          gh release create "$GITHUB_REF_NAME" *.tgz --generate-notes $PRE

The release is created last, so it only exists when everything shipped. A tag with a hyphen, like v2.0.0-beta.1, is marked as a pre-release by the case statement.

Step 5: rehearse and recover

  • Test the pipeline with a tag like v0.0.0-test.1 in a throwaway fork or with --dry-run publishing first.
  • If publishing half-succeeds, fix forward: publish a new patch version rather than moving the tag.
  • If a bad version reaches users, deprecate it (npm deprecate) and, for security issues, publish an advisory.
  • Keep the pipeline itself reviewed: a CODEOWNERS rule on .github/workflows/ protects it.

A stand-in: release notes from labelled pull requests

GitHub's generated notes group merged pull requests by label using .github/release.yml. The stand-in below reimplements that grouping on invented data, so you can experiment with categories and exclusions. It is a simplified model of the idea, not GitHub's generator.

JS Stand-in: release notes generator (invented data)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Move a pull request to a different label and the entry jumps to another heading, which is exactly why consistent labelling pays off at release time.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why verify that the tag matches package.json before publishing?

    A mismatch signals a mistake; failing early prevents an inconsistent release.
  2. 2. What does putting the publish jobs in an environment with required reviewers achieve?

    The job pauses until a reviewer approves, so a stray tag cannot publish.
  3. 3. Why set permissions per job rather than only at workflow level?

    Least privilege limits what a compromised step can do.
  4. 4. A published release has a bug. What is the right fix?

    Tags that users already fetched must not move; fix forward with a new version.

Summary

  • Make the tag the trigger: verify, build once, approve, publish everywhere, then create the release.
  • Use an environment with reviewers, a tag ruleset and per-job permissions to keep publishing safe.
  • Add provenance to npm packages and container images.
  • Labelled pull requests become release notes; fix forward instead of moving tags.

Next: Practice: GitHub Scenarios