---
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.