ci: API breakage checks for SDK (Griffe) and REST (oasdiff)

[enyst]

This PR adds API breakage checks to run on release PRs.

What’s included

• SDK programmatic API check using Griffe

  • .github/scripts/check_sdk_api_breakage.py
  • Compares current workspace openhands-sdk against the previous PyPI release
  • Defaults to include openhands.sdk; override with SDK_INCLUDE_PATHS
  • Prints GitHub-friendly explanations and only considers public API
  • Policy: If breaking changes are detected, require a MINOR version bump (not MAJOR)

• REST OpenAPI diff using oasdiff

  • .github/scripts/check_rest_api_breakage.py
  • Generates OpenAPI JSON for old and new:
    • Old: installs previous PyPI release of openhands-agent-server in a temp venv and calls api.openapi()
    • New: imports local server and calls generate_openapi_schema()
  • Runs ghcr.io/tufin/oasdiff:latest breaking to detect breaking changes
  • Policy: breaking REST changes require a MAJOR bump

• Workflow

  • .github/workflows/api-breakage.yml
  • Two jobs (sdk, rest) run on PRs to main and release/*
  • Installs griffe via uv and runs the SDK script
  • Runs REST script; requires Docker on runner for oasdiff

Notes

• You can scope SDK checks by setting SDK_INCLUDE_PATHS to a comma-separated list of modules/classes to track.
• The SDK policy follows the request: breaking public API changes force at least a MINOR bump.
• The REST policy defaults to requiring a MAJOR bump on breaking OpenAPI changes; we can adjust if desired.

Co-authored-by: openhands openhands@all-hands.dev

@enyst can click here to continue refining the PR

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:7b2abca-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-7b2abca-python \
  ghcr.io/openhands/agent-server:7b2abca-python

All tags pushed for this build

ghcr.io/openhands/agent-server:7b2abca-golang-amd64
ghcr.io/openhands/agent-server:7b2abca-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:7b2abca-golang-arm64
ghcr.io/openhands/agent-server:7b2abca-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:7b2abca-java-amd64
ghcr.io/openhands/agent-server:7b2abca-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:7b2abca-java-arm64
ghcr.io/openhands/agent-server:7b2abca-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:7b2abca-python-amd64
ghcr.io/openhands/agent-server:7b2abca-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:7b2abca-python-arm64
ghcr.io/openhands/agent-server:7b2abca-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:7b2abca-golang
ghcr.io/openhands/agent-server:7b2abca-java
ghcr.io/openhands/agent-server:7b2abca-python

About Multi-Architecture Support

• Each variant tag (e.g., 7b2abca-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 7b2abca-python-amd64) are also available if needed

[enyst]

OpenHands-GPT-5 here — suggestion on scoping SDK API breakage checks.

To avoid over-constraining internals and to align with a curated public surface, please scope the SDK API check to the symbols exported from the public module(s), rather than scanning deep subpackages:

Recommended options:

1. Rely on package-level exports of openhands.sdk (preferred)

   • Set SDK_INCLUDE_PATHS=openhands.sdk so Griffe inspects only the public surface (governed by all).
   • Alternatively, the script can import openhands.sdk and programmatically read all to derive the explicit list of symbols to verify.

2. Expand the tracked surface only as stability commitments grow

   • Start with the few critical types (e.g., ConversationExecutionStatus) and add more over time.
   • This keeps internals free to evolve without breaking downstream dependents.

Context:

• A separate PR proposes exporting ConversationExecutionStatus via openhands.sdk and openhands.sdk.conversation to formalize it as part of the public API.
• This approach pairs well with the CI checks: the breakage job validates just the curated export surface.

Happy to help wire the all-based resolution in the check_sdk_api_breakage.py script if useful.

[enyst]

@OpenHands split this PR in two:

• keep here the SDK checks
• make a new branch from main and add there the REST/agent-server/oasdiff side of it

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[openhands-ai]

Summary of work completed

Goal

• Split existing PR so that:
  • Current PR keeps only the SDK API breakage checks
  • A new branch from main contains the REST/agent-server/oasdiff checks

Actions taken

• Updated current PR branch ci/api-breakage (SDK-only)

  • Removed REST files:
    • Deleted .github/scripts/check_rest_api_breakage.py
    • Deleted .github/oasdiff.yaml
  • Edited .github/workflows/api-breakage.yml to keep only the SDK Griffe job
  • Ran pre-commit on modified workflow; all checks passed
  • Pushed changes
  • Commit: 186c3a6 ci: scope PR to SDK API breakage checks only; remove REST/oasdiff job and scripts

• Created a new branch from main for REST checks

  • Branch: ci/rest-api-breakage (based on origin/main)
  • Added REST check artifacts:
    • .github/scripts/check_rest_api_breakage.py
    • .github/oasdiff.yaml
    • .github/workflows/rest-api-breakage.yml (REST job only)
  • Ran pre-commit on added files; all checks passed
  • Pushed branch
  • Commit: 1f8da74 ci: split REST OpenAPI breakage check into its own workflow and branch
  • Create PR link: https://github.com/OpenHands/software-agent-sdk/pull/new/ci/rest-api-breakage

Checklist

• Current PR contains only SDK checks
• New branch created from main with REST/oasdiff checks
• Pre-commit checks run and passed on all modified/added files
• Changes are minimal and targeted to the request
• All changes pushed; no extra or unrelated edits

Notes

• The REST script currently enforces a MINOR version bump on breaking changes (matching the previous guidance). If you prefer requiring a MAJOR bump for REST changes, I can adjust the policy.
• I haven’t opened a PR for ci/rest-api-breakage yet; let me know if you want me to open it and cross-reference the SDK PR.

_{View full conversation}