Add simple version tags (e.g., 1.2.0-python) to agent-server Docker images on release

[xingyaoww]

Summary

Currently, when we release a new version (e.g., v1.2.0), the agent-server Docker images are tagged with complex versioned tags like v1.2.0_python-nodejs-python3.12-nodejs22 but not with simpler version-based tags like 1.2.0-python.

Current Behavior

When a git tag like v1.2.0 is pushed:

• The workflow triggers and passes --versioned-tag to build.py
• Images are tagged with the format: v{SDK_VERSION}_{BASE_IMAGE_SLUG} (e.g., v1.2.0_python-nodejs-python3.12-nodejs22)
• Images are also tagged with commit-based tags like {SHORT_SHA}-python
• Images on main branch get main-python, latest-python tags

Proposed Enhancement

Add simpler, more intuitive version tags for releases:

• 1.2.0-python (or v1.2.0-python)
• 1.2.0-java (or v1.2.0-java)
• 1.2.0-golang (or v1.2.0-golang)

This would make it easier for users to:

1. Pull specific versions by simply using ghcr.io/openhands/agent-server:1.2.0-python
2. Understand which version they're using without parsing complex base image slugs
3. Follow common Docker image tagging conventions

Implementation Considerations

The build.py script already has infrastructure for custom tags via custom_tag_list. We could:

1. Option A: Modify the versioned_tag property to also generate simpler tags when triggered by a git tag
2. Option B: Add an additional tag format specifically for release tags that follows the pattern {VERSION}-{VARIANT}
3. Option C: Keep the existing complex versioned tags but add these simpler tags alongside them

Related Files

• .github/workflows/server.yml - Lines 240-244 handle --versioned-tag flag for git tags
• openhands-agent-server/openhands/agent_server/docker/build.py - Lines 382-383 define the versioned_tag format

Additional Context

Users looking for agent-server images currently see:

• ✅ latest-python - Clear what this is
• ✅ main-python - Clear what this is
• ❓ v1.2.0_python-nodejs-python3.12-nodejs22 - Not immediately clear, hard to remember
• ❌ 1.2.0-python - This is what users would expect but doesn't exist

Having consistent, predictable version tags would improve user experience and align with Docker image tagging best practices.

[xingyaoww]

@OpenHands we should just modify the versioned tag to return {version}-{t} for all t in custom tag lists. We should not set base_image_slug for versioned tag

[openhands-ai]

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

[openhands-ai]

Summary

I've successfully implemented the requested changes to modify the versioned tag system for agent-server Docker images.

✅ Changes Made

Modified build.py:

1. Changed versioned_tag property to versioned_tags (returns list[str] instead of single string)
2. Updated tag format from v{SDK_VERSION}_{BASE_IMAGE_SLUG} to {SDK_VERSION}-{TAG} for each custom tag
3. Removed base_image_slug dependency from versioned tags (as requested)
4. Removed "v" prefix from version numbers for cleaner tags
5. Updated all_tags property to iterate over versioned_tags list
6. Updated GitHub Actions outputs to use versioned_tags_csv instead of versioned_tag

Added comprehensive tests:

• 9 new test functions in test_docker_build.py
• Coverage for single/multiple tags, arch/target suffixes, enable/disable flags
• All 21 docker build tests pass ✅

📊 Before vs After

Before:

v1.2.0_python-nodejs-python3.12-nodejs22

After:

1.2.0-python
1.2.0-java
1.2.0-golang

🔍 Example Output

With custom_tags="python,java,golang" and sdk_version="1.2.0":

• versioned_tags: ['1.2.0-python', '1.2.0-java', '1.2.0-golang']
• Users can now pull images with: ghcr.io/openhands/agent-server:1.2.0-python

🚀 Pull Request

Created PR: #1197

The PR includes:

• Implementation changes in build.py
• 9 comprehensive unit tests
• All pre-commit hooks pass (pyright, ruff, pycodestyle)
• Detailed PR description explaining the changes and benefits

Fixes issue #1195 as requested by @xingyaoww

_{View full conversation}