feat(chart,docs): migrate to unified image tag format openab:<tag>-<agent>

chaodu-agent · chaodu-agent · commit 41e21307d622 · 2026-06-23T20:52:36.000Z
- Update _helpers.tpl agentImage to produce openab:<tag>-<agent> for non-kiro agents (kiro stays openab:<tag> as default) - Remove per-agent image overrides from values.yaml examples (chart auto-resolves now) - Rewrite docs/image-tags.md with unified tag convention and migration table - Update all agent docs to remove --set image lines (no longer needed) - Update docker pull examples to use openab:beta-<agent> format Part of #1175 follow-up. Backward-compatible: explicit image override still works for custom registries.
diff --git a/charts/openab/templates/_helpers.tpl b/charts/openab/templates/_helpers.tpl
@@ -56,9 +56,12 @@ app.kubernetes.io/component: {{ .agent }}
 {{- end -}}
 {{- end }}
 
-{{/* Resolve image: agent-level string override → global default (repository:tag, tag defaults to appVersion).
-    Caveat: "contains :" treats registry ports (e.g. my-registry:5000/img) as tagged.
-    Not an issue for ghcr.io / Docker Hub; revisit if custom registries with ports are needed. */}}
+{{/* Resolve image: agent-level string override → unified default (repository:<tag>-<agent>).
+    When no per-agent image override is set, produces:
+      ghcr.io/openabdev/openab:<tag>-<agent>   (e.g. openab:beta-claude)
+      ghcr.io/openabdev/openab:<tag>            (for kiro, the default agent)
+    Per-agent image override (string with ":") is used verbatim for full backward compat.
+    Call with: dict "ctx" $ "agent" $name "cfg" $cfg */}}
 {{- define "openab.agentImage" -}}
 {{- if and .cfg.image (kindIs "string" .cfg.image) (ne .cfg.image "") }}
 {{- if contains ":" .cfg.image }}
@@ -68,7 +71,11 @@ app.kubernetes.io/component: {{ .agent }}
 {{- end }}
 {{- else }}
 {{- $tag := default .ctx.Chart.AppVersion .ctx.Values.image.tag }}
+{{- if eq .agent "kiro" }}
 {{- printf "%s:%s" .ctx.Values.image.repository $tag }}
+{{- else }}
+{{- printf "%s:%s-%s" .ctx.Values.image.repository $tag .agent }}
+{{- end }}
 {{- end }}
 {{- end }}
 
diff --git a/charts/openab/values.yaml b/charts/openab/values.yaml
@@ -95,7 +95,7 @@ agents:
     #   nodeSelector: {}
     #   tolerations: []
     #   affinity: {}
-    #   image: "ghcr.io/openabdev/openab-claude"  # tag omitted → auto-appends appVersion
+    #   image: ""  # leave empty → auto-resolves to openab:<tag>-claude (unified format)
     # opencode:
     #   command: opencode
     #   args:
@@ -125,7 +125,7 @@ agents:
     #     size: 1Gi
     #   agentsMd: ""
     #   resources: {}
-    #   image: "ghcr.io/openabdev/openab-opencode:latest"
+    #   image: ""  # leave empty → auto-resolves to openab:<tag>-opencode
     # pi:
     #   command: pi-acp
     #   discord:
@@ -152,7 +152,7 @@ agents:
     #     enabled: true
     #     storageClass: ""
     #     size: 1Gi
-    #   image: "ghcr.io/openabdev/openab-pi:latest"
+    #   image: ""  # leave empty → auto-resolves to openab:<tag>-pi
     # cursor:
     #   command: cursor-agent
     #   args:
@@ -183,7 +183,7 @@ agents:
     #     existingClaim: ""  # set to reuse an existing PVC (skips PVC creation)
     #     storageClass: ""
     #     size: 1Gi
-    #   image: "ghcr.io/openabdev/openab-cursor:latest"
+    #   image: ""  # leave empty → auto-resolves to openab:<tag>-cursor
     # hermes:
     #   command: hermes-acp
     #   discord:
