ci: Publish release branch previews

Create Version Packages updates on the release branch and dispatch CI because GitHub token branch updates cannot start another workflow. Green runs publish the package preview and update the GHCR next tag while main continues to update its own mutable image.

Author: aron-cf

.github/changeset-version.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// Called by the changesets action in release.yml as the `version`
-// command. It consumes pending changesets, then applies release-time
-// references that must be committed with the Version Packages PR.
+// Called by the version path in release.yml. It consumes pending changesets,
+// then applies release-time references that must be committed with the Version
+// Packages PR.
 //
 // Changesets owns package versions and changelogs, including private
 // packages (`privatePackages.version` is enabled in .changeset/config.json).

.github/workflows/ci.yml

@@ -4,12 +4,12 @@
 # build siblings whose dist/ this package's typecheck depends on,
 # then run biome + typecheck + tests scoped to that package.
 #
-# Runs on every PR and on every push to main or next, so a merge
-# that slipped through (admin override, branch protection off,
-# etc.) still gets the same lint/build/typecheck/test signal.
+# Runs on every PR and on pushes to the long-lived branches. The release
+# workflow also dispatches CI for the release branch because its GITHUB_TOKEN
+# push cannot start another workflow.
 #
-# Path filter skips pure documentation changes — they have no
-# influence on any package's lint, typecheck, or test surface.
+# Path filters skip pure documentation changes — they have no influence on
+# any package's lint, typecheck, or test surface.
 
 name: CI
 
@@ -20,21 +20,22 @@ on:
       - "docs/**"
       - ".github/**/*.md"
   push:
-    branches: [main, next]
+    branches: [main, next, release]
     paths-ignore:
       - "**/*.md"
       - "docs/**"
       - ".github/**/*.md"
+  workflow_dispatch: {}
 
 permissions:
   contents: read
 
 concurrency:
-  # PRs key on the PR number so successive pushes cancel the prior
-  # run; pushes to main key on the ref so we never cancel a main
-  # build (those are the historical signal).
+  # PRs key on the PR number so successive pushes cancel the prior run. The
+  # version branch also keeps only its newest run, while main builds remain a
+  # historical signal and are never canceled.
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/release' }}
 
 jobs:
   package:
@@ -190,7 +191,11 @@ jobs:
 
   preview:
     name: preview package
-    if: github.event_name == 'pull_request'
+    if: >-
+      ${{
+        (github.event_name == 'pull_request' && github.head_ref != 'release') ||
+        github.ref == 'refs/heads/release'
+      }}
     needs: [package, example]
     runs-on: ubuntu-24.04
     timeout-minutes: 15

.github/workflows/main-computerd-image.yml

@@ -1,20 +1,19 @@
-# Build the computerd image from the commit that passed CI on main. The
-# mutable :main tag gives tests and examples that follow main a fresh binary
-# without waiting for the changesets release flow.
+# Build computerd images from commits that passed CI. The mutable :main tag
+# follows main, while :next follows the changesets Version Packages branch.
 
-name: Main computerd image
+name: Computerd branch image
 
 on:
   workflow_run:
     workflows: ["CI"]
-    branches: [main]
+    branches: [main, release]
     types: [completed]
   workflow_dispatch: {}
 
 concurrency:
-  group: ${{ github.workflow }}
-  # If main advances while an image is building, only the newest commit
-  # should be allowed to publish the mutable :main tag.
+  # Keep the main and next publishers independent while allowing newer commits
+  # on either branch to cancel stale image builds for the same tag.
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.ref }}
   cancel-in-progress: true
 
 permissions:
@@ -30,11 +29,23 @@ jobs:
           (
             github.event_name == 'workflow_run' &&
             github.event.workflow_run.conclusion == 'success' &&
-            github.event.workflow_run.event == 'push' &&
-            github.event.workflow_run.head_branch == 'main' &&
+            (
+              github.event.workflow_run.event == 'push' ||
+              github.event.workflow_run.event == 'workflow_dispatch'
+            ) &&
+            (
+              github.event.workflow_run.head_branch == 'main' ||
+              github.event.workflow_run.head_branch == 'release'
+            ) &&
             github.event.workflow_run.head_repository.full_name == github.repository
           ) ||
