Skip to content

chore: release packages with verwalter instead of changesets/action - #784

Merged
lukasIO merged 9 commits into
mainfrom
claude/migrate-release-verwalter-a70793
Nov 19, 2026
Merged

lukasIO merged 9 commits into
mainfrom
claude/migrate-release-verwalter-a70793

Conversation

@lukasIO

@lukasIO lukasIO commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Releases run through changesets/action in the build_and_release job of ci.yml. That job runs on every push to main, and it both commits to the release PR and publishes. This PR moves the release to verwalter. Verwalter keeps one release PR that it regenerates from main, and it tags before it publishes. Tag names, versions and changelogs continue without a gap.

Change

  • verwalter.toml lists packages/* (livekit-server-sdk, @livekit/rtc-node), the version in package.json, the existing tag format {package}@{version}, and npm as the registry. Private examples are left out.
  • Four new workflows from verwalter v0.31.0, pinned by commit:
    • release-pr.yml keeps the release PR open on each push to main.
    • release.yml runs after a release PR merges, on any base branch, so that an rc PR from another branch is released too. It has four jobs:
      • release tags and creates the GitHub releases.
      • publish builds both packages and runs pnpm publish per package with npm trusted publishing. It skips versions that npm has, and it fails a package whose files changed since its tag. One publish runs at a time (npm-publish group with queue: max).
      • verify runs verwalter status --check. If a tag, a public GitHub release or an npm version is missing, it fails.
      • docs builds the server SDK docs and uploads them to S3. It runs only for a final livekit-server-sdk release from main. An rc or a release of rtc-node alone does not replace the docs.
    • pre-release.yml opens an rc PR on demand.
    • changeset-check.yml fails a PR that changes a package without a changeset. The internal label skips the check.
  • Removed: the build_and_release job from ci.yml, .changeset/config.json, the ci:publish and changeset scripts, and @changesets/cli with @livekit/changesets-changelog-github from both package.json files. ci.yml now needs only contents: read.
  • Kept: .changeset/*.md files use the same format, so pending changesets carry over. Every CHANGELOG.md stays, and new entries go on top.

Different afterwards

  • Nobody pushes to the release PR. A fix goes to main with its own changeset.
  • A failed job is re-run with "Re-run failed jobs" on its run. That keeps the merge commit. A run by hand is only for a fixed workflow file. Set ref to the release tag. If no tag exists yet, set it to the merge commit of the release PR. An empty ref means the head of the branch.
  • A failed docs upload makes only the docs job red. To deploy the docs again, run the workflow by hand with package=livekit-server-sdk and ref=livekit-server-sdk@<version>.
  • Snapshot releases have no equivalent. The old setup had none either.

Verified

  • verwalter v0.31.0, built from the tag: plan shows 2 packages and 0 pending changesets. status --check exits 0. publish --dry-run skips both versions because npm has them.
  • The docs gate, with fixtures for releases: it runs for a final livekit-server-sdk release. It skips an rc, a release of rtc-node alone, and an empty list.
  • pnpm install --frozen-lockfile and pinact run --check pass. The docs job's build sequence runs locally.
  • actionlint v1.7.12 reports one error: it does not know queue in concurrency. GitHub added queue in May 2026, after that actionlint release. The workflow syntax docs allow it at job level.

For maintainers

The PR cannot do these:

  • Make sure that npm trusted publishing for both packages names release.yml, not ci.yml. Else the first publish fails and the release stays a draft.
  • Create the internal label, and add it to this PR. The PR changes only devDependencies and scripts of a package.
  • Uninstall the changeset-bot GitHub App. It still posts "No Changeset found" on each PR.

Not done yet

  • The API check ([check].api with break-check). That is a follow-up.

🤖 Generated with Claude Code

Add verwalter.toml and the four verwalter workflows (release PR,
release, pre-release, changeset check). Remove the changesets/action
job from CI, .changeset/config.json, the ci:publish script and the
changesets devDependencies. Pending .changeset/*.md files carry over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lukasIO lukasIO self-assigned this Nov 16, 2026
@changeset-bot

changeset-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 61fb163

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@lukasIO
lukasIO marked this pull request as ready for review November 16, 2026 10:49
devin-ai-integration[bot]

This comment was marked as resolved.

Run the release workflow for verwalter PRs on any base branch, so an
rc PR from another branch is tagged and published. Remove the
server SDK's changeset and ci:publish scripts. Let a failed docs build
or upload fail the publish job.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
devin-ai-integration[bot]

This comment was marked as resolved.

An rc release must not replace the docs of the current stable release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread .github/workflows/release.yml Outdated
command: publish
releases: ${{ needs.release.outputs.releases }}

# The docs site holds one version: an rc must not replace it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: an rc?

Suggested change
# The docs site holds one version: an rc must not replace it.
# The docs site holds one version: a rc must not replace it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept "an rc". "rc" is said "ar-see", which starts with a vowel sound, so it takes "an".

@xianshijing-lk xianshijing-lk left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the release workflows and validated the source/tag mismatch and docs guard with local fixtures against the pinned verwalter v0.30.0. Two correctness findings and one non-blocking concurrency suggestion are inline. No packages or documentation were published during validation.

Comment thread .github/workflows/release.yml Outdated
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.merge_commit_sha || github.sha }}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Reject source/tag mismatches during manual recovery

A fresh manual dispatch on main checks out the branch's current SHA. If a failed publish left a release tag at commit A and the branch has advanced to B without another version bump, recovery can publish B's source under A's already-tagged version.

I validated this with the pinned verwalter v0.30.0: with the tag pointing to A and the same package version at B, both release --dry-run --package livekit-server-sdk and publish --dry-run accept the mismatch. The build steps here compile B before publishing.

Please reject a mismatch between the package's release tag and the checkout before building/publishing. Documenting recovery by re-running the original workflow or dispatching its original tag would also help operators choose the right source.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 59ed548.

  • A run by hand takes a ref input. All checkouts use merge_commit_sha || inputs.ref || github.sha.
  • Before the build, the publish job fails if a package that this run publishes differs from its release tag. The check uses git diff --quiet <tag> HEAD -- <package dir>. The error message names ref=<tag>.
  • The check covers only packages in releases (or all, if the list is empty) that have a tag and are not on npm yet. Without that limit, a package that changed after its last release through an internal PR would block every later release.
  • The comment on workflow_dispatch now says to use "Re-run failed jobs" first, and to run by hand only with ref set to the tag.

I tested the check with fixtures: it fails on a newer commit and passes at the tag. verwalter itself checks only that the tag exists, so I will also report this upstream.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update: I removed the guard step again in 10da6cd. The next verwalter release fixes this in publish itself (livekit/verwalter#105): it fails a package whose files changed since its tag, and the reason names ref=<tag>. I will bump the pin when that release is out. Until then, a run by hand must set ref to the release tag, as the comment in release.yml says.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 8d3b36b: the workflows now pin verwalter v0.31.0, whose publish fails a package whose files changed since its tag (livekit/verwalter#105).

Comment thread .github/workflows/release.yml Outdated
id: docs
run: |
version=$(node -p "require('./packages/livekit-server-sdk/package.json').version")
if [[ "$version" != *-* ]]; then echo "stable=true" >> "$GITHUB_OUTPUT"; fi

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Restrict stable documentation deployment to the appropriate server SDK release

A stable version in this checkout does not establish that this run released the server SDK or that this branch contains the current stable documentation. An RTC-only prerelease on a maintenance branch can leave the server SDK at an older stable version and overwrite the single unversioned documentation destination.

I ran this guard against the server SDK manifest from the real livekit-server-sdk@2.19.3 tag: it emits stable=true even with an RTC-only release handoff. Both documentation steps then run.

Please require an appropriate stable server SDK release in needs.release.outputs.releases and restrict this unversioned destination to the designated current release line. Other branches can skip deployment or use a versioned prefix; keep a way to retry a failed docs deployment.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 59ed548. The docs job now runs only when releases contains livekit-server-sdk with prerelease == false, and only for main (the base branch of the PR, or the branch of a run by hand). A release of rtc-node alone, an rc, or another branch skips it. To retry a failed docs upload, start a run by hand with package=livekit-server-sdk, which reports the package again.

Comment thread .github/workflows/release.yml Resolved

@xianshijing-lk xianshijing-lk left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

got some review comments from ai, maybe take a look ?

lukasIO and others added 2 commits November 17, 2026 10:15
A docs failure no longer turns the publish job red after npm has the
version. A publish job waits for a running one instead of publishing
the same version twice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Add a ref input for runs by hand. Before the build, fail when a
  package to publish differs from its release tag.
- Upload the server SDK docs only when this run released a final
  server SDK version from main.
- Keep every waiting publish run with queue: max.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The next verwalter release checks in publish that each package matches
its tag (livekit/verwalter#105). Until then, a run by hand sets ref to
the tag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lukasIO and others added 2 commits November 19, 2026 13:05
v0.31.0 checks in publish that each package matches its tag, so the
note about v0.30.0 goes. A verify job runs status --check after the
publish, as in the upstream example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A build job runs first and uploads the build output. A build that fails
now stops the run before release creates any tag. publish and docs use
that output instead of building after the tag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lukasIO lukasIO changed the title Release with verwalter instead of changesets/action chore: release packages with verwalter instead of changesets/action Nov 19, 2026
…e-verwalter-a70793

# Conflicts:
#	pnpm-lock.yaml
@lukasIO
lukasIO merged commit f2cd644 into main Nov 19, 2026
14 checks passed
@lukasIO
lukasIO deleted the claude/migrate-release-verwalter-a70793 branch November 19, 2026 17:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants