π OpenHands: AI-Driven Development
chore: switch to tag-based release workflow with per-tier npm dist-tags (#996)
Tim O'Farrell1d4fd1525cef
diff --git a/.agents/skills/release.md b/.agents/skills/release.mdindex 951d7f2409..1235c41460 100644--- a/.agents/skills/release.md+++ b/.agents/skills/release.md@@ -1,6 +1,6 @@---name: release-description: Guide the release process for @openhands/agent-canvas β version bump PR, E2E validation, merge with automatic tagging, and downstream npm/Docker publishing.+description: Guide the release process for @openhands/agent-canvas β version bump on the release branch, QA, then tag to publish to npm and Docker.triggers:- release- new release@@ -11,191 +11,143 @@ triggers:# Release Process for @openhands/agent-canvas-You are guiding a release of the `@openhands/agent-canvas` package. Follow these steps **in order**. Do NOT skip ahead β each step has a checkpoint where you must wait for the user.+## Overview-## Step 1: Check Current Version and Ask the User+Releases use a **long-lived release branch** model:-**IMPORTANT: You MUST complete this step and get explicit user confirmation before doing anything else.**+1. A `rel-X.Y.Z` branch is created from `main` at the start of a release cycle.+2. QA and fixes land on the branch (cherry-picked from main or landed directly).+3. When ready, a tag (`vX.Y.Z-rc.1`, `vX.Y.Z`, etc.) is pushed to the branch.+4. The tag push triggers all downstream workflows automatically.+5. **The release branch is never merged back to main.**-First, read the current version from `package.json`:+npm dist-tags by version tier:-```bash-node -p "require('./package.json').version"-```--Then present the result to the user and suggest the next logical version. Use these rules to form your suggestion:-- If the current version is a pre-release like `1.0.0-alpha.7`, suggest `1.0.0-alpha.8` (bump the last numeric segment).-- If the current version is stable like `1.2.3`, suggest `1.2.4` (patch bump) but mention they can also do `1.3.0` (minor) or `2.0.0` (major).--**Version format**: This project uses semver with optional pre-release suffixes.-- Pre-release examples: `1.0.0-alpha.8`, `1.0.0-beta.1`, `1.0.0-rc.1`-- Stable examples: `1.0.0`, `1.1.0`, `2.0.0`+| Version | Example | npm dist-tag | `npm install` resolves? |+|---|---|---|---|+| Alpha | `1.0.0-alpha.1` | `alpha` | `@alpha` only |+| Beta | `1.0.0-beta.1` | `beta` | `@beta` only |+| RC | `1.0.0-rc.1` | `rc` | `@rc` only |+| Stable | `1.0.0` | `latest` | β default |-**STOP HERE.** Tell the user the current version, your suggested next version, and ask:--> The current version is `<current>`. I'd suggest bumping to `<suggested>`. What version would you like to release?--**Do not proceed to Step 2 until the user confirms a version.**--## Step 2: Create the Release PR+----### 2a. Create the release branch+## Step 1: Confirm the Release Branch Exists-The branch **must** be named `rel-<version>` (e.g., `rel-1.0.0-alpha.8`). This naming convention is required β the `create-release.yml` workflow detects merged release PRs by matching the `rel-` branch prefix.+The branch must be named `rel-X.Y.Z` (e.g. `rel-1.0.0`). Check:```bash-git checkout main-git pull origin main-git checkout -b rel-<version>+git branch -r | grep rel-```-### 2b. Bump the version--Update the version in **both** `package.json` and `package-lock.json`:+If it doesn't exist yet, create it from main:```bash-npm version <version> --no-git-tag-version+git checkout main && git pull origin main+git checkout -b rel-<X.Y.Z>+git push -u origin rel-<X.Y.Z>```-This updates both files without creating a git tag (the tag is created automatically on merge).+**STOP HERE if the branch doesn't exist.** Ask the user to confirm the release series (e.g. `1.0.0`) before creating it.-### 2c. Update version references in README.md+----The `README.md` contains Docker image tags that reference a specific version (e.g., `ghcr.io/openhands/agent-canvas:<version>`). Update **all** version references in `README.md` to match the new release version:+## Step 2: Ensure `package.json` Version Is Set-```bash-# Find and replace the old version tag with the new one-sed -i 's/ghcr.io\/openhands\/agent-canvas:[0-9]*\.[0-9]*\.[0-9]*[^ ]*/ghcr.io\/openhands\/agent-canvas:<version>/g' README.md-```+The version in `package.json` must match the tag you're about to push.-Verify the change:+Check the current version:```bash-git diff --stat-# Should show: package.json, package-lock.json, and README.md changed+node -p "require('./package.json').version"```-### 2d. Commit and push+If it needs updating (e.g. bumping from `1.0.0-alpha.8` to `1.0.0-rc.1`), update both `package.json` and `package-lock.json`:```bash-git add package.json package-lock.json README.md-git commit -m "chore: bump version to <version>"-git push -u origin rel-<version>+git checkout rel-<X.Y.Z>+git pull origin rel-<X.Y.Z>+npm version <new-version> --no-git-tag-version+git add package.json package-lock.json+git commit -m "chore: bump version to <new-version>"+git push```-### 2e. Create the PR--Create the PR targeting `main` with the `e2e-tests` label:+**Also update version references in `README.md`** if the Docker image tag examples reference a specific version:```bash-gh pr create \- --title "chore: bump version to <version>" \- --body "## Release v<version>--This PR bumps the version to **<version>** for release.--### Release Checklist-- [x] Version bumped in package.json and package-lock.json-- [x] Version references updated in README.md-- [ ] CI passes (lint, test, build)-- [ ] Visual snapshot tests pass-- [ ] Mock-LLM E2E tests pass (triggered by \`e2e-tests\` label)-- [ ] Review and approve--### What happens on merge-When this PR is merged, the \`create-release.yml\` workflow will automatically:-1. Create a GitHub release with tag \`v<version>\` and auto-generated notes-2. The tag push triggers \`npm-publish.yml\` to publish to npm-3. The tag push triggers \`docker.yml\` to build and push Docker images to GHCR" \- --base main \- --head "rel-<version>" \- --label "e2e-tests"+sed -i 's/ghcr.io\/openhands\/agent-canvas:[0-9]*\.[0-9]*\.[0-9]*[^ ]*/ghcr.io\/openhands\/agent-canvas:<new-version>/g' README.md+git add README.md && git commit -m "docs: update README version to <new-version>" && git push```-## Step 3: Wait for CI and E2E Tests--The following checks must pass before merging:--| Workflow | Trigger | What it checks |-|---|---|---|-| **CI** (`ci.yml`) | Every PR | Lint, unit tests, app build, library build |-| **Snapshot Tests** (`snapshot-tests.yml`) | Every PR | Visual regression screenshots |-| **Mock-LLM E2E Tests** (`mock-llm-e2e.yml`) | `e2e-tests` label | End-to-end tests with a mock LLM against a real agent-server |--Monitor the PR checks:--```bash-gh pr checks <pr-number> --watch-```--If the mock-LLM E2E tests fail, investigate the failure in the workflow artifacts. The `e2e-tests` label can be removed and re-added to re-trigger the workflow.--If snapshot tests show intentional changes (e.g., version string in the UI changed), add the `update-snapshots` label to acknowledge the changes.+----## Step 4: Merge the PR+## Step 3: Push the Tag-Once all checks pass and the PR is approved, merge it:+Confirm the branch is in the right state (CI green, QA done), then push the tag:```bash-gh pr merge <pr-number> --squash --delete-branch+git checkout rel-<X.Y.Z>+git pull origin rel-<X.Y.Z>+git tag v<version>+git push origin v<version>```-### Automatic tagging on merge--The `create-release.yml` workflow automatically runs when a PR from a `rel-*` branch is merged into `main`. It will:+Examples:+- First release candidate: `git tag v1.0.0-rc.1 && git push origin v1.0.0-rc.1`+- Subsequent RC: `git tag v1.0.0-rc.2 && git push origin v1.0.0-rc.2`+- Full release: `git tag v1.0.0 && git push origin v1.0.0`-1. **Extract the version** from the branch name (e.g., `rel-1.0.0-alpha.8` β `1.0.0-alpha.8`)-2. **Create a GitHub release** with tag `v<version>` targeting the merge commit-3. **Auto-generate release notes** from the commits since the previous release-4. **Mark pre-release versions** (those containing a hyphen) as pre-releases--You do **not** need to manually create a tag or GitHub release.--### Downstream workflows triggered by the tag--The tag push (`v*`) automatically triggers:+**The tag push is the release trigger.** Three workflows fire in parallel:| Workflow | What it does ||---|---|-| **npm-publish.yml** | Builds and publishes `@openhands/agent-canvas` to npm with provenance |-| **docker.yml** | Builds and pushes multi-arch Docker images to `ghcr.io/openhands/agent-canvas` |+| `create-release.yml` | Creates the GitHub Release object with auto-generated notes |+| `npm-publish.yml` | Builds and publishes to npm with the correct dist-tag |+| `docker.yml` | Builds and pushes multi-arch Docker images to GHCR |-### Verify the release+----After merging, verify the downstream workflows complete successfully:+## Step 4: Verify the Release```bash-# Check the GitHub release was created+# GitHub releasegh release view v<version>-# Watch downstream workflow runs-gh run list --workflow=npm-publish.yml --limit=1-gh run list --workflow=docker.yml --limit=1+# npm (allow ~2 min for publish to propagate)+npm view @openhands/agent-canvas@<version>+npm view @openhands/agent-canvas dist-tags # confirm correct dist-tag++# Docker+docker pull ghcr.io/openhands/agent-canvas:<version>```-Confirm the package is available:-- **npm**: `npm view @openhands/agent-canvas@<version>`-- **Docker**: `docker pull ghcr.io/openhands/agent-canvas:<version>`+Monitor workflow runs:++```bash+gh run list --workflow=npm-publish.yml --limit=3+gh run list --workflow=docker.yml --limit=3+```++---## Troubleshooting-### E2E tests not triggering-The `e2e-tests` label must be present on the PR. If you added it but tests didn't run, remove and re-add the label, or manually trigger the workflow from the Actions tab.+### package.json version doesn't match the tag+`npm-publish.yml` validates that `package.json` version equals the tag version and fails if they differ. Fix the version on the branch, push, then delete and re-push the tag:+```bash+git push origin :refs/tags/v<version> # delete remote tag+git tag -d v<version> # delete local tag+# fix package.json, commit, push+git tag v<version> && git push origin v<version>+```-### Tag already exists-If a tag `v<version>` already exists (e.g., from a previous failed attempt), the `create-release.yml` workflow will skip creation. Delete the existing release and tag first:+### GitHub release already exists+`create-release.yml` skips silently if the release already exists. To recreate it:```bashgh release delete v<version> --yes-git push origin :refs/tags/v<version>```+Then the workflow will re-create it on the next tag push (or run it manually from the Actions tab).-### npm publish failed-The `npm-publish.yml` workflow validates that `package.json` version matches the tag version. If they don't match, the publish will fail. Ensure the version bump in Step 2b matches the branch name exactly.--## Reference--This release process is modeled after the [OpenHands/software-agent-sdk release workflow](https://github.com/OpenHands/software-agent-sdk/blob/main/.github/workflows/README-RELEASE.md) for consistency across OpenHands projects. Key differences:-- agent-canvas uses npm (not PyPI) for package publishing-- agent-canvas uses `npm version` (not `make set-package-version`) for version bumping-- agent-canvas release branches use `rel-<version>` naming (same as SDK)-- Both repos use `create-release.yml` to auto-create GitHub releases on merge of `rel-*` PRs+### npm publish failed mid-way+Check the `npm-publish.yml` run logs. The dist-tag is resolved from the `package.json` version β if the version string contains `alpha`, `beta`, or `rc`, it uses the matching dist-tag; otherwise `latest`.diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.ymlindex c8707e5d89..45656a1166 100644--- a/.github/workflows/create-release.yml+++ b/.github/workflows/create-release.yml@@ -1,54 +1,46 @@---name: Create GitHub Release-# Automatically create a GitHub release when a release PR is merged into main.-# This bridges the gap between merging the release PR and the downstream-# workflows (npm-publish, docker) which trigger on tag push (v*).-#-# Modeled after OpenHands/software-agent-sdk's create-release.yml for consistency.+# Automatically create a GitHub release object when a v* tag is pushed.+# The tag is pushed manually to a rel-X.Y.Z release branch (never merged to main).+# This workflow creates the GitHub Release; the same tag push also triggers+# npm-publish.yml and docker.yml in parallel.on:- pull_request:- types: [closed]- branches: [main]+ push:+ tags:+ - 'v*'jobs:create-release:- # Only run when a release PR is merged (not just closed)- # and the branch follows the rel-X.Y.Z naming convention.- if: >- github.event.pull_request.merged == true &&- startsWith(github.event.pull_request.head.ref, 'rel-')runs-on: ubuntu-24.04permissions:contents: write- pull-requests: readsteps:- - name: Extract version from branch name+ - name: Extract version from tagid: version- env:- PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}run: |- BRANCH="$PR_HEAD_REF"- VERSION="${BRANCH#rel-}"+ TAG="${GITHUB_REF#refs/tags/}"+ VERSION="${TAG#v}"- # Accept semver with optional pre-release suffix (e.g. 1.0.0, 1.0.0-alpha.8)+ # Accept semver with optional pre-release suffix (e.g. 1.0.0, 1.0.0-rc.1)if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then- echo "β Could not extract valid version from branch: $BRANCH"+ echo "β Could not extract valid version from tag: $TAG"exit 1fiecho "version=$VERSION" >> "$GITHUB_OUTPUT"+ echo "tag=$TAG" >> "$GITHUB_OUTPUT"echo "π¦ Version: $VERSION"- name: Check release does not already existid: checkenv:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}- VERSION: ${{ steps.version.outputs.version }}+ TAG: ${{ steps.version.outputs.tag }}run: |- if gh release view "v${VERSION}" --repo "${{ github.repository }}" > /dev/null 2>&1; then- echo "β οΈ Release v${VERSION} already exists, skipping"+ if gh release view "$TAG" --repo "${{ github.repository }}" > /dev/null 2>&1; then+ echo "β οΈ Release $TAG already exists, skipping"echo "exists=true" >> "$GITHUB_OUTPUT"elseecho "exists=false" >> "$GITHUB_OUTPUT"@@ -69,12 +61,9 @@ jobs:- name: Create GitHub Releaseif: steps.check.outputs.exists == 'false'env:- # Use a PAT (not GITHUB_TOKEN) so the resulting tag-push event- # propagates to downstream workflows (npm-publish.yml, docker.yml).- # Tags created via GITHUB_TOKEN are silently suppressed by GitHub- # and will not trigger other workflow runs.- GH_TOKEN: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC || secrets.GITHUB_TOKEN }}+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}VERSION: ${{ steps.version.outputs.version }}+ TAG: ${{ steps.version.outputs.tag }}PREV_TAG: ${{ steps.prev_tag.outputs.prev_tag }}run: |NOTES_START_FLAG=()@@ -82,34 +71,32 @@ jobs:NOTES_START_FLAG=(--notes-start-tag "$PREV_TAG")fi- # Detect pre-release versions (anything with a hyphen, e.g. 1.0.0-alpha.8)+ # Detect pre-release versions (anything with a hyphen, e.g. 1.0.0-rc.1)PRERELEASE_FLAG=()if [[ "$VERSION" == *-* ]]; thenPRERELEASE_FLAG=(--prerelease)fi- gh release create "v${VERSION}" \+ gh release create "$TAG" \--repo "${{ github.repository }}" \- --target "${{ github.event.pull_request.merge_commit_sha }}" \- --title "v${VERSION}" \+ --title "$TAG" \--generate-notes \"${NOTES_START_FLAG[@]}" \"${PRERELEASE_FLAG[@]}"- echo "β Release v${VERSION} created!"- echo "π https://github.com/${{ github.repository }}/releases/tag/v${VERSION}"+ echo "β Release $TAG created!"+ echo "π https://github.com/${{ github.repository }}/releases/tag/$TAG"- name: Summaryif: steps.check.outputs.exists == 'false'env:- VERSION: ${{ steps.version.outputs.version }}+ TAG: ${{ steps.version.outputs.tag }}run: |- echo "## β Release v${VERSION} Created" >> "$GITHUB_STEP_SUMMARY"+ echo "## β Release $TAG Created" >> "$GITHUB_STEP_SUMMARY"echo "" >> "$GITHUB_STEP_SUMMARY"- echo "- **Tag**: v${VERSION}" >> "$GITHUB_STEP_SUMMARY"- echo "- **Release**: https://github.com/${{ github.repository }}/releases/tag/v${VERSION}" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Tag**: $TAG" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Release**: https://github.com/${{ github.repository }}/releases/tag/$TAG" >> "$GITHUB_STEP_SUMMARY"echo "" >> "$GITHUB_STEP_SUMMARY"- echo "### Triggered Downstream Workflows" >> "$GITHUB_STEP_SUMMARY"- echo "The tag push \`v${VERSION}\` will automatically trigger:" >> "$GITHUB_STEP_SUMMARY"+ echo "Downstream workflows triggered by the same tag push:" >> "$GITHUB_STEP_SUMMARY"echo "- **npm-publish.yml** β publish \`@openhands/agent-canvas\` to npm" >> "$GITHUB_STEP_SUMMARY"echo "- **docker.yml** β build and push \`ghcr.io/openhands/agent-canvas\` Docker images" >> "$GITHUB_STEP_SUMMARY"diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.ymlindex 134fa51b86..bae15a48a7 100644--- a/.github/workflows/npm-publish.yml+++ b/.github/workflows/npm-publish.yml@@ -90,18 +90,29 @@ jobs:fiecho "β Version $PACKAGE_VERSION matches release tag"- # Temporary: publish all versions (including prerelease) as "latest"- # until the first stable release (see cleanup issue #395).- # Note: OIDC trusted-publishing tokens cover only the `npm publish`- # call itself; a separate `npm dist-tag add` after publish fails- # with E401, so we publish directly with --tag latest in one step.- #- # Named prerelease dist-tags (alpha/beta/rc) are intentionally NOT- # published under this policy β only "latest" is used. This means- # `npm install @openhands/agent-canvas@alpha` will not resolve to- # any published version. When prerelease dist-tags need to be- # re-introduced (issue #395 cleanup), update this step to publish- # with a versioned dist-tag (e.g. --tag alpha) and only tag stable- # releases as "latest".+ # Resolve the npm dist-tag from the version's pre-release identifier:+ # alpha β --tag alpha (e.g. 1.0.0-alpha.1)+ # beta β --tag beta (e.g. 1.0.0-beta.1)+ # rc β --tag rc (e.g. 1.0.0-rc.1)+ # stable β --tag latest (e.g. 1.0.0)+ # Note: OIDC trusted-publishing tokens cover only the `npm publish` call+ # itself; a separate `npm dist-tag add` would fail with E401, so the tag+ # is resolved and passed directly in one step.+ - name: Resolve npm dist-tag+ id: dist_tag+ run: |+ VERSION=$(node -p "require('./package.json').version")+ if [[ "$VERSION" == *-alpha* ]]; then+ DIST_TAG="alpha"+ elif [[ "$VERSION" == *-beta* ]]; then+ DIST_TAG="beta"+ elif [[ "$VERSION" == *-rc* ]]; then+ DIST_TAG="rc"+ else+ DIST_TAG="latest"+ fi+ echo "dist_tag=$DIST_TAG" >> "$GITHUB_OUTPUT"+ echo "π¦ Version $VERSION β dist-tag: $DIST_TAG"+- name: Publish to npm with provenance- run: npm publish --access public --provenance --tag latest+ run: npm publish --access public --provenance --tag ${{ steps.dist_tag.outputs.dist_tag }}diff --git a/AGENTS.md b/AGENTS.mdindex 52100f1daa..fcded59e28 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -552,6 +552,6 @@ When adding code that needs a new string, decide up front which rule it falls un- Spec files live under `specs/`. Spec IDs are stable β never renumber. Mark deprecated specs with ~~strikethrough~~. Tag implementation code and tests with `// @spec BM-002 β Short title` comments so specs are grep-able across the codebase (`grep -rn '@spec BM-' src/ __tests__/`). Place the comment on the line immediately above the relevant code block or test. When multiple tests cover the same spec, use `it.each` if the test structure is identical.-- Release automation: `.github/workflows/create-release.yml` automatically creates a GitHub release (with tag `v<version>`) when a PR from a `rel-*` branch is merged into `main`. This is modeled after the SDK's `create-release.yml`. The tag push then triggers `npm-publish.yml` and `docker.yml` downstream. The release skill (`.agents/skills/release.md`, keyword trigger: `release`) guides agents through the full process: version bump PR, `e2e-tests` label for mock-LLM E2E validation, merge with auto-tagging. Pre-release versions (containing a hyphen) are marked as pre-releases on the GitHub release.+- Release automation: releases use a **long-lived release branch** model β a `rel-X.Y.Z` branch is created from `main`, QA/fixes land there, and publishing is triggered by pushing a `v*` tag directly to that branch (the branch is never merged back to main). Tag format determines the npm dist-tag: `alpha` β `alpha`, `beta` β `beta`, `rc` β `rc`, no suffix β `latest`. Three workflows fire in parallel on every `v*` tag push: `create-release.yml` (creates the GitHub Release object with auto-generated notes and marks pre-release for hyphenated versions), `npm-publish.yml` (builds and publishes to npm with the correct dist-tag), and `docker.yml` (builds multi-arch Docker images). The release skill (`.agents/skills/release.md`, keyword trigger: `release`) guides agents through the full process.- Cloud conversation resume gating: when a cloud conversation is closed from the UI (`pauseCloudSandbox` is called), the conversation's `conversation_url` is NOT cleared -- it still points to the old sandbox host. `WebSocketProviderWrapper` must suppress the URL (pass `null` to `ConversationWebSocketProvider`) while `sandbox_status === "PAUSED"`, otherwise the WebSocket immediately tries the stale URL before the sandbox wakes. Symmetrically, `useActiveConversation`'s refetch interval must fast-poll (3 s) on both `!conversation_url` AND `sandbox_status === "PAUSED"` -- checking only the missing URL would leave the hook on the 30 s interval while the sandbox is resuming. The resume sequence: navigate -> sandbox PAUSED detected -> `resumeCloudSandbox` called (in `conversation.tsx`) -> fast-poll detects RUNNING -> `conversationUrl` unblocked -> WebSocket connects.