---
name: openhands-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."
license: "MIT"
metadata:
  decimalai-skill-id: "50819a0d-0a40-4ca0-a5ca-4178005b3941"
  decimalai-version-id: "095a2550-8320-488c-bd46-db5772686d98"
  decimalai-version: "1"
  decimalai-body-sha256: "7203f6d39c0856b1409e8bf3252ec78203414c0b7818636105e5bbd21c36557e"
  decimalai-name: "openhands/sdk-release"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "devops"
  decimalai-source: "https://app.decimal.ai/s/openhands-sdk-release@1/SKILL.md"
---
# 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

```bash
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`
6. 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.

```bash
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.**

| 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/` |
| `security-scan` | Release security scan | Approval drift and dependency diff checks |

Monitor status:

```bash
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:

```bash
# 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.

```bash
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:

```bash
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.
2. **`pypi-release.yml`** triggers on the published release and publishes
   all four packages to PyPI:
   - `openhands-sdk`
   - `openhands-tools`
   - `openhands-workspace`
   - `openhands-agent-server`
3. **`version-bump-prs.yml`** triggers after successful PyPI publish and
   creates downstream version bump PRs.

### ⏸ Checkpoint — Verify PyPI Publication

```bash
# 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