ci: use oasdiff for agent-server REST API breakage detection#2240
Merged
Conversation
Replaced custom Python diffing logic with oasdiff for OpenAPI breaking change detection. The script now: - Uses oasdiff CLI for detecting breaking changes between OpenAPI specs - Still enforces deprecation-before-removal and MINOR version bump policies - Keeps the logic for fetching previous version from PyPI and generating OpenAPI schemas for comparison Co-authored-by: openhands <openhands@all-hands.dev>
Contributor
API breakage checks (Griffe)Result: Passed |
Contributor
Agent server REST API breakage checks (OpenAPI)Result: Passed |
all-hands-bot
approved these changes
Feb 27, 2026
Collaborator
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Taste Rating: 🟢 Good taste
Excellent refactor. Replacing 190 lines of custom OpenAPI diffing with a purpose-built tool (oasdiff) is exactly the right approach. The script keeps the important custom logic (deprecation policies, version bump enforcement) while delegating complex breaking-change detection to a well-maintained tool.
Key Insight: Simplicity wins - use existing tools instead of maintaining custom parsing logic. This is pragmatic engineering.
zparnold
added a commit
to zparnold/software-agent-sdk
that referenced
this pull request
Mar 2, 2026
127 upstream commits merged. 2 conflicts resolved: - .gitignore: kept both upstream api_compliance outputs and our sync marker - vscode_service.py: adopted upstream's config-based server_base_path (replaces our env-var approach — same functionality, cleaner design) Upstream lint fixes applied: - Line length violations in build.py, llm.py, test_llm_config.py - Enum str inheritance (ruff unsafe-fixes) Upstream test fixes: - Removed test_check_agent_server_rest_api_breakage.py (references OperationKey removed in OpenHands#2240 oasdiff rewrite) - Fixed test_model -> check_model rename in test_resolve_model_config.py Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR replaces the custom Python diffing logic with oasdiff for OpenAPI breaking change detection in the agent-server REST API breakage workflow.
Changes
Updated script (
.github/scripts/check_agent_server_rest_api_breakage.py):oasdiff breakingto detect breaking changes between OpenAPI specsUpdated workflow (
.github/workflows/agent-server-rest-api-breakage.yml):Updated documentation (
openhands-agent-server/AGENTS.md):Rationale
As mentioned in PR #2232 comment, oasdiff is a purpose-built tool for OpenAPI breaking-change detection. While it doesn't replace the entire workflow (we still need custom logic for PyPI fetching and policy enforcement), using it for the actual diffing provides:
The custom policy enforcement (deprecation-before-removal and MINOR version bump) is preserved.
Co-authored-by: openhands openhands@all-hands.dev
Agent Server images for this PR
• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server
Variants & Base Images
eclipse-temurin:17-jdknikolaik/python-nodejs:python3.12-nodejs22golang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:32701f0-pythonRun
All tags pushed for this build
About Multi-Architecture Support
32701f0-python) is a multi-arch manifest supporting both amd64 and arm6432701f0-python-amd64) are also available if needed