-          (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
+          (
+            github.event_name == 'workflow_dispatch' &&
+            (
+              github.ref == 'refs/heads/main' ||
+              github.ref == 'refs/heads/release'
+            )
+          )
         )
       }}
     runs-on: ubuntu-24.04
@@ -47,6 +58,26 @@ jobs:
           ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.ref }}
           fetch-depth: 1
 
+      - name: Select the mutable image tag
+        id: image
+        env:
+          SOURCE_BRANCH: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || github.ref_name }}
+        run: |
+          case "$SOURCE_BRANCH" in
+            main)
+              tag=main
+              ;;
+            release)
+              tag=next
+              ;;
+            *)
+              echo "Unsupported source branch: $SOURCE_BRANCH" >&2
+              exit 1
+              ;;
+          esac
+          echo "branch=$SOURCE_BRANCH" >> "$GITHUB_OUTPUT"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
       - uses: ./.github/actions/install
 
       - name: Install system dependencies
@@ -86,26 +117,30 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      # A slower CI run for an older main commit can finish after a newer
-      # one. Do not let that run replace the newer image.
-      - name: Verify main has not advanced
-        id: main-sha
+      # A slower CI run for an older commit can finish after a newer one. Do
+      # not let that run replace the newer branch image.
+      - name: Verify the source branch has not advanced
+        id: branch-sha
+        env:
+          SOURCE_BRANCH: ${{ steps.image.outputs.branch }}
         run: |
-          git fetch --no-tags --depth=1 origin main
-          if [[ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]]; then
-            echo "main advanced while this image was building; skipping the push"
+          git fetch --no-tags --depth=1 origin "$SOURCE_BRANCH"
+          if [[ "$(git rev-parse HEAD)" != "$(git rev-parse FETCH_HEAD)" ]]; then
+            echo "$SOURCE_BRANCH advanced while this image was building; skipping the push"
             echo "current=false" >> "$GITHUB_OUTPUT"
           else
             echo "current=true" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Build and push the main image
-        if: steps.main-sha.outputs.current == 'true'
+      - name: Build and push the branch image
+        if: steps.branch-sha.outputs.current == 'true'
+        env:
+          IMAGE_TAG: ${{ steps.image.outputs.tag }}
         run: |
           docker buildx build \
             --platform linux/amd64 \
             --push \
             --provenance=false \
-            --tag ghcr.io/cloudflare/computer-computerd-linux-x64:main \
+            --tag "ghcr.io/cloudflare/computer-computerd-linux-x64:$IMAGE_TAG" \
             --file packages/computer-computerd-linux-x64/Dockerfile \
             packages/computer-computerd-linux-x64

.github/workflows/release.yml

@@ -1,11 +1,14 @@
 # Changesets-driven release. A green CI run on main either opens/updates the
-# changesets Version Packages PR, or publishes the release after that PR merges.
+# Version Packages PR, or publishes the release after that PR merges.
 #
 # Version PR path:
 #   - contributors commit `.changeset/*.md` files;
-#   - changesets/action runs `.github/changeset-version.mjs`;
-#   - the Version Packages PR commits package versions, changelogs, lockfile
-#     updates, and the Dockerfile/docs pins for the computerd image.
+#   - `.github/changeset-version.mjs` applies the pending versions;
+#   - create-pull-request commits those changes to the `release` branch;
+#   - the Version Packages PR includes package versions, changelogs, lockfile
+#     updates, and the Dockerfile/docs pins for the computerd image;
+#   - this workflow dispatches CI on `release`, which publishes the package
+#     preview and lets the branch image workflow publish `:next`.
 #
 # Publish path:
 #   - no pending changesets remain on main;
@@ -34,6 +37,8 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 30
     permissions:
+      # The version path dispatches CI for the release branch.
+      actions: write
       # Trusted publishing on npm requires the OIDC id-token.
       id-token: write
       # changesets/action creates the version PR, release commit, and tags.
@@ -84,6 +89,43 @@ jobs:
             echo "present=false" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Version packages
