CI: API breakage checks failing on all PRs due to DockerDevWorkspace.server_image change

[ixchio]

Summary

The API breakage checks (Griffe) are failing on all open PRs due to a breaking change that was merged to main in PR #2243.

Root Cause

PR #2243 (fix: override server_image default to None in DockerDevWorkspace) merged on Feb 28 changed the default value of DockerDevWorkspace.server_image:

# Before (v1.11.4 - released version)
# server_image inherited from parent with default='ghcr.io/openhands/agent-server:latest-python'

# After (v1.11.5-dev - current main)
server_image: str | None = Field(
    default=None,  # ← Breaking change
    description="Pre-built agent server image. Mutually exclusive with base_image.",
)

CI Output

Checking openhands-workspace (openhands.workspace)
Comparing openhands-workspace 1.11.5 against 1.11.4
##[warning] Attribute value was changed: 
  Field(default='ghcr.io/openhands/agent-server:latest-python', ...) 
  -> Field(default=None, ...)
##[error] Breaking changes detected (1); require at least minor version bump from 1.11.x, but new is 1.11.5

Impact

• All open PRs have failing API breakage checks
• Example: PR fix: add security_risk and summary to tool examples for non-native function calling #2251 (which only changes prompt examples) shows this failure

Suggested Fix

One of:

1. Bump version to 1.12.0 to acknowledge the breaking change (recommended if this was intentional)
2. Update the baseline version if v1.11.4 comparison is no longer valid
3. Mark this specific check as non-blocking temporarily while addressing the version

Related

• PR fix: override server_image default to None in DockerDevWorkspace #2243 introduced the change
• PR fix: add security_risk and summary to tool examples for non-native function calling #2251 is blocked by this (unrelated to its actual changes)

[enyst]

Thank you for reporting! I think the check is not mandatory on PRs at this time, so while it fails, it shouldn't cause problems by itself

[ixchio]

This issue can be closed. As @enyst noted, the API breakage check is non-blocking on regular PRs (continue-on-error: true in the workflow).

The check only blocks on release PRs (branches starting with rel-), at which point the version will be properly bumped to 1.12.0 to acknowledge the breaking changes.

The current CI warnings are informational and expected - they help track breaking changes that need to be addressed in the next release, but they do not prevent PRs from being merged.

[enyst]

I reopen, because it should be addressed before the next release.

cc @simonrosenberg Do you know why it broke in that PR?

[ixchio]

Hi @enyst, I can explain the context behind PR #2243.

Why the change was made

The change was intentional to fix a real bug reported in issue #2242. The problem was:

1. DockerDevWorkspace is designed to be used with base_image (to build images on-the-fly)
2. DockerWorkspace (parent class) has server_image defaulting to "ghcr.io/openhands/agent-server:latest-python"
3. The validator requires exactly one of base_image or server_image to be set
4. The bug: When a user calls DockerDevWorkspace(base_image="python:3.13"), it would fail because both base_image AND server_image (inherited default) were non-None

Users had to work around this by explicitly passing server_image=None:

# This workaround was needed before the fix
DockerDevWorkspace(base_image="python:3.13", server_image=None)

Why it's a breaking change

The change makes DockerDevWorkspace() (with no arguments) fail validation, whereas before it would silently use the parent's server_image default. However:

• This edge case is not meaningful — if you want to use a pre-built server image, you should use DockerWorkspace directly
• All real usages pass base_image explicitly (that's the whole point of DockerDevWorkspace)
• The previous behavior was accidentally permissive, not intentional API

Recommended fix for the CI

Since the change is intentional and correct, the proper solution is to bump the version to 1.12.0 before the next release. This acknowledges the breaking change per SemVer.

Note: There are also other breaking changes detected:

• LLM.top_p default changed from 1.0 to None
• Some symbols removed from openhands.tools.__all__ (BrowserToolSet, get_agent_factory, register_agent)

These all need to be addressed in the 1.12.0 release.

[simonrosenberg]

@enyst

I think there are 3 options to fix the CI? 3. seems heavier but recommended

1. Bump to 1.12.0 now — Change the version in pyproject.toml on main. Correct SemVer, silences the warnings immediately. Minimal effort.

2. Do nothing until release — Leave warnings as-is since they're non-blocking on regular PRs. Bump to 1.12.0 only when cutting the rel- branch. Downside: noisy CI on every PR until then.

3. Bump now + audit all breakages — Bump to 1.12.0 and also verify that the other accumulated breaking changes (LLM.top_p, removed symbols from openhands.tools.__all__ like BrowserToolSet, get_agent_factory, register_agent) are intentional. Important: if those symbols were removed without a prior @deprecated marker in v1.11.4, the check will still fail even after the version bump — undeprecated removals are a separate failure condition that a version bump alone doesn't fix.

[all-hands-bot]

[Automatic Post]: This issue has been waiting for triage. @xingyaoww @neubig @enyst, could you please take a look and add the appropriate priority label when you have a chance?

[all-hands-bot]

[Automatic Post]: This issue has been waiting for triage. @xingyaoww @neubig @enyst, could you please take a look and add the appropriate priority label when you have a chance?

[all-hands-bot]

[Automatic Post]: This issue has been waiting for triage. @xingyaoww @neubig @enyst, could you please take a look and add the appropriate priority label when you have a chance?