Skip to content

Release with verwalter instead of changesets/action - #784

Open
lukasIO wants to merge 6 commits into
mainfrom
claude/migrate-release-verwalter-a70793
Open

lukasIO wants to merge 6 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.30.0, pinned by commit:
    • release-pr.yml keeps the release PR open on each push to main.
    • release.yml tags and creates the GitHub releases after the release PR merges. Then it builds both packages and runs pnpm publish per package with npm trusted publishing. The server SDK docs build and S3 upload move to the end of this job.
    • 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 script, 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 publish leaves the tag. Re-run the Release workflow. It skips versions that npm already has.
  • Snapshot releases have no equivalent. The old setup had none either.

Verified

  • verwalter plan: 2 packages, 0 pending changesets.
  • verwalter status: both packages at the version of their last tag, with the GitHub release published and the version on npm.
  • verwalter pr --dry-run: nothing to release.
  • pnpm install --frozen-lockfile passes with the updated lock file.
  • pinact run --check passes on the new workflows.

For maintainers

The PR cannot do these:

  • Allow GitHub Actions to create pull requests (Settings, Actions, General), or add the VERWALTER_RELEASE_CLIENT_ID and VERWALTER_RELEASE_APP_KEY secrets for the verwalter GitHub App. With github.token, the release PR does not trigger CI. release.yml expects the author verwalter-release[bot]. Without the App, change that check to github-actions[bot].
  • Create the internal label, and add it to this PR. The PR changes only devDependencies of a package.
  • Make sure that npm trusted publishing for both packages names release.yml, not ci.yml.

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 <[email protected]>
@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: 10da6cd

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 <[email protected]>
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 <[email protected]>
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.

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 [email protected] 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.

contents: write
id-token: write # trusted publishing

jobs:

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.

Non-blocking: serialize release workflows without dropping pending releases

Could we serialize the whole release workflow? An older run can fetch tags before a newer release exists, finish after it, and publish to latest. With two separate tag snapshots, I verified that the pinned verwalter chooses the default npm tag for both versions, so the older publish can move latest backwards.

A shared concurrency group with queue: max and cancel-in-progress: false would prevent overlapping release runs while retaining queued runs. cancel-in-progress: false alone still allows a newly queued run to replace an existing pending run. Queueing does not itself guarantee release-version order, but it removes the concurrent execution window.

The previous workflow also lacked serialization, so this is optional hardening rather than a regression introduced here.

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.

Partly fixed in d5e70d1, completed in 59ed548. The publish job has the group npm-publish with cancel-in-progress: false and now queue: max. Two publish jobs no longer run at the same time. A waiting publish job checks out only after the running one ends, so it sees the newer tag, and verwalter picks latest-1 for the older version. queue: max keeps every waiting run. I left the release job outside the group: it writes only tags and draft releases, and the order of the publish jobs decides the npm dist-tag.

@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 <[email protected]>
- 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 <[email protected]>
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 <[email protected]>
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