hermes-skills/devops/rke2-cluster-administration/references/gitea-helm-chart-v12-deployment-2026-07.md

Gitea Helm Chart v12 Deployment — Session 2026-07-14

Context

Deploying Gitea on K8s via ArgoCD using the official gitea-charts/gitea chart v12.6.0 (app v1.26.1). DB = external MariaDB Galera via MaxScale VIP 10.0.30.70:3306. Secrets via 1Password ESO.

Issue 1: DB Password Not Reaching Init Container

Symptom

[F] Failed to initialize ORM engine: Error 1045 (28000):
Access denied for user 'gitea'@'10.0.30.62' (using password: NO)

Root Cause

The configure-gitea init container runs gitea migrate which reads app.ini. The chart generates app.ini from gitea.config values — but PASSWD was not set there. Env vars GITEA__database__PASSWD override app.ini at runtime, but only if they reach the init container.

Failed Attempts

1. gitea.env — not a valid chart value path; silently ignored
2. gitea.database.existingSecret — not a valid chart value; ignored
3. gitea.config.database.PASSWD: __placeholder__ — literal string reaches DB, not a secret reference

Solution

gitea.additionalConfigFromEnvs — templated into ALL containers (init-directories, init-app-ini, configure-gitea, main):

gitea:
  additionalConfigFromEnvs:
    - name: GITEA__database__PASSWD
      valueFrom:
        secretKeyRef:
          name: gitea-db
          key: password

Verification

After fix, init-app-ini log showed database + PASSWD in config, and configure-gitea logged PING DATABASE mysql followed by successful schema migration.

Issue 2: Valkey Auto-Deployed

Symptom

3 gitea-valkey-cluster-* pods appeared despite redis-cluster.enabled: false.

Root Cause

Chart v12 renamed redis-cluster → valkey-cluster. The old key no longer controls the cache subsystem.

Fix

valkey-cluster:
  enabled: false

ArgoCD pruned the Valkey StatefulSet after the updated values synced.

Issue 3: RWO PVC Blocks Rolling Update

Symptom

New pod stuck in Init:0/3 with:

Multi-Attach error for volume "pvc-..."
Volume is already used by pod(s) gitea-OLD_POD

Root Cause

ReadWriteOnce PVC + single replica + ArgoCD selfHeal creates new pod before old one terminates. Both compete for the same volume.

Fix

kubectl scale deploy -n gitea gitea --replicas=0
sleep 15
kubectl scale deploy -n gitea gitea --replicas=1

Issue 4: Galera Schema Migration Slowness

Symptom

configure-gitea init container stayed at Init:2/3 for 5+ minutes.

Diagnosis

• 104 tables created by Gitea 1.26.1
• Galera replicates each CREATE TABLE + index synchronously to 3 nodes
• SHOW PROCESSLIST on Galera showed creating table / Committing alter table
• Total time: ~8 minutes from first table to pod Running

Key Insight

This is normal for Galera — do NOT CrashLoop the pod or delete it. Monitor progress via SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='gitea'.

ArgoCD App Architecture Used

Two separate ArgoCD Applications:

1. gitea-config (sync-wave 1): Git source → clusters/main/gitea/ (namespace.yaml + external-secrets.yaml)
2. gitea (sync-wave 2): Helm source → https://dl.gitea.com/charts/ chart gitea v12.6.0

The root App-of-Apps (clusters/main/apps/) auto-discovers both.

Final Working Values (Key Sections)

gitea:
  config:
    database:
      DB_TYPE: mysql
      HOST: 10.0.30.70:3306
      NAME: gitea
      USER: gitea
  additionalConfigFromEnvs:
    - name: GITEA__database__PASSWD
      valueFrom:
        secretKeyRef:
          name: gitea-db
          key: password
  existingSecret:
    name: gitea-security
    keys:
      internal_token: internal_token
      jwt_secret: jwt_secret
      secret_key: secret_key
      lfs_jwt_secret: lfs_jwt_secret

mysql:
  enabled: false
postgresql:
  enabled: false
postgresql-ha:
  enabled: false
redis-cluster:
  enabled: false
valkey-cluster:
  enabled: false

persistence:
  enabled: true
  storageClass: ceph-hdd-replica
  size: 10Gi
  accessModes:
    - ReadWriteOnce

Repo Migration via Gitea Migration API (Task 7)

Prerequisites

• API tokens on BOTH Gitea instances (source CT108 + dest K8s)
• Orgs and users created on destination before migrating
• migrations.ALLOWED_HOST_LIST configured (see above)

Token Generation

# CT108 (source, LXC — Gitea runs as user 'gitea'):
ssh root@10.0.30.105 "su - gitea -s /bin/bash -c \
  'gitea admin user generate-access-token -u dominik -t migrator --raw \
   --config /etc/gitea/app.ini'"

# K8s Gitea (destination):
kubectl exec -n gitea deploy/gitea -- \
  gitea admin user generate-access-token -u dominik -t migrator --raw \
  --config /data/gitea/conf/app.ini

Migration Script Pattern

for repo in repos:
    migrate_data = {
        "clone_addr": f"{CT108_URL}/{owner}/{name}.git",
        "repo_owner": owner, "repo_name": name,
        "mirror": False, "wiki": True, "issues": True,
        "labels": True, "milestones": True,
        "pull_requests": True, "releases": True,
        "service": "gitea", "auth_token": CT108_TOKEN,
    }
    resp = k8s_api("POST", "/api/v1/repos/migrate", migrate_data)

API calls go through kubectl exec on the K8s Gitea pod (no LoadBalancer/Ingress needed during migration):

kubectl exec -n gitea deploy/gitea -- curl -s -X POST \
  -H "Authorization: token TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}' http://localhost:3000/api/v1/repos/migrate

Results (23 repos)

• 18/23 migrated on first attempt ✅
• 1/23 skipped (already existed from test) ⏭️
• 4/23 failed with PR import errors → retried with pull_requests: false → all ✅
• Final: 23/23 repos migrated with issues + wikis

Failed Repos (PR Import Bug)

• dominik/hermes-skills — initRepository: getRepositoryByID
• pm-infra/homelab-board — error while listing pull requests
• d.schoen/packer-proxmox — initRepository: getRepositoryByID
• codecamp-n/qr-reader-webapp — error while listing pull requests

Fix: DELETE /api/v1/repos/{owner}/{name} (cleanup), then retry migration with pull_requests: false.

Commits

• 48a26e6 — Initial scaffold (ArgoCD apps + namespace + ES + helm values)
• 68eda13 — Fix: GITEA__database__PASSWD env + disable valkey-cluster
• effb49b — Fix: use additionalConfigFromEnvs (correct chart mechanism)
• 40da393 — Fix: allow migration from CT108 host (wrong setting name)
• 68adfab — Fix: correct migrations setting names (ALLOWED_HOST_LIST + ALLOW_LOCALNETWORKS)