fix(ci): use SDK_SHA for docker image tags in examples

The built-in GITHUB_SHA resolves to the merge-commit SHA on
pull_request events, which does not match the agent-server image tags
built from the PR head commit.  The agent-server build workflow already
uses SDK_SHA for this reason.

Switch run-examples.yml to export SDK_SHA (matching the server workflow)
and update all remote-agent-server examples to prefer SDK_SHA, falling
back to GITHUB_SHA for backward compatibility.

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

Author: openhands-agent

.github/workflows/run-examples.yml

@@ -76,7 +76,7 @@ jobs:
                   PR_NUMBER: ${{ github.event.pull_request.number }}
                   REPO_OWNER: ${{ github.repository_owner }}
                   REPO_NAME: ${{ github.event.repository.name }}
-                  GITHUB_SHA: ${{ github.event.pull_request.head.sha }}
+                  SDK_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
                   OPENHANDS_CLOUD_API_KEY: ${{ secrets.ALLHANDS_BOT_OPENHANDS_SAAS_API_KEY }}
                   # ACP agents (Claude Code, Codex) route through LiteLLM proxy
                   ANTHROPIC_BASE_URL: https://llm-proxy.app.all-hands.dev

examples/02_remote_agent_server/02_convo_with_docker_sandboxed_server.py

@@ -40,11 +40,11 @@ def get_server_image():
     """Get the server image tag, using PR-specific image in CI."""
     platform_str = detect_platform()
     arch = "arm64" if "arm64" in platform_str else "amd64"
-    # If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
-    # Otherwise, use the latest image from main
-    github_sha = os.getenv("GITHUB_SHA")
-    if github_sha:
-        return f"ghcr.io/openhands/agent-server:{github_sha[:7]}-python-{arch}"
+    # SDK_SHA is the canonical commit SHA set by CI workflows (avoids the
+    # built-in GITHUB_SHA which resolves to the merge-commit on PRs).
+    sha = os.getenv("SDK_SHA") or os.getenv("GITHUB_SHA")
+    if sha:
+        return f"ghcr.io/openhands/agent-server:{sha[:7]}-python-{arch}"
     return "ghcr.io/openhands/agent-server:latest-python"
 
 

examples/02_remote_agent_server/03_browser_use_with_docker_sandboxed_server.py

@@ -35,11 +35,11 @@ def get_server_image():
     """Get the server image tag, using PR-specific image in CI."""
     platform_str = detect_platform()
     arch = "arm64" if "arm64" in platform_str else "amd64"
-    # If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
-    # Otherwise, use the latest image from main
-    github_sha = os.getenv("GITHUB_SHA")
-    if github_sha:
-        return f"ghcr.io/openhands/agent-server:{github_sha[:7]}-python-{arch}"
+    # SDK_SHA is the canonical commit SHA set by CI workflows (avoids the
+    # built-in GITHUB_SHA which resolves to the merge-commit on PRs).
+    sha = os.getenv("SDK_SHA") or os.getenv("GITHUB_SHA")
+    if sha:
+        return f"ghcr.io/openhands/agent-server:{sha[:7]}-python-{arch}"
     return "ghcr.io/openhands/agent-server:latest-python"
 
 

examples/02_remote_agent_server/04_convo_with_api_sandboxed_server.py

@@ -45,9 +45,9 @@
     exit(1)
 
 
-# If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
-# Otherwise, use the latest image from main
-server_image_sha = os.getenv("GITHUB_SHA") or "main"
+# SDK_SHA is the canonical commit SHA set by CI workflows (avoids the
+# built-in GITHUB_SHA which resolves to the merge-commit on PRs).
+server_image_sha = os.getenv("SDK_SHA") or os.getenv("GITHUB_SHA") or "main"
 server_image = f"ghcr.io/openhands/agent-server:{server_image_sha[:7]}-python-amd64"
 logger.info(f"Using server image: {server_image}")
 

examples/02_remote_agent_server/05_vscode_with_docker_sandboxed_server.py

@@ -37,11 +37,11 @@ def get_server_image():
     """Get the server image tag, using PR-specific image in CI."""
     platform_str = detect_platform()
     arch = "arm64" if "arm64" in platform_str else "amd64"
-    # If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
-    # Otherwise, use the latest image from main
-    github_sha = os.getenv("GITHUB_SHA")
-    if github_sha:
-        return f"ghcr.io/openhands/agent-server:{github_sha[:7]}-python-{arch}"
+    # SDK_SHA is the canonical commit SHA set by CI workflows (avoids the
+    # built-in GITHUB_SHA which resolves to the merge-commit on PRs).
+    sha = os.getenv("SDK_SHA") or os.getenv("GITHUB_SHA")
+    if sha:
+        return f"ghcr.io/openhands/agent-server:{sha[:7]}-python-{arch}"
     return "ghcr.io/openhands/agent-server:latest-python"
 
 

examples/02_remote_agent_server/08_convo_with_apptainer_sandboxed_server.py

@@ -40,11 +40,11 @@ def get_server_image():
     """Get the server image tag, using PR-specific image in CI."""
     platform_str = detect_platform()
     arch = "arm64" if "arm64" in platform_str else "amd64"
-    # If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
-    # Otherwise, use the latest image from main
-    github_sha = os.getenv("GITHUB_SHA")
-    if github_sha:
-        return f"ghcr.io/openhands/agent-server:{github_sha[:7]}-python-{arch}"
+    # SDK_SHA is the canonical commit SHA set by CI workflows (avoids the
+    # built-in GITHUB_SHA which resolves to the merge-commit on PRs).
+    sha = os.getenv("SDK_SHA") or os.getenv("GITHUB_SHA")
+    if sha:
+        return f"ghcr.io/openhands/agent-server:{sha[:7]}-python-{arch}"
     return "ghcr.io/openhands/agent-server:latest-python"
 
 

examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py

@@ -41,9 +41,9 @@
 runtime_api_key = os.getenv("RUNTIME_API_KEY")
 assert runtime_api_key, "RUNTIME_API_KEY required"
 
-# If GITHUB_SHA is set (e.g. running in CI of a PR), use that to ensure consistency
-# Otherwise, use the latest image from main
-server_image_sha = os.getenv("GITHUB_SHA") or "main"
+# SDK_SHA is the canonical commit SHA set by CI workflows (avoids the
+# built-in GITHUB_SHA which resolves to the merge-commit on PRs).
+server_image_sha = os.getenv("SDK_SHA") or os.getenv("GITHUB_SHA") or "main"
 server_image = f"ghcr.io/openhands/agent-server:{server_image_sha[:7]}-python-amd64"
 logger.info(f"Using server image: {server_image}")