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:

1. Validate version format
2. Create branch rel-<version>
3. Run make set-package-version version=<version> across all packages
4. Update the sdk_ref default in the eval workflow
5. Open a PR titled "Release v\<version\>" with labels

integration-test, behavior-test, test-examples, and security-scan

1. Notify #proj-agent with the release PR link and workflow actor

⏸ 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 — Checks Must Pass

The release PR triggers three labeled test suites and a security scan. All four must pass.

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:

# Find the run ID
gh run list --repo OpenHands/software-agent-sdk \
  --branch "rel-<version>" --limit 5

# Re-run failed jobs
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:

1. create-release.yml detects the merged rel-* branch, creates a

GitHub release with tag v<version> and auto-generated release notes.

1. pypi-release.yml triggers on the published release and publishes

all four packages to PyPI: - openhands-sdk - openhands-tools - openhands-workspace - openhands-agent-server

1. version-bump-prs.yml triggers after successful PyPI publish and

creates downstream version bump PRs.

⏸ Checkpoint — Verify PyPI Publication

# Check each package is available (allow a few minutes for indexing)
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

• Trigger prepare-release.yml with target version
• Verify release PR is created
• Fix deprecation deadline failures (if any)
• Integration tests pass
• Behavior tests pass
• Example tests pass
• Security scan passes
• (Optional) Evaluation run shows no regressions
• 🚨 Get human approval, then merge the release PR
• (Automated) GitHub release created with auto-generated notes
• (Automated) Packages published to PyPI
• (Automated) Downstream version bump PRs created
• Verify packages appear on PyPI
• Send Slack message with downstream version bump PR links