Releases & upgrades

How versions are cut, what the release-candidate convention buys you, what CI does, and how to upgrade a running deployment.

Releases are cut by pushing a git tag. That is the only trigger — there is no manual publish step and no separate changelog job.

Version and tag conventions#

The pre-release flag is derived from the tag containing a hyphen, and the latest Docker tag is applied only when the tag contains no hyphen. So the RC convention is enforced by the tag's shape, not by a flag someone has to remember.

Anything touching the Docker image, the database schema, auth, or the proxy goes out as an RC first. Pull it explicitly by tag:

docker pull ghcr.io/<owner>/<repo>:v0.25.0-rc.1

Soak it, then promote.

Release notes#

Every release ships a hand-written docs/releases/<tag>.md. The workflow prefers that file and copies it verbatim into the GitHub release body. Without it, the release body is an auto-generated git log dump plus a compare link. The range runs from the highest-versioned other tag to this one — git tag --sort=-v:refname with the tag being built filtered out. That is the previous release in the normal case, but not when you rebuild an older tag via workflow_dispatch: there the range is computed against a newer tag and the log comes out empty or backwards.

Notes live under the stable name — docs/releases/vX.Y.Z.md — from the first release candidate onward. That means an RC build itself falls back to the git-log changelog. That is fine, because the notes are for the stable release the RC is rehearsing.

Group notes by category, explain why a change was made rather than restating the commit subject, and link the relevant findings document when one exists.

Promoting a release candidate#

scripts/promote-rc.sh v0.25.0-rc.1 [--dry-run]

The script strips the -rc.N suffix, bumps package.json to the stable version, commits, tags, and — after a [y/N] prompt — pushes main and the tag, which fires the release workflow. It refuses to run unless every one of these holds:

• the argument matches vX.Y.Z-rc.N
• the RC tag exists and the stable tag does not
• you are on main with a clean working tree (untracked files ignored)
• the RC tag is an ancestor of HEAD — main has not diverged from what you soaked
• docs/releases/<stable>.md exists

The tag checks run against local refs, after a git fetch --tags origin. A stable tag you created locally and never pushed still trips the "already exists" refusal. Delete it with git tag -d first.

Before it does anything it prints git log --oneline <rc>..HEAD under the heading commits landed since <rc> (these ship untested by the RC build):. Read that list. If it is non-empty, the thing you soaked is not the thing you are about to release.

The package.json bump and its commit are conditional — skipped when the file already holds the stable version, which is the normal case after a repeat run. The tag is always created.

--dry-run prints the push commands and exits without tagging. Declining the final prompt deletes the local tag but keeps the version-bump commit.

What CI does#

ci.yml runs on pushes and pull requests to main, across a Node 20 and 22 matrix, with a postgres:16 service container. The PostgreSQL half of the database adapter suite skips itself without a live server, which would leave the backend untested, so CI provides one via TEST_POSTGRES_URL.

Steps: npm ci → npm run lint → npm run build → npm run typecheck:tests -w @workbench/server → npm run test:coverage -w @workbench/server → Codecov upload with fail_ci_if_error: true.

Two things to know about that list. npm run lint is a no-op — no package defines a lint script, so the turbo task resolves to zero work and exits 0. And the separate typecheck step exists because the main tsconfig.json covers only src/, so the build never type-checks the test suite.

release.yml runs on a v*.*.* or v*.*.*-* tag push, or via workflow_dispatch with a tag input to rebuild an existing tag. It checks out the tag with full history, verifies the tag against package.json, builds and tests on Node 20, assembles the release notes, builds the image with Buildx and pushes it to GHCR with GitHub Actions layer caching, then creates the GitHub release as a draft and immediately publishes it — a two-step needed for repositories with an immutable-releases policy.

flowchart TD
  A[push vX.Y.Z-rc.1] --> B[release.yml]
  B --> C{tag == package.json?}
  C -->|no| F[fail]
  C -->|yes| D[build + test]
  D --> E[push image, tag only]
  E --> G[GitHub pre-release]
  G --> H[soak]
  H --> I[promote-rc.sh]
  I --> J[push vX.Y.Z]
  J --> K[release.yml]
  K --> L[image + latest]
  L --> M[GitHub release]

Upgrading a running deployment#

# docker-compose.override.yml
services:
  workbench:
    image: ghcr.io/<owner>/<repo>:v0.25.0

docker compose pull && docker compose up -d

git fetch --tags && git checkout v0.25.0
docker compose up -d --build