Skip to content
Tutorials Center
My learning

Topics

Lesson 40 of 44 ยท Projects

Project: Release Automation for a Monorepo

Automate releases in a monorepo: read conventional commits, bump per-package versions, write changelogs, create tags, and publish only the packages that changed.

A monorepo holds many packages in one repository, and releasing it well is harder than releasing a single project. If every merge bumps every version, consumers get noise. If nothing is automated, people forget to release or tag the wrong commit. The goal of this project is a pipeline that looks at what actually changed since the last release and does only the necessary work: it picks a new version for each affected package, writes its changelog, tags it, tests what was touched, and publishes just those packages.

The repository in this project has three packages: core, utils (which depends on core) and web (which depends on both). The workflow files below are read-only, because they need GitHub, a registry and your credentials. The centerpiece is a stand-in: a release planner written in Node.js that takes a list of conventional commits and produces the whole plan. It runs on this site and mirrors the decisions the real tools make. The ideas come from Versioning and Automated Releases and CI for Monorepos.

The design in one picture

flowchart TD
  C["Commits since last tags"] --> P["Parse conventional commits"]
  P --> A["Map files to packages"]
  A --> V["Pick version bump per package"]
  V --> D["Propagate to dependents"]
  D --> T["Test affected packages"]
  T --> L["Changelog + tag per package"]
  L --> U["Publish matrix"]

Every release is computed from commits; no one types a version number.

Decisions to make first

Every team has to settle these before writing YAML, and the planner below encodes one answer to each:

  1. Independent versions. Each package has its own version and tags such as [email protected], so a change to web does not force a release of core.
  2. Conventional commits drive bumps. fix: is a patch, feat: is a minor, and a ! after the type or a BREAKING CHANGE: footer is a major. Types such as docs:, chore: and test: do not release anything on their own.
  3. Dependents follow. If core is released, packages that depend on it need at least a patch release so that their published dependency range picks up the new version. This is a policy; some teams prefer to let ranges float and release dependents only when they change.
  4. Scopes or paths decide ownership. A commit belongs to the packages whose files it touched. Scopes in the message (feat(utils): ...) are helpful for humans but unreliable as the only signal, so path mapping is the source of truth.
  5. 0.x versions. Before 1.0.0 many teams treat a breaking change as a minor bump. We use the standard rule (breaking is major) for clarity.

If you would rather not build this yourself, tools such as Changesets, release-please, semantic-release plugins for monorepos and Nx release implement variations of this design. Learning the mechanics first makes their configuration much easier to understand.

Step 1: validate commit messages on pull requests

The plan is only as good as the commit messages. Check the pull request title (when you squash-merge, the title becomes the commit message):

YAML
name: pr-title

on:
  pull_request:
    types: [opened, edited, synchronize]

permissions:
  contents: read

jobs:
  check-title:
    runs-on: ubuntu-latest
    steps:
      - name: Validate conventional commit title
        env:
          TITLE: ${{ github.event.pull_request.title }}
        run: |
          pattern='^(feat|fix|docs|chore|refactor|test|ci|perf|build)(\([a-z0-9-]+\))?!?: .+'
          if ! printf '%s' "$TITLE" | grep -Eq "$pattern"; then
            echo "Title must look like: feat(scope): summary"
            exit 1
          fi

The title goes through an environment variable instead of being pasted into the script with ${{ }}. A pull request title is untrusted input, and interpolating it directly would allow script injection, as explained in Securing Your Pipeline.

Step 2: test only what is affected

On pull requests, a small job computes the affected packages and exposes them as a matrix. Your repository would contain a script (here scripts/affected.mjs) that prints a JSON array, such as ["core","utils"]:

YAML
name: ci

