From 1906289997773cba7a8212983bb856f6d5fdda84 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Thu, 16 Jul 2026 14:45:43 +0200
Subject: [PATCH] docs(deploy): state-hub Forgejo image promote flow
 (CUST-WP-0059 T06)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../apps/charts/state-hub/PROMOTE.md          | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 deploy/railiance/apps/charts/state-hub/PROMOTE.md

diff --git a/deploy/railiance/apps/charts/state-hub/PROMOTE.md b/deploy/railiance/apps/charts/state-hub/PROMOTE.md
new file mode 100644
index 0000000..0d8d213
--- /dev/null
+++ b/deploy/railiance/apps/charts/state-hub/PROMOTE.md
@@ -0,0 +1,39 @@
+# state-hub image promotion (Forgejo)
+
+The state-hub container image is built and published by CI
+(`.forgejo/workflows/image.yaml`) to the **Forgejo** registry on every `main`
+push that touches the app:
+
+- `forgejo.coulomb.social/coulomb/state-hub:main-<short-sha>` — immutable, promotable
+- `forgejo.coulomb.social/coulomb/state-hub:latest` — moving pointer to newest main
+
+The chart's `image.repository` defaults to `forgejo.coulomb.social/coulomb/state-hub`.
+
+## Promote a build to the cluster
+
+1. Pick a CI-produced tag to promote — **use an immutable `main-<sha>`**, not
+   `latest` (avoid surprise upgrades). List candidates:
+   ```
+   # requires a Forgejo read token
+   curl -s -u <user>:<token> \
+     "https://forgejo.coulomb.social/api/v1/packages/coulomb?type=container&q=state-hub"
+   ```
+2. Upgrade the release (rolling, `maxUnavailable=0` → zero downtime; `--atomic`
+   auto-rolls-back if the pull fails):
+   ```
+   helm -n state-hub upgrade state-hub <chart-path> \
+     --reuse-values \
+     --set image.tag=main-<sha> \
+     --atomic --timeout 3m
+   ```
+3. Update this chart's `appVersion` to the promoted `main-<sha>` and commit, so the
+   declared version matches what's deployed.
+
+## History
+
+- **2026-07-16:** the deployed release pinned the gitea-era tag `f2e042a`, which
+  Forgejo CI never produced. The running image was preserved by a one-off
+  gitea→Forgejo copy of `f2e042a` and the release repointed to Forgejo
+  (CUST-WP-0059). Going forward, promotions use CI `main-<sha>` tags — no manual
+  image copies. The next promotion should move off `f2e042a` onto a `main-<sha>`
+  and update `appVersion` accordingly.