@@ -204,7 +204,7 @@ agents:
     #     enabled: true
     #     storageClass: ""
     #     size: 1Gi
-    #   image: "ghcr.io/openabdev/openab-hermes"
+    #   image: ""  # leave empty → auto-resolves to openab:<tag>-hermes
     # grok:
     #   command: grok
     #   args:
@@ -232,7 +232,7 @@ agents:
     #     enabled: true
     #     storageClass: ""
     #     size: 1Gi
-    #   image: "ghcr.io/openabdev/openab-grok"
+    #   image: ""  # leave empty → auto-resolves to openab:<tag>-grok
     image: ""
     # configUrl: when set, openab uses `-c <URL>` to fetch config remotely
     # instead of mounting the chart-generated ConfigMap. The ConfigMap and its
diff --git a/docs/agentcore.md b/docs/agentcore.md
@@ -84,10 +84,10 @@ args = ["agentcore-bridge", "--runtime-arn", "arn:aws:...", "--region", "us-east
 
 ## Docker Image
 
-Use `ghcr.io/openabdev/openab-agentcore` — a minimal image (~20MB) with only the OAB binary. No Python, no coding CLI bundled.
+Use `ghcr.io/openabdev/openab:beta-agentcore` — a minimal image (~20MB) with only the OAB binary. No Python, no coding CLI bundled.
 
 ```bash
-docker pull ghcr.io/openabdev/openab-agentcore:latest
+docker pull ghcr.io/openabdev/openab:beta-agentcore
 ```
 
 ## Deploying a Kiro Runtime
diff --git a/docs/antigravity.md b/docs/antigravity.md
@@ -69,7 +69,7 @@ agents:
       args: []
       workingDir: "/home/agent"
     image:
-      repository: ghcr.io/openabdev/openab-antigravity
+      repository: ghcr.io/openabdev/openab:beta-antigravity
       tag: "latest"
 ```
 
diff --git a/docs/claude-code.md b/docs/claude-code.md
@@ -17,7 +17,6 @@ helm install openab openab/openab \
   --set agents.kiro.enabled=false \
   --set agents.claude.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.claude.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
-  --set agents.claude.image=ghcr.io/openabdev/openab-claude:latest \
   --set agents.claude.command=claude-agent-acp \
   --set agents.claude.workingDir=/home/node
 ```
diff --git a/docs/codex.md b/docs/codex.md
@@ -21,7 +21,6 @@ helm install openab openab/openab \
   --set agents.codex.discord.enabled=true \
   --set agents.codex.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.codex.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
-  --set agents.codex.image=ghcr.io/openabdev/openab-codex:latest \
   --set agents.codex.command=codex-acp \
   --set agents.codex.workingDir=/home/node
 ```
diff --git a/docs/copilot.md b/docs/copilot.md
@@ -59,7 +59,6 @@ helm install openab-copilot openab/openab \
   --set agents.copilot.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.copilot.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
   --set agents.copilot.discord.enabled=true \
-  --set agents.copilot.image=ghcr.io/openabdev/openab-copilot \
   --set agents.copilot.command=copilot \
   --set 'agents.copilot.args={--acp,--stdio}' \
   --set agents.copilot.persistence.enabled=true \
@@ -129,7 +128,6 @@ helm install openab-copilot openab/openab \
   --set agents.copilot.discord.enabled=true \
   --set agents.copilot.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.copilot.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
-  --set agents.copilot.image=ghcr.io/openabdev/openab-copilot \
   --set agents.copilot.command=copilot \
   --set 'agents.copilot.args={--acp,--stdio}' \
   --set agents.copilot.persistence.enabled=true \
diff --git a/docs/cursor.md b/docs/cursor.md
@@ -63,7 +63,6 @@ helm install openab openab/openab \
   --set agents.kiro.enabled=false \
   --set agents.cursor.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.cursor.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
-  --set agents.cursor.image=ghcr.io/openabdev/openab-cursor:latest \
   --set agents.cursor.command=cursor-agent \
   --set 'agents.cursor.args={acp}' \
   --set agents.cursor.persistence.enabled=true \
diff --git a/docs/gemini.md b/docs/gemini.md
@@ -18,7 +18,6 @@ helm install openab openab/openab \
   --set agents.gemini.discord.enabled=true \
   --set agents.gemini.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.gemini.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
-  --set agents.gemini.image=ghcr.io/openabdev/openab-gemini:latest \
   --set agents.gemini.command=gemini \
   --set agents.gemini.args='{--acp}' \
   --set agents.gemini.workingDir=/home/node
diff --git a/docs/grok.md b/docs/grok.md
@@ -18,7 +18,6 @@ helm install openab openab/openab \
   --set agents.grok.discord.enabled=true \
   --set agents.grok.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.grok.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
-  --set agents.grok.image=ghcr.io/openabdev/openab-grok:latest \
   --set agents.grok.command=grok \
   --set-string 'agents.grok.args[0]=agent' \
   --set-string 'agents.grok.args[1]=stdio' \
diff --git a/docs/hermes.md b/docs/hermes.md
@@ -20,7 +20,6 @@ helm install openab openab/openab \
   --set agents.hermes.discord.enabled=true \
   --set agents.hermes.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.hermes.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
-  --set agents.hermes.image=ghcr.io/openabdev/openab-hermes:latest \
   --set agents.hermes.command=hermes-acp \
   --set agents.hermes.workingDir=/home/agent
 ```
diff --git a/docs/image-tags.md b/docs/image-tags.md
@@ -1,17 +1,48 @@
 # Docker Image Tagging Convention
 
-## Core (`ghcr.io/openabdev/openab`)
+## Unified Image Repository (`ghcr.io/openabdev/openab`)
+
+All agent variants are published under a single image repository using tag-based variants:
+
+```
+ghcr.io/openabdev/openab:<version>-<agent>   # per-agent variant
+ghcr.io/openabdev/openab:<version>           # default (kiro)
+```
+
+### Default (kiro) tags
 
 | Tag | Points to | Updated when |
 |-----|-----------|--------------|
-| `0.8.3-beta.12` | Exact pre-release build | Pre-release tag pushed |
+| `0.9.0-beta.1` | Exact pre-release build | Pre-release tag pushed |
 | `beta` | Latest pre-release | Every pre-release build |
-| `0.8.3` | Promoted stable build | Stable tag pushed |
-| `0.8` | Latest patch in minor | Stable promotion |
+| `0.9.0` | Promoted stable build | Stable tag pushed |
+| `0.9` | Latest patch in minor | Stable promotion |
 | `stable` | Latest stable | Stable promotion |
 | `latest` | Latest stable (= `stable`) | Stable promotion |
 
-Variant images (e.g. `-codex`, `-claude`, `-gemini`) follow the same convention with a suffix: `ghcr.io/openabdev/openab-codex:beta`.
+### Per-agent variant tags
+
+Agent variants use the format `<version>-<agent>`:
+
+| Tag | Example | Points to |
+|-----|---------|-----------|
+| `<version>-<agent>` | `0.9.0-beta.1-claude` | Exact pre-release build for claude |
+| `beta-<agent>` | `beta-codex` | Latest pre-release for codex |
+| `<version>-<agent>` | `0.9.0-gemini` | Promoted stable for gemini |
+| `stable-<agent>` | `stable-grok` | Latest stable for grok |
+
+Available agents: `kiro`, `claude`, `codex`, `copilot`, `cursor`, `gemini`, `grok`, `hermes`, `mimocode`, `opencode`, `antigravity`, `pi`, `native`, `agentcore`
+
+### Migration from per-repo images (deprecated)
+
+Previously, each agent had its own image repository (`ghcr.io/openabdev/openab-codex:beta`).
+These are now replaced by the unified tag format (`ghcr.io/openabdev/openab:beta-codex`).
+
+| Old (deprecated) | New |
+|------------------|-----|
+| `ghcr.io/openabdev/openab-claude:beta` | `ghcr.io/openabdev/openab:beta-claude` |
+| `ghcr.io/openabdev/openab-codex:0.8.5-beta.13` | `ghcr.io/openabdev/openab:0.8.5-beta.13-codex` |
+| `ghcr.io/openabdev/openab:beta` | `ghcr.io/openabdev/openab:beta` (unchanged, kiro is default) |
 
 ## Gateway (`ghcr.io/openabdev/openab-gateway`)
 
@@ -25,31 +56,40 @@ Variant images (e.g. `-codex`, `-claude`, `-gemini`) follow the same convention
 
 | Use case | Recommended tag |
 |----------|----------------|
-| Production (pinned) | Exact version (`0.8.3-beta.12`) |
-| Helm chart default | `stable` or `beta` (channel-based) |
-| Local dev / quick test | `beta` |
+| Production (pinned) | Exact version (`0.9.0-beta.1-claude`) |
+| Helm chart default | `stable` or `beta` (channel-based) — chart auto-appends `-<agent>` |
+| Local dev / quick test | `beta` or `beta-<agent>` |
 | CI | Exact version or SHA |
 
 ## Release flow
 
 ```
-release PR merged → tag-on-merge → v0.8.3-beta.12
+release PR merged → tag-on-merge → v0.9.0-beta.1
                                          │
                                          ▼
                                   build-operator.yml
                                          │
                               ┌──────────┴──────────┐
                               │ is_prerelease=true   │
                               ▼                      │
-                    tag: 0.8.3-beta.12               │
-                    tag: beta                        │
+                    openab:0.9.0-beta.1              │
+                    openab:0.9.0-beta.1-claude       │
+                    openab:0.9.0-beta.1-codex        │
+                    openab:beta                      │
+                    openab:beta-claude               │
+                    openab:beta-codex                │
+                    ... (all agents)                 │
                                                     │
                               ┌──────────────────────┘
                               │ is_prerelease=false (stable)
                               ▼
-                    promote latest beta image →
-                    tag: 0.8.3
-                    tag: 0.8
-                    tag: stable
-                    tag: latest
+                    promote latest beta images →
+                    openab:0.9.0
+                    openab:0.9.0-claude
+                    openab:0.9
+                    openab:0.9-claude
+                    openab:stable
+                    openab:stable-claude
+                    openab:latest
+                    ... (all agents)
 ```
diff --git a/docs/multi-agent.md b/docs/multi-agent.md
@@ -10,7 +10,6 @@ helm install openab openab/openab \
   --set-string 'agents.kiro.discord.allowedChannels[0]=KIRO_CHANNEL_ID' \
   --set agents.claude.discord.botToken="$CLAUDE_BOT_TOKEN" \
   --set-string 'agents.claude.discord.allowedChannels[0]=CLAUDE_CHANNEL_ID' \
-  --set agents.claude.image=ghcr.io/openabdev/openab-claude:latest \
   --set agents.claude.command=claude-agent-acp \
   --set agents.claude.workingDir=/home/node
 ```
@@ -30,17 +29,14 @@ helm install openab openab/openab \
   --set-string 'agents.kiro.discord.allowedChannels[0]=KIRO_CHANNEL_ID' \
   --set agents.claude.discord.botToken="$CLAUDE_BOT_TOKEN" \
   --set-string 'agents.claude.discord.allowedChannels[0]=CLAUDE_CHANNEL_ID' \
-  --set agents.claude.image=ghcr.io/openabdev/openab-claude:latest \
   --set agents.claude.command=claude-agent-acp \
   --set agents.claude.workingDir=/home/node \
   --set agents.codex.discord.botToken="$CODEX_BOT_TOKEN" \
   --set-string 'agents.codex.discord.allowedChannels[0]=CODEX_CHANNEL_ID' \
-  --set agents.codex.image=ghcr.io/openabdev/openab-codex:latest \
   --set agents.codex.command=codex-acp \
   --set agents.codex.workingDir=/home/node \
   --set agents.gemini.discord.botToken="$GEMINI_BOT_TOKEN" \
   --set-string 'agents.gemini.discord.allowedChannels[0]=GEMINI_CHANNEL_ID' \
-  --set agents.gemini.image=ghcr.io/openabdev/openab-gemini:latest \
   --set agents.gemini.command=gemini \
   --set agents.gemini.args='{--acp}' \
   --set agents.gemini.workingDir=/home/node
diff --git a/docs/opencode.md b/docs/opencode.md
@@ -38,7 +38,6 @@ helm install openab openab/openab \
   --set agents.opencode.enabled=true \
   --set agents.opencode.command=opencode \
   --set 'agents.opencode.args={acp}' \
-  --set agents.opencode.image=ghcr.io/openabdev/openab-opencode:latest \
   --set agents.opencode.discord.botToken="$DISCORD_BOT_TOKEN" \
   --set-string 'agents.opencode.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \
   --set agents.opencode.workingDir=/home/node \
diff --git a/docs/openshell.md b/docs/openshell.md
@@ -75,7 +75,7 @@ Using the pre-built image:
 
 ```bash
 openshell sandbox create --name oab \
-  --from ghcr.io/openabdev/openab-native-sandbox:latest \
+  --from ghcr.io/openabdev/openab:beta-native-sandbox \
   --provider discord \
   -- bash
 ```
diff --git a/docs/pi.md b/docs/pi.md
@@ -68,7 +68,7 @@ agents:
         - "YOUR_CHANNEL_ID"
     command: pi-acp
     workingDir: /home/node
-    image: "ghcr.io/openabdev/openab-pi:latest"
+    image: "ghcr.io/openabdev/openab:beta-pi"
 ```
 
 ## Authentication
diff --git a/docs/refarch/cronjob_k8s_refarch.md b/docs/refarch/cronjob_k8s_refarch.md
@@ -17,7 +17,7 @@ Kubernetes CronJob
      |
      v
 Ephemeral Job Pod
-  image: ghcr.io/openabdev/openab-codex:latest
+  image: ghcr.io/openabdev/openab:beta-codex
   command: bash /opt/openab-project-screening/screen_once.sh
      |
      +--> read GitHub Project state via gh
@@ -91,7 +91,7 @@ spec:
             - name: project-screening
               # Pin to a specific tag in production (e.g. :0.8.0) to ensure
               # reproducible runs. :latest is used here for illustration only.
-              image: ghcr.io/openabdev/openab-codex:latest
+              image: ghcr.io/openabdev/openab:beta-codex
               command:
                 - bash
                 - /opt/openab-project-screening/screen_once.sh
@@ -308,7 +308,7 @@ projectScreening:
   enabled: true
   schedule: "*/30 * * * *"
   # Pin to a specific tag in production (e.g. :0.8.0)
-  image: ghcr.io/openabdev/openab-codex:latest
+  image: ghcr.io/openabdev/openab:beta-codex
   githubToken: "<token with project scope>"
   codexAuthJson: |
     <contents of ~/.codex/auth.json>
diff --git a/docs/refarch/sidecar-proxy.md b/docs/refarch/sidecar-proxy.md
@@ -64,7 +64,6 @@ kubectl create secret generic auth-proxy-tokens \
 helm install openab openab/openab \
   --set agents.mybot.command=opencode \
   --set-json 'agents.mybot.args=["acp"]' \
-  --set agents.mybot.image=ghcr.io/openabdev/openab-opencode \
   --set-json 'agents.mybot.extraContainers=[{"name":"auth-proxy","image":"ghcr.io/openabdev/openab-auth-proxy:latest","args":["serve","--bind","0.0.0.0"],"ports":[{"containerPort":9090}],"volumeMounts":[{"name":"data","mountPath":"/home/agent"}]}]' \
   --set-json 'agents.mybot.extraInitContainers=[{"name":"copy-tokens","image":"busybox","command":["sh","-c","mkdir -p /dest/.openab-auth-proxy/xai && cp /src/tokens.json /dest/.openab-auth-proxy/xai/tokens.json"],"volumeMounts":[{"name":"tokens-src","mountPath":"/src","readOnly":true},{"name":"data","mountPath":"/dest"}]}]' \
   --set-json 'agents.mybot.extraVolumes=[{"name":"tokens-src","secret":{"secretName":"auth-proxy-tokens"}}]'