on:
  pull_request:
  push:
    branches: [main]

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.affected.outputs.packages }}
      any: ${{ steps.affected.outputs.any }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: affected
        run: |
          base="${{ github.event.pull_request.base.sha || github.event.before }}"
          list=$(node scripts/affected.mjs "$base" HEAD)
          echo "packages=$list" >> "$GITHUB_OUTPUT"
          if [ "$list" = "[]" ]; then echo "any=false" >> "$GITHUB_OUTPUT"; else echo "any=true" >> "$GITHUB_OUTPUT"; fi

  test:
    needs: plan
    if: needs.plan.outputs.any == 'true'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        package: ${{ fromJSON(needs.plan.outputs.packages) }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test --workspace "${{ matrix.package }}"

fetch-depth: 0 downloads the full history, which the diff needs. A job with a matrix produced by fromJSON fails with an error when the list is empty, hence the separate any output and the if condition. On a brand new branch the before SHA can be all zeros, so a production script should fall back to testing everything in that case. The "affected" set is the changed packages plus everything that depends on them, directly or indirectly, which the planner below computes.

Step 3: plan the release on main

When commits land on main, a release job reads the commits since each package's last tag. We keep the logic in a script so it can be tested locally and by unit tests, and the workflow just calls it:

YAML
name: release

on:
  push:
    branches: [main]

concurrency:
  group: release
  cancel-in-progress: false

permissions:
  contents: read

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.plan.outputs.matrix }}
      has_releases: ${{ steps.plan.outputs.has_releases }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: plan
        run: node scripts/release-plan.mjs >> "$GITHUB_OUTPUT"

  publish:
    needs: plan
    if: needs.plan.outputs.has_releases == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    strategy:
      fail-fast: false
      max-parallel: 1
      matrix:
        include: ${{ fromJSON(needs.plan.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm version "${{ matrix.version }}" --no-git-tag-version --workspace "${{ matrix.name }}"
      - run: npm publish --workspace "${{ matrix.name }}" --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - name: Tag
        run: |
          git tag "${{ matrix.name }}@${{ matrix.version }}"
          git push origin "${{ matrix.name }}@${{ matrix.version }}"

A few choices stand out. concurrency with cancel-in-progress: false queues releases instead of cancelling a running one, because killing a publish half-way leaves tags and the registry out of step. max-parallel: 1 publishes one package at a time; combined with an ordering in the matrix (dependencies first), consumers never see a package whose dependency is not yet published. The id-token: write permission allows npm provenance statements, and the registry token is an environment secret in a real setup. Because main is usually protected, this sketch does not commit the new version back. The version exists in the published package and in the tag. The alternative is a release pull request that bumps the files and changelog, which you merge to release (the approach release-please takes).

Stand-in: the release planner

The program below is a complete, small release planner. It knows the package graph, receives commits with their changed files, and prints: which packages are affected, the new versions, changelogs, tags and the publish order. Edit the commits list to try other histories: add a ! to a type for a major bump, or touch only docs/ files to see that nothing is released.

Node.js End-to-end release planner

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Study the output. core gets a patch because of the fix, web gets a minor because of the feature, and utils had only a chore: change yet is released as a patch, since it depends on the newly released core. The README change touches no package, so it is ignored. The tests cover all three packages: core changed, and utils and web depend on it.

Stand-in: checking a commit message

The planner depends on well-formed messages. The checker below is the same pattern as in the workflow, shown in JavaScript so you can try your own titles.

JS Conventional commit title checker

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

No output.

Notice that docs: with nothing after the space fails because the pattern requires at least one character of summary, and that a capital letter in the scope is rejected by this particular rule. Your own rule may differ, as long as the planner and the check agree.

Hardening and edge cases

  • Idempotency. If the publish job is re-run, tags and registry versions already exist. Make the script skip a version that is already published instead of failing.
  • Partial failure. With fail-fast: false the other packages continue, but a failed dependency should block its dependents. If ordering matters strongly, use sequential jobs or a single job with a loop.
  • Squash vs merge commits. The planner reads whatever lands on main. With squash merging, the pull request title is the only message, which is why Step 1 validates it.
  • Changelog storage. The sketch above prints notes; in practice you either commit CHANGELOG.md through a release pull request or attach the notes to a GitHub Release.
  • Secrets. The registry token should live in a protected environment, and the publish job should be the only one that can read it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In the planner, why is utils released after a chore commit?

    The policy gives dependents at least a patch release when an internal dependency is released, so their published dependency range picks up the new version.
  2. 2. Which commit message produces a major version bump?

    A ! after the type, or a BREAKING CHANGE footer, marks a breaking change, which maps to a major bump.
  3. 3. Why does the test job check an any output before using fromJSON on the matrix?

    An empty matrix is an error. A separate boolean output lets the test job be skipped cleanly.
  4. 4. Why is the pull request title passed through an environment variable in the validation step?

    An attacker can write a title containing shell syntax. As an environment variable it stays data and is never parsed as code.
  5. 5. Why use concurrency with cancel-in-progress set to false on the release workflow?

    Cancelling a release mid-way can leave tags and registry versions inconsistent, so new runs wait their turn.

Summary

  • Release monorepo packages independently, with tags like name@version, so unrelated changes do not force releases.
  • Conventional commits supply the bump: fix is patch, feat is minor, ! or a breaking footer is major, and other types release nothing.
  • Map changed files to packages, then propagate through the dependency graph for both testing and dependent releases.
  • Compute a plan first (a script with unit tests), then feed it to a publish matrix; skip the matrix when it would be empty.
  • Serialize releases, publish in dependency order, and make every step safe to re-run.
  • Validate commit titles on pull requests, passing untrusted text through environment variables.
  • The real workflows are read-only here; the planner models the decisions.

Next: Practice: Pipeline Exercises with Solutions