From 8a9baa92bc3c3cbf4e810f21e521b9c31c73cf54 Mon Sep 17 00:00:00 2001 From: Keith Jackson Date: Sat, 7 Nov 2026 22:55:06 -0600 Subject: [PATCH] feat(gitea): upgrade 1.27.3 -> 28.3.0 Gitea dropped the "1." prefix; 28.x is the successor of 1.27. - image 28.3.0, update.range >=28.0.0 <29.0.0, Renovate ceiling <29.0.0 - drop GITEA__server__DOMAIN (no longer read in 28, ROOT_URL is the source) - declare RUN_RETENTION_DAYS=400, EGRESS_MODE=lax (no allow list: the OIDC login source is not gated by the egress policy in 28.3.0), and DISABLE_REGISTRATION=true (28's new default) - document autoRollbackOnFailedHealth as inert (no ImagePolicy is rendered); rollback is a PVC restore because the DB migration is one-way Co-Authored-By: Claude Opus 5.5 --- apps/wave-0/gitea.yaml | 10 ++++-- catalog/gitea.yaml | 44 ++++++++++++++++++++--- decisions/2026-11-07-gitea-28.md | 62 ++++++++++++++++++++++++++++++++ renovate.json5 | 4 +-- 4 files changed, 110 insertions(+), 10 deletions(-) create mode 100644 decisions/2026-11-07-gitea-28.md diff --git a/apps/wave-0/gitea.yaml b/apps/wave-0/gitea.yaml index 78841ba..189d946 100644 --- a/apps/wave-0/gitea.yaml +++ b/apps/wave-0/gitea.yaml @@ -78,7 +78,7 @@ spec: spec: containers: - name: gitea - image: gitea/gitea:1.27.3 + image: gitea/gitea:28.3.0 ports: - containerPort: 3000 env: @@ -89,14 +89,18 @@ spec: secretKeyRef: name: gitea-bootstrap key: secret-key - - name: GITEA__server__DOMAIN - value: gitea.${BASE_DOMAIN} - name: GITEA__server__ROOT_URL value: https://gitea.${BASE_DOMAIN}/ - name: GITEA__actions__ENABLED value: 'true' - name: GITEA__actions__DEFAULT_ACTIONS_URL value: github + - name: GITEA__actions__RUN_RETENTION_DAYS + value: '400' + - name: GITEA__security__EGRESS_MODE + value: lax + - name: GITEA__service__DISABLE_REGISTRATION + value: 'true' - name: GITEA_ADMIN_USERNAME valueFrom: secretKeyRef: diff --git a/catalog/gitea.yaml b/catalog/gitea.yaml index 943c773..c6341b4 100644 --- a/catalog/gitea.yaml +++ b/catalog/gitea.yaml @@ -10,7 +10,7 @@ name: gitea kind: container source: - image: gitea/gitea:1.27.3 # pinned recent stable tag (R-UPD-01); update.range governs advancement + image: gitea/gitea:28.3.0 # pinned recent stable tag (R-UPD-01); update.range governs advancement # Headless-install bootstrap (formerly apps/gitea-bootstrap-patch.yaml; now first-class via the # ServiceDefinition env/envFrom/lifecycle fields, schema >=1.2.0). Gitea must come up INSTALLED # without the interactive web wizard and with a FIXED, persistent SECRET_KEY, so all of this is @@ -23,14 +23,43 @@ env: secretKeyRef: name: gitea-bootstrap key: secret-key - - name: GITEA__server__DOMAIN # correct public clone/redirect URLs for the TLS-terminated host - value: gitea.${BASE_DOMAIN} + # ROOT_URL is the ONLY source of the instance domain since Gitea 28 (go-gitea/gitea#39400): [server] + # DOMAIN is no longer read, and the SSH domain defaults from ROOT_URL too. GITEA__server__DOMAIN was + # removed in the 28 upgrade; the stale DOMAIN line environment-to-ini already wrote into app.ini is + # inert. Correct public clone/redirect URLs for the TLS-terminated host come from this one value. - name: GITEA__server__ROOT_URL value: https://gitea.${BASE_DOMAIN}/ - name: GITEA__actions__ENABLED # Phase 6 CI/CD: declared (not implicit upstream default) so the value: "true" # in-cluster act_runner (ns gitea-actions) registers against it - name: GITEA__actions__DEFAULT_ACTIONS_URL # resolve `uses: /@ref` from github.com (cluster value: github # has internet egress; not air-gapped) + # Gitea 28 added run retention (go-gitea/gitea#38855): completed runs, with their jobs, logs and + # artifacts, are deleted by the cleanup_action_runs cron after RUN_RETENTION_DAYS. Upstream's default + # (400) is kept but DECLARED, so the deletion horizon is visible here rather than implicit. The spec + # repo states no CI-history retention requirement; 0 would mean keep forever. + - name: GITEA__actions__RUN_RETENTION_DAYS + value: "400" + # Gitea 28 (go-gitea/gitea#39426) puts webhooks, the OAuth2 avatar fetch and OpenID 2.0 behind an + # egress policy: in the default lax mode, PUBLIC targets are allowed and private/loopback/CGNAT + # targets need an IP or CIDR entry in [security] ALLOWED_HOST_LIST (a hostname entry is NOT enough + # for a private address). DECLARED lax with an EMPTY allow list, deliberately: + # * the Keycloak OIDC login source is NOT gated by it. In 28.3.0 the openidConnect provider is + # goth's, built with its default HTTP client (services/auth/source/oauth2/providers_openid.go); + # egress.NewSecurityPolicy is used only by routers/web/auth/oauth.go (avatar fetch, and + # [oauth2_client] UPDATE_AVATAR is off here) and modules/auth/openid (OpenID 2.0, unused). + # So keycloak. resolving to the private Gateway address in-cluster does not matter. + # * this instance has no webhooks and no mirrors (measured 2026-11-07), and 1.27 already refused + # private webhook targets by default, so nothing that worked before is newly denied. + # Adding an entry here would only WIDEN the webhook SSRF surface. Add the narrowest CIDR (e.g. the + # Gateway address /32) only if a real private webhook target appears. + - name: GITEA__security__EGRESS_MODE + value: lax + # Gitea 28 (go-gitea/gitea#39400) disables LOCAL self-registration unless DISABLE_REGISTRATION is + # explicitly false; 1.27 defaulted it open. Declared true: accounts arrive via Keycloak only. + # OAuth2 auto-registration below is unaffected — routers/web/auth/oauth.go gates it on + # ALLOW_ONLY_INTERNAL_REGISTRATION and ENABLE_AUTO_REGISTRATION, not on DISABLE_REGISTRATION. + - name: GITEA__service__DISABLE_REGISTRATION + value: "true" - name: GITEA_ADMIN_USERNAME # break-glass local admin creds (consumed by the postStart hook) valueFrom: secretKeyRef: @@ -233,9 +262,14 @@ auth: # recovery tools (docs/15 "Availability caveat"). No secret is embedded here. update: channel: stable # R-UPD-01 - range: ">=1.22.0 <2.0.0" # stay on the 1.x stable line + range: ">=28.0.0 <29.0.0" # Gitea dropped the "1." prefix at 28.0.0 (successor of 1.27); stay on 28.x cadence: "0 4 * * *" - autoRollbackOnFailedHealth: true # R-UPD-03 + # R-UPD-03. INERT FOR THIS SERVICE, and it must stay that way: this flag renders only an annotation + # on a Flux ImagePolicy, and apps/ is rendered --no-image-automation (ci/render-golden.sh), so no + # ImagePolicy exists and the Deployment (strategy Recreate) is never auto-reverted. That matters + # because a Gitea upgrade (1.27 -> 28 included) MIGRATES THE SQLITE DB ONE-WAY: an image revert onto + # a migrated DB is not a rollback. Roll Gitea back by RESTORING THE DATA PVC from its pre-upgrade backup. + autoRollbackOnFailedHealth: true observability: metrics: true slis: diff --git a/decisions/2026-11-07-gitea-28.md b/decisions/2026-11-07-gitea-28.md new file mode 100644 index 0000000..5b40ef8 --- /dev/null +++ b/decisions/2026-11-07-gitea-28.md @@ -0,0 +1,62 @@ +--- +date: 2026-11-07 +branch: feat/gitea-28 +title: "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. diff --git a/renovate.json5 b/renovate.json5 index 144aff1..21214e4 100644 --- a/renovate.json5 +++ b/renovate.json5 @@ -316,9 +316,9 @@ "enabled": false }, { - "description": "ADDED 2026-10-30. MIRRORS catalog/.yaml `update.range` — the operator's declared per-service policy (schemas/servicedefinition.schema.json), which Renovate does not read. Without it the dry run proposed gitea 28.2.0, qbittorrent 20.04.1 (both stale/odd tags, not real successors), radarr 6.x and nextcloud 35 (four majors past 31; Nextcloud cannot skip majors). KEEP IN STEP with the catalog ranges.", + "description": "ADDED 2026-10-30. MIRRORS catalog/.yaml `update.range` — the operator's declared per-service policy (schemas/servicedefinition.schema.json), which Renovate does not read. Without it the dry run proposed gitea 28.2.0, qbittorrent 20.04.1 (the qbittorrent tag is a stale/odd one, not a real successor; gitea 28.x IS the real successor of 1.27 — upstream dropped the \"1.\" prefix at 28.0.0 — and the catalog moved to it on 2026-11-07, so the gitea ceiling is now <29.0.0: 28.x patches/minors are proposed, never auto-merged per the blast-radius rule, and 29 waits for a human), radarr 6.x and nextcloud 35 (four majors past 31; Nextcloud cannot skip majors). KEEP IN STEP with the catalog ranges.", "matchPackageNames": ["gitea/gitea"], - "allowedVersions": "<2.0.0" + "allowedVersions": "<29.0.0" }, { "matchPackageNames": ["nextcloud"], "allowedVersions": "<32.0.0" }, { "matchPackageNames": ["lscr.io/linuxserver/qbittorrent"], "allowedVersions": "<6.0.0" },