+        if: steps.pending-changesets.outputs.present == 'true'
+        run: node .github/changeset-version.mjs
+
+      # changesets/action fixes its branch name to changeset-release/<base>.
+      # Use create-pull-request so the stable Version Packages branch is the
+      # shorter `release` name.
+      - name: Create or update the Version Packages PR
+        id: version-pr
+        if: steps.pending-changesets.outputs.present == 'true'
+        uses: peter-evans/create-pull-request@v8
+        with:
+          branch: release
+          base: main
+          commit-message: Version Packages
+          committer: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
+          author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
+          title: Version Packages
+          body: |
+            This pull request applies the pending changesets to package versions,
+            changelogs, the lockfile, and computerd image pins. Merge it to publish
+            the release.
+
+      - name: Close the old Version Packages PR
+        if: steps.version-pr.outputs.pull-request-number
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION_PR: ${{ steps.version-pr.outputs.pull-request-number }}
+        run: |
+          old_pr="$(gh pr list --repo "$GITHUB_REPOSITORY" --state open \
+            --base main --head changeset-release/main --json number \
+            --jq '.[0].number // empty')"
+          if [[ -n "$old_pr" ]]; then
+            gh pr close "$old_pr" --repo "$GITHUB_REPOSITORY" --delete-branch \
+              --comment "Superseded by #$VERSION_PR after the release branch was renamed."
+          fi
+
       # The following Docker setup is only needed on the publish path. The
       # Version Packages PR path should not need registry credentials.
       - name: Set up buildx
@@ -110,10 +152,18 @@ jobs:
             -u "$CF_REGISTRY_USERNAME" --password-stdin
 
       - id: changesets
+        if: steps.pending-changesets.outputs.present == 'false'
         uses: changesets/action@v1
         with:
-          version: node .github/changeset-version.mjs
           publish: node .github/changeset-publish.mjs
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_CONFIG_PROVENANCE: "true"
+
+      # A branch update made with GITHUB_TOKEN cannot trigger a push workflow.
+      # workflow_dispatch is exempt from that recursion guard.
+      - name: Run CI on the version branch
+        if: steps.pending-changesets.outputs.present == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run ci.yml --ref release

COLLABORATORS.md

@@ -144,11 +144,15 @@ Once your pull request merges to `main`, the release workflow takes
 over in two steps:
 
 1. It gathers the pending changesets into a "Version Packages" pull
-   request that bumps package versions, rewrites changelogs, and updates
-   Dockerfile and documentation pins for the `computerd` image. Private
-   packages such as `@cloudflare/dofs`, `@cloudflare/computer-rpc`, and
+   request from the `release` branch. That pull request bumps package
+   versions, rewrites changelogs, and updates Dockerfile and documentation
+   pins for the `computerd` image. Private packages such as
+   `@cloudflare/dofs`, `@cloudflare/computer-rpc`, and
    `@cloudflare/computerd` are versioned and get changelogs, but are not
-   published to npm.
+   published to npm. Each update publishes a package preview through
+   `pkg.pr.new` and the mutable
+   `ghcr.io/cloudflare/computer-computerd-linux-x64:next` image after CI
+   passes.
 2. Merging that pull request first builds and pushes the `computerd`
    binary image to `ghcr.io` and `registry.cloudflare.com`, then publishes
    public npm packages. Rerunning a failed publish is safe: existing image

packages/computer-computerd-linux-x64/README.md

@@ -35,10 +35,12 @@ ENTRYPOINT ["/usr/local/bin/computerd"]
 ```
 
 Pin the image version explicitly. `latest` is fine for experimentation but
-can bite when wire-protocol changes land. The `Main computerd image` workflow
-also publishes `ghcr.io/cloudflare/computer-computerd-linux-x64:main` after
-successful CI on `main`; use that mutable tag only for tests and examples
-that intentionally track the branch.
+can bite when wire-protocol changes land. The `Computerd branch image`
+workflow publishes `ghcr.io/cloudflare/computer-computerd-linux-x64:main`
+after successful CI on `main` and
+`ghcr.io/cloudflare/computer-computerd-linux-x64:next` after successful CI on
+the `release` branch. Use these mutable tags only for tests and examples that
+intentionally track their branches.
 
 ## Configuration