Skip to Content
WebFrostdocs
Contributing

Releasing

How WebFrost versions work, how to add a changeset, and the CI and release workflows that release a version when the Version Packages pull request is merged.

WebFrost uses Semantic Versioning and changesets for version bumps and the changelog. All packages move together.

Versioning policy

MAJOR.MINOR.PATCH:

ChangeBump
Breaking API or CLI change, incompatible database migrationMAJOR
New feature, CLI command or server route, backwards-compatibleMINOR
Bug fix, docs, dependency update, performance tweakPATCH

When in doubt, use PATCH. Prefer MINOR over MAJOR: WebFrost is self-hosted, so users control their own upgrades.

All packages (@webfrost/core, @webfrost/cli, @webfrost/server, @webfrost/sdk, @webfrost/ui) share one version number through a fixed group in .changeset/config.json. Private packages are versioned with the group but get no per-package tag (privatePackages.tag: false), and @webfrost/docs is ignored. Versions stay on 0.x until the maintainers decide to release 1.x.

Pre-release suffixes for a tag:

SuffixMeaning
-alpha.NIncomplete, not ready for broad testing
-beta.NFeature-complete, may have known issues
-rc.NRelease candidate, ships unless a blocking bug appears

Example: v0.2.0-alpha.1, v0.2.0-rc.1, v0.2.0.

Add a changeset

Every pull request that changes behavior users will notice needs one:

bun changeset
# pick the bump type and write a short description

