Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: add release skill and create-release workflow (#900)

Rohit Malhotrab7e5882b767c
diff --git a/.agents/skills/release.md b/.agents/skills/release.md
new file mode 100644
index 0000000000..b478be04e0
--- /dev/null
+++ b/.agents/skills/release.md
@@ -0,0 +1,191 @@
+---
+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.
+triggers:
+- release
+- new release
+- cut a release
+- publish release
+- bump version
+---
+
+# 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.
+
+## Step 1: Check Current Version and Ask the User
+
+**IMPORTANT: You MUST complete this step and get explicit user confirmation before doing anything else.**
+
+First, read the current version from `package.json`:
+
+```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`
+
+**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
+
+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.
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b rel-<version>
+```
+
+### 2b. Bump the version
+
+Update the version in **both** `package.json` and `package-lock.json`:
+
+```bash
+npm version <version> --no-git-tag-version
+```
+
+This updates both files without creating a git tag (the tag is created automatically on merge).
+
+Verify the change:
+
+```bash
+git diff --stat
+# Should show: package.json and package-lock.json changed
+```
+
+### 2c. Commit and push
+
+```bash
+git add package.json package-lock.json
+git commit -m "chore: bump version to <version>"
+git push -u origin rel-<version>
+```
+
+### 2d. Create the PR
+
+Create the PR targeting `main` with the `e2e-tests` label:
+
+```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
+- [ ] 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"
+```
+
+## 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
+
+Once all checks pass and the PR is approved, merge it:
+
+```bash
+gh pr merge <pr-number> --squash --delete-branch
+```
+
+### Automatic tagging on merge
+
+The `create-release.yml` workflow automatically runs when a PR from a `rel-*` branch is merged into `main`. It will:
+
+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:
+
+| 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` |
+
+### Verify the release
+
+After merging, verify the downstream workflows complete successfully:
+
+```bash
+# Check the GitHub release was created
+gh 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
+```
+
+Confirm the package is available:
+- **npm**: `npm view @openhands/agent-canvas@<version>`
+- **Docker**: `docker pull ghcr.io/openhands/agent-canvas:<version>`
+
+## 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.
+
+### 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:
+```bash
+gh release delete v<version> --yes
+git push origin :refs/tags/v<version>
+```
+
+### 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
diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml
new file mode 100644
index 0000000000..9d6d82ac35
--- /dev/null
+++ b/.github/workflows/create-release.yml
@@ -0,0 +1,111 @@
+---
+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.
+
+on:
+ pull_request:
+ types: [closed]
+ branches: [main]
+
+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.04
+ permissions:
+ contents: write
+ pull-requests: read
+ steps:
+ - name: Extract version from branch name
+ id: version
+ env:
+ PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
+ run: |
+ BRANCH="$PR_HEAD_REF"
+ VERSION="${BRANCH#rel-}"
+
+ # Accept semver with optional pre-release suffix (e.g. 1.0.0, 1.0.0-alpha.8)
+ if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+ echo "❌ Could not extract valid version from branch: $BRANCH"
+ exit 1
+ fi
+
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+ echo "πŸ“¦ Version: $VERSION"
+
+ - name: Check release does not already exist
+ id: check
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ VERSION: ${{ steps.version.outputs.version }}
+ run: |
+ if gh release view "v${VERSION}" --repo "${{ github.repository }}" > /dev/null 2>&1; then
+ echo "⚠️ Release v${VERSION} already exists, skipping"
+ echo "exists=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "exists=false" >> "$GITHUB_OUTPUT"
+ fi
+
+ - name: Find previous release tag
+ if: steps.check.outputs.exists == 'false'
+ id: prev_tag
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ PREV_TAG=$(gh release list --repo "${{ github.repository }}" \
+ --exclude-drafts --limit 1 \
+ --json tagName --jq '.[0].tagName')
+ echo "prev_tag=${PREV_TAG}" >> "$GITHUB_OUTPUT"
+ echo "πŸ“Œ Previous release tag: ${PREV_TAG:-<none>}"
+
+ - name: Create GitHub Release
+ if: steps.check.outputs.exists == 'false'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ VERSION: ${{ steps.version.outputs.version }}
+ PREV_TAG: ${{ steps.prev_tag.outputs.prev_tag }}
+ run: |
+ NOTES_START_FLAG=()
+ if [ -n "$PREV_TAG" ]; then
+ NOTES_START_FLAG=(--notes-start-tag "$PREV_TAG")
+ fi
+
+ # Detect pre-release versions (anything with a hyphen, e.g. 1.0.0-alpha.8)
+ PRERELEASE_FLAG=()
+ if [[ "$VERSION" == *-* ]]; then
+ PRERELEASE_FLAG=(--prerelease)
+ fi
+
+ gh release create "v${VERSION}" \
+ --repo "${{ github.repository }}" \
+ --target "${{ github.event.pull_request.merge_commit_sha }}" \
+ --title "v${VERSION}" \
+ --generate-notes \
+ "${NOTES_START_FLAG[@]}" \
+ "${PRERELEASE_FLAG[@]}"
+
+ echo "βœ… Release v${VERSION} created!"
+ echo "πŸ”— https://github.com/${{ github.repository }}/releases/tag/v${VERSION}"
+
+ - name: Summary
+ if: steps.check.outputs.exists == 'false'
+ env:
+ VERSION: ${{ steps.version.outputs.version }}
+ run: |
+ echo "## βœ… Release v${VERSION} 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 "" >> "$GITHUB_STEP_SUMMARY"
+ echo "### Triggered Downstream Workflows" >> "$GITHUB_STEP_SUMMARY"
+ echo "The tag push \`v${VERSION}\` will automatically trigger:" >> "$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/AGENTS.md b/AGENTS.md
index 5769b73141..abc5f05320 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -528,4 +528,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.
+
- 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.