home-network-k3s-impl/decisions/2026-11-07-gitea-28.md

date, branch, title

date	branch	title
2026-11-07	feat/gitea-28	Gitea 1.27.3 -> 28.3.0 (upstream dropped the 1. prefix)

What changed

• catalog/gitea.yaml: source.image gitea/gitea:1.27.3 -> gitea/gitea:28.3.0 (still the newest stable tag on Docker Hub and GitHub on 2026-11-07: 28.0.0, 28.1.0, 28.2.0, 28.3.0). update.range ">=1.22.0 <2.0.0" -> ">=28.0.0 <29.0.0".
• 28.x breaking changes handled in the env block:
  • GITEA__server__DOMAIN removed: 28 no longer reads [server] DOMAIN (go-gitea/gitea#39400); ROOT_URL was already set and is now the only source of the domain. Nothing else in the repo reads the variable (the bootstrap script sets ROOT_URL/SSH_PORT only).
  • GITEA__actions__RUN_RETENTION_DAYS=400 declared (go-gitea/gitea#38855 added the 400-day default; the spec repo states no CI-history retention requirement).
  • GITEA__security__EGRESS_MODE=lax declared, with no allow list. Read from the 28.3.0 source: the Keycloak OIDC login source does NOT go through the new egress policy (goth's openidConnect provider, default HTTP client). The policy covers webhooks, the OAuth2 avatar fetch (UPDATE_AVATAR is off) and OpenID 2.0. A hostname entry would not even help for a private address — WithLocalNeedsIPAllow requires an IP/CIDR entry. So the brief's "Keycloak SSO breaks" premise does not hold for 28.3.0, and an allow-list entry would only widen webhook SSRF reach.
  • GITEA__service__DISABLE_REGISTRATION=true declared (28's new default; 1.27 defaulted it open). OAuth2 auto-registration is gated separately and keeps working.
• update.autoRollbackOnFailedHealth: kept true, commented as inert. It renders only an annotation on a Flux ImagePolicy, and apps/ is rendered --no-image-automation, so no ImagePolicy exists. The Deployment is Recreate with no probes, so nothing reverts the image automatically. Rollback = restore the PVC, never an image revert onto the migrated DB.
• apps/wave-0/gitea.yaml re-rendered with the canonical command (render.py --all catalog -o apps --wave-layout --no-image-automation, in the toolbox). Only gitea changed.
• renovate.json5: gitea allowedVersions <2.0.0 -> <29.0.0; the description no longer calls 28.x a stale tag.

What I verified

• Docker Hub tag list and GitHub tags: 28.3.0 is the newest 28.x stable tag.
• Read the v28.3.0 source: modules/egress/policy/policy.go, modules/egress/policies.go, every egress.New* caller, services/auth/source/oauth2/providers_openid.go, modules/setting/{security,actions,service}.go, routers/web/auth/{oauth,linkaccount}.go, cmd/admin_user_list.go, cmd/admin_auth*.go, the Dockerfile, and docker/root (the s6 setup still runs environment-to-ini). The postStart hook's CLI is unchanged in 28.3.0: admin user list --admin still has Username in column 2, admin auth list still has ID/Name in columns 1/2, add-oauth/update-oauth keep the same flags, and curl and su-exec are still in the image.
• Live Gitea (API, 2026-11-07): version 1.27.3. Zero repo, org and system webhooks, no mirrors.
• renovate-config-validator at 44.167.0 (the tag renovate.yaml pins): "Config validated successfully".
• Ran the toolbox gate on the committed tree (numbers are in the PR).

What I did NOT verify

• The upgrade itself. Nothing booted 28.3.0 against a copy of the production DB. Migration time, migration success and the post-upgrade SSO login are all UNVERIFIED, and the PR's post-merge checklist covers them.
• The age of the latest gitea-data Longhorn/off-cluster backup. The cluster read failed from the worktree (no k3s-prod context with the kubeconfig available), so the operator must confirm it before merging.
• How the Envoy Gateway handles the new /-/ws WebSocket. If upgrades are not forwarded, live notifications fall back to polling (not breaking). UNVERIFIED.
• Whether the L2/L3 conformance suite passes. It does not run in CI.