Commit the generated .changeset/*.md file with the pull request.

Cut a release

Merging the Version Packages pull request is the release. Nobody pushes a tag by hand.

Make sure main is green

All intended pull requests are merged and CI passes on main.

Merge the Version Packages pull request

When changesets accumulate on main and CI has passed, the Changesets job of the release workflow opens or updates a pull request titled chore: version packages. It bumps every package version and writes the CHANGELOG.md entries. Review and merge it.

CI does not run on that pull request by itself

Workflows do not start for pull requests opened or updated with the built-in GITHUB_TOKEN, so the required checks never report and the pull request cannot be merged. Close and reopen the pull request: the reopen event comes from you, so CI runs. Do this after every update of the pull request. If it becomes tedious, switch the action to a GitHub App token.

gh pr list --search "chore: version packages"

Once CI passes on the merge commit, the release workflow tags it v<version> (the Release tag job) and, in the same run, builds and publishes the Docker image, the binaries, the GitHub release and the Homebrew formula.

Check the GitHub release

NEW_VERSION=$(node -p "require('./packages/core/package.json').version")
gh run list --workflow release.yml --limit 3
gh release view "v$NEW_VERSION"
curl -fsSL https://webfrost.dev/install.sh | WEBFROST_VERSION=$NEW_VERSION sh

The release holds the five binaries, checksums.txt and the notes from the CHANGELOG.md section of the version (GitHub-generated notes when there is none).

Smoke test the image

docker run --rm -d --name wf-smoke -p 3001:3000 \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  ghcr.io/gtkatakura/webfrost/server:$NEW_VERSION
sleep 5 && curl http://localhost:3001/health   # {"status":"ok"}
docker stop wf-smoke

Hotfixes and pre-releases: push a tag by hand

A v*.*.* tag pushed by hand still releases that commit, as long as CI passed on it (the CI gate job checks):

git tag v0.2.0-rc.1 <commit>   # or git tag -s, to sign the tag itself
git push origin v0.2.0-rc.1

A tag with a suffix (-rc.1) is a GitHub pre-release, never "latest", does not move the latest image tag and does not touch Homebrew. The automatic tag never makes pre-releases: in Changesets pre-release mode (.changeset/pre.json) the Release tag job does nothing, so tag those by hand.

For an urgent fix, merge the minimal fix with a changeset to main through a pull request and merge the Version Packages pull request, which releases it. When main holds work that must not ship yet, branch from the released tag (git checkout -b hotfix/v0.1.1 v0.1.0), apply the fix, bump the versions by hand, open a pull request so CI runs on that commit, and push the v0.1.1 tag on it once CI passes.

Retry a failed release

  • A product job failed (Docker, Binaries, Verify binary, GitHub Release, Homebrew): open the release run and choose Re-run failed jobs. The tag stays where it is; the jobs pick it up from the earlier attempt. Re-run all jobs works too: on a re-run, the Release tag job finds its own tag on the same commit and passes it on. Every product job can run again safely (the image tags are overwritten, the release assets are uploaded with --clobber, the formula commit is skipped when unchanged).
  • The run failed before the tag was pushed (Changesets or Release tag failed): re-run the failed jobs, or push the tag by hand as above.
  • CI on the merge commit was cancelled (a second merge landed right after it): re-run CI for that commit, and its successful run starts the release. If the next commit on main has no new changeset, its CI run releases the version from that commit instead.

Roll back

Deploy the previous image tag, and restore a backup first if the release changed the database schema. See Deploy.

CI

.github/workflows/ci.yml runs on every pull request and push to main:

JobWhat it does
Lintbun run lint (Biome)
Typecheckbun run typecheck, then bun run build to keep the quickstart working
Unit Testsbun run test, with Playwright Chromium and a MinIO container for the S3 integration tests
Unit Tests (PostgreSQL), Unit Tests (MySQL)The core and server tests, and the server API end-to-end tests, again against a PostgreSQL 17 and a MySQL 8.4 container, through WEBFROST_TEST_DATABASE_URL
Server API E2Ebun run test:e2e in packages/server
E2EPlaywright tests in packages/ui, with Chromium and yt-dlp, AUTH_DISABLED=true. Traces upload on failure.
Docker buildBuilds packages/server/Dockerfile and apps/docs/Dockerfile without pushing, so a broken Dockerfile fails the pull request

Each job installs with bun install --frozen-lockfile and caches Bun's package cache. CI has read-only permissions (contents: read).

Benchmarks are not part of CI. .github/workflows/bench-vs-archivebox.yml runs the microbenchmarks and the ArchiveBox comparison weekly (Mondays 05:00 UTC) and on manual dispatch. Results upload as artifacts for 90 days.

Release workflow

.github/workflows/release.yml runs after a successful CI run on main, on v*.*.* tags pushed by hand, and on manual dispatch (target docker-ghcr). A release is either path: CI on main followed by Changesets and Release tag, or a pushed tag followed by the CI gate. Either way, the Release version job names the tag and commit, and every job after it builds that commit.

A tag pushed by the workflow itself (with GITHUB_TOKEN) starts no other workflow run, which is why the release jobs run in the same run as the Release tag job.

JobRuns whenWhat it does
CI gatetag or dispatchFails unless the commit already has a successful CI run. It does not run the tests again.
ChangesetsCI succeeded on mainCreates or updates the chore: version packages pull request. When that pull request is merged, it publishes to npm with changeset publish, using npm trusted publishing (OIDC) with provenance. While every package is private this publishes nothing and passes.
Release tagafter ChangesetsReads the shared version from packages/core/package.json (and fails if another package in the fixed group differs). Creates a lightweight v<version> tag (GitHub shows the merge commit's signature) on the commit CI tested and pushes it, only when no changeset is pending, the version is not 0.0.0, Changesets is not in pre-release mode and the tag does not exist. Otherwise it does nothing, so every later CI run on main is a no-op until the next Version Packages merge. Runs one at a time across the repository.
Release versiona tag from either path, or dispatchResolves the tag, version and commit the jobs below use. No permissions.
Docker to GHCRafter Release versionBuilds packages/server/Dockerfile for linux/amd64 and linux/arm64 (QEMU and Buildx) and pushes ghcr.io/gtkatakura/webfrost/server. Layers are cached in GitHub Actions.
Binariesafter Release version, not on dispatchbun build --compile for darwin-arm64, darwin-x64, linux-x64, and linux-arm64 on one Linux runner (Bun cross-compiles), with the UI embedded and the tag as the version. Packs webfrost-<os>-<arch>.tar.gz and checksums.txt (SHA-256).
Verify binaryafter BinariesRuns --version, --help, init, list and doctor from the archives on Linux and macOS (arm64). A failure stops the release.
GitHub Releaseafter Verify binaryCreates the release for the tag (or uploads to it) with the archives and checksums.txt. install.sh and the Homebrew formula read these file names.
Homebrew tapafter GitHub Release, stable tags onlyWrites Formula/webfrost.rb (URL and SHA-256 per OS and CPU) to gtkatakura/homebrew-tap and pushes it. Skipped, passing, when the HOMEBREW_TAP_TOKEN secret is not set.
AURafter GitHub Release, stable tags onlyWrites PKGBUILD and .SRCINFO for webfrost-bin (scripts/aur-pkgbuild.ts: the release tarballs per architecture, the browser's libraries as dependencies, !strip because stripping breaks a Bun-compiled binary) and pushes them to aur.archlinux.org with the AUR_SSH_PRIVATE_KEY secret. Skipped when the secret is not set; a refused push only warns, so the release stays green.
Visual verifyafter the Docker jobStarts the pushed sha-<short-sha> image with AUTH_DISABLED=true, waits up to 60 s for /health, runs a Playwright check that the page renders without console errors, and uploads a screenshot as deploy-screenshot-<sha> for 90 days

Image tags: <version> and <major>.<minor> (no leading v) and sha-<short-sha> on a version tag, plus latest on a stable tag (a tag with a -rc.1 style suffix gets only <version> and does not move latest). A merge to main builds an image only when it releases a version.

If Visual verify fails, open the deploy-screenshot-<sha> artifact: a blank page or an error state is obvious. Usual causes are a static asset build failure (blank page), a JavaScript error, or a slow start (health timeout).

Enabling npm publishing

Every package is "private": true today, @webfrost/sdk included, so changeset publish publishes nothing yet. The SDK is the first one meant for npm: its package.json already carries publishConfig (public, with provenance) and a check:package script (publint and Are the Types Wrong). To publish it:

  1. Set "private": false in packages/sdk/package.json.
  2. Register the repository as a trusted publisher for @webfrost/sdk on npmjs.com (package settings, Trusted Publisher, workflow release.yml). No NPM_TOKEN secret is needed: the job has id-token: write and NPM_CONFIG_PROVENANCE=true.
  3. Merge the Version Packages pull request. With no changesets left pending, the Changesets job runs changeset publish.
  4. Set sdkPublished = true in apps/docs/app/lib/unpublished.ts, so the SDK reference page appears on this site. Until then the page is left out of the navigation, the search and the prerendered pages.

To publish another package, repeat steps 1 and 2 for it.

Secrets and permissions

ItemPurpose
GITHUB_TOKENInjected automatically; pushes to GHCR, opens the Version Packages pull request and pushes the release tag. If a tag ruleset protects v* tags, let GitHub Actions bypass it.
npm trusted publisherReplaces an npm token; configured on npmjs.com, not in the repository
HOMEBREW_TAP_TOKENRepository secret. A fine-grained personal access token with Contents: Read and write on gtkatakura/homebrew-tap and nothing else. Without it the release still succeeds and the formula is not updated.

In repository settings, under Actions, allow workflows to create pull requests, and make the ghcr.io/gtkatakura/webfrost/server package public after the first push.

Add a deploy target

Create a job in release.yml that needs release, runs when needs.release.result == 'success', checks out needs.release.outputs.sha, and document it here.

On this page