| name | sdk-release |
| description | This skill should be used when the user asks to "release the SDK", "prepare a release", "publish a new version", "cut a release", "do a release", or mentions the SDK release checklist or release process. Guides through the full software-agent-sdk release workflow from version bump to PyPI publication, emphasizing human checkpoints. |
SDK Release Guide
This skill walks through the software-agent-sdk release process step by step.
🚨 CRITICAL: NEVER merge the release PR or create/publish a GitHub
release without the human's explicit approval. Release is the last line
of human defense. Always present the current status and ask for
confirmation before performing any irreversible action.
Phase 1: Trigger the Prepare-Release Workflow
Determine the target version (SemVer X.Y.Z). Then trigger the
prepare-release.yml workflow, which creates a release branch and PR
automatically.
Via GitHub UI
Navigate to
https://github.com/OpenHands/software-agent-sdk/actions/workflows/prepare-release.yml,
click Run workflow, enter the version (e.g. 1.16.0), and run it.
Via GitHub API
curl -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
"https://api.github.com/repos/OpenHands/software-agent-sdk/actions/workflows/prepare-release.yml/dispatches" \
-d '{
"ref": "main",
"inputs": {
"version": "1.16.0"
}
}'
The workflow will:
- Validate version format
- Create branch
rel-<version>
- Run
make set-package-version version=<version> across all packages
- Update the
sdk_ref default in the eval workflow
- Open a PR titled "Release v<version>" with labels
integration-test, behavior-test, and test-examples
⏸ Checkpoint — Confirm PR Created
Verify the PR exists and the version changes look correct before continuing.
gh pr list --repo OpenHands/software-agent-sdk \
--head "rel-<version>" --json number,title,url
Phase 2: Address Deprecation Deadlines
The deprecation-check CI job runs on every PR. If the release version
crosses any deprecation deadline declared in the codebase, the check will
fail.
Review the failing check output and either:
- Remove the deprecated code if the deadline has passed, or
- Extend the deadline with justification.
Push fixes to the release branch. The check must pass before merging.
Phase 3: Wait for CI — Tests Must Pass
The release PR triggers three labeled test suites. All three must pass.
| Label | Suite | What it covers |
|---|
integration-test | Integration tests | End-to-end agent scenarios |
behavior-test | Behavior tests | Agent behavioral guardrails |
test-examples | Example tests | All runnable examples in examples/ |
Monitor status:
gh pr checks <PR_NUMBER> --repo OpenHands/software-agent-sdk
⏸ Checkpoint — Human Judgment on Failures
Some test failures may be pre-existing or flaky. Decide with the team
whether each failure is:
- Blocking — must fix before release
- Known / pre-existing — acceptable to release with a follow-up issue
- Flaky — re-run the workflow
Re-run failed jobs:
gh run list --repo OpenHands/software-agent-sdk \
--branch "rel-<version>" --limit 5
gh run rerun <RUN_ID> --repo OpenHands/software-agent-sdk --failed
Phase 4: Run Evaluation (Optional but Recommended)
Trigger an evaluation run on SWE-bench (or another benchmark) against the
release branch to catch regressions. See the run-eval skill for full
details.
curl -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
"https://api.github.com/repos/OpenHands/software-agent-sdk/actions/workflows/run-eval.yml/dispatches" \
-d '{
"ref": "main",
"inputs": {
"benchmark": "swebench",
"sdk_ref": "v<version>",
"eval_limit": "50",
"reason": "Pre-release eval for v<version>",
"allow_unreleased_branches": "true"
}
}'
⏸ Checkpoint — Evaluate Results
Compare the eval results against the previous release. Significant score
drops should block the release.
Phase 5: Merge the Release PR
🚨 STOP — Do NOT merge without explicit human approval.
Present the CI status summary and ask the human to confirm before merging.
Merging is effectively irreversible — it automatically triggers the full
release pipeline (GitHub release → PyPI publish → downstream version bumps).
Once the human approves:
gh pr merge <PR_NUMBER> --repo OpenHands/software-agent-sdk --merge
Phase 6: Automated Release Pipeline (no action needed)
When the release PR is merged, the following happens automatically:
create-release.yml detects the merged rel-* branch, creates a
GitHub release with tag v<version> and auto-generated release notes.pypi-release.yml triggers on the published release and publishes
all four packages to PyPI:
openhands-sdkopenhands-toolsopenhands-workspaceopenhands-agent-server
version-bump-prs.yml triggers after successful PyPI publish and
creates downstream version bump PRs.
⏸ Checkpoint — Verify PyPI Publication
for pkg in openhands-sdk openhands-tools openhands-workspace openhands-agent-server; do
curl -s -o /dev/null -w "$pkg: %{http_code}\n" \
"https://pypi.org/pypi/$pkg/<version>/json"
done
All should return 200.
Phase 7: Post-Release Announcements
After the automated pipeline completes, compose a Slack message for the
human to post, including links to the downstream version bump PRs:
🚀 *SDK v<version> published to PyPI!*
Version bump PRs:
• <https://github.com/All-Hands-AI/OpenHands/pulls?q=is%3Apr+bump-sdk-<version>|OpenHands>
• <https://github.com/OpenHands/openhands-cli/pulls?q=is%3Apr+bump-sdk-<version>|OpenHands-CLI>
Release: <https://github.com/OpenHands/software-agent-sdk/releases/tag/v<version>|v<version>>
See references/post-release-checklist.md for details on reviewing
downstream PRs and handling any issues.
Quick Reference — Full Checklist
