feat(gitea): 准备 1.26.4 suspended 升级

CHANGELOG.md

@@ -28,6 +28,7 @@ What changed in this homelab, when, and why. Newest first.
 | Gitea adoption stage | 开始用 Flux 接管关键 `gitea` release：固定现有 chart `12.5.3`，以 `suspend: true` 登记 HelmRelease、source、values ConfigMap 和现有 HTTPRoute，子 Kustomization 保持 `prune: false`；现有 OIDC Secret 继续只引用不覆盖，其尚未进入 OpenBao/ESO 的缺口独立跟踪 |
 | Gitea adoption activate | 第一阶段合并后 source、子 Kustomization 和 HTTPRoute 均 Ready，Helm release 仍为 revision 14，Gitea Pod 未重建或重启；再次确认固定 chart 对 live 业务资源零差异后移除 `suspend`，允许 Flux 修正 Helm 存储状态并启用 drift detection |
 | Gitea upgrade plan | 规划两跳升级：chart `12.6.0` + 显式 Gitea `1.26.4`，再到 chart `12.7.0` + 显式 Gitea `1.27.3`；每个 minor 都先以 suspended desired state 合并、停机建立 CNPG/PVC 一致回滚点，再用独立 PR 激活。当前 CNPG 无连续备份、local-path PVC 无 snapshot class，因此禁止无备份直接触发数据库 migration |
+| Gitea 1.26 preparation | 将第一跳目标写入 Git：chart 固定为 `12.6.0`、rootless 镜像显式固定为 `1.26.4`，同时重新设置 HelmRelease `suspend: true`；该准备 revision 合并后只更新 desired state，不触发 Pod replacement 或数据库 migration |
 
 `Carried forward`: complete the two-stage zero-change `gitea` HelmRelease
 adoption, migrate its remaining manual OIDC Secret to OpenBao/ESO, then upgrade

apps/gitea/README.md

@@ -23,3 +23,7 @@ Gitea 是 Flux GitRepository 的上游。升级或重启期间 Git source 暂时
 
 跨 minor 的执行顺序、停机一致备份和失败恢复步骤见
 [`../../docs/gitea-upgrade-plan.md`](../../docs/gitea-upgrade-plan.md)。
+
+当前 Git desired state 已准备第一跳 chart `12.6.0` / Gitea `1.26.4`，但
+HelmRelease 保持 `suspend: true`。合并该准备状态不会运行 migration；必须先按升级
+计划取得停机一致备份，再通过只移除 suspend 的独立激活 PR 执行升级。

apps/gitea/helmrelease.yaml

@@ -11,7 +11,7 @@ spec:
       sourceRef:
         kind: HelmRepository
         name: gitea-charts
-      version: 12.5.3
+      version: 12.6.0
   driftDetection:
     mode: enabled
   install:
@@ -20,12 +20,21 @@ spec:
       retryInterval: 5m
   interval: 30m
   releaseName: gitea
+  suspend: true
   targetNamespace: gitea
   timeout: 15m
   upgrade:
     strategy:
       name: RetryOnFailure
       retryInterval: 5m
+  # Keep the patch release explicit because chart 12.6.0 defaults to 1.26.1.
+  # This override is in the suspended HelmRelease itself so chart, image and
+  # suspension are applied atomically; changing the watched values ConfigMap in
+  # the same revision could otherwise trigger reconciliation first.
+  values:
+    image:
+      rootless: true
+      tag: "1.26.4"
   valuesFrom:
     - kind: ConfigMap
       name: gitea-values

docs/gitea-upgrade-plan.md

@@ -50,8 +50,9 @@ Actions fork PR 审批绕过等安全问题。两个 rootless 镜像标签都已
 
 ### 1. 预拉取与 review
 
-1. 在 `apps/gitea/gitea-values.yaml` 显式设置目标 `image.tag`，同时把 HelmRelease chart
+1. 在 HelmRelease 中显式设置目标 `image.tag`，同时把 chart 固定到该阶段目标版本，
-   固定到该阶段目标版本，并重新执行 Helm/Kustomize render。
+   并重新执行 Helm/Kustomize render。目标 chart、镜像与 `suspend: true` 必须在同一
+   HelmRelease 对象内原子提交；不得同时修改会触发 watch 的 values ConfigMap。
 2. 在节点预拉取目标 rootless 镜像，避免维护窗口受 WAN 波动影响。
 3. 创建 **保持 `spec.suspend: true`** 的准备 PR；合并并等 Flux 同步。此时 Git 只记录
    目标版本，不执行 Helm action。