Skip to content
Gitea icon
v1.2.3App: v28.2.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Gitea Helm Chart

Helm chart for deploying Gitea self-hosted Git service on Kubernetes using the official gitea/gitea rootless Docker image.

  • Current application version 28.2.0
  • Default image docker.io/gitea/gitea:28.2.0-rootless
  • Chart lock policy source chart does not commit Chart.lock; dependencies are resolved during packaging/validation
  • Rootless storage optional initContainer can prepare PVC paths for UID/GID 1000 when required

Features

  • Official rootless image based on gitea/gitea:<version>-rootless (UID 1000)
  • Database backends SQLite3 (default), PostgreSQL, or MySQL with auto-detection
  • PostgreSQL and MySQL subcharts optional bundled database deployments
  • External database connect to an existing PostgreSQL or MySQL instance
  • Persistent storage repositories, LFS objects, config, and SQLite in /var/lib/gitea
  • HTTP + SSH services separate services for web UI and Git SSH access
  • Configurable HTTP listener application and Service ports remain independent
  • Optional NetworkPolicy namespace-local ingress by default when enabled
  • SSH NodePort optional NodePort for SSH access from outside the cluster
  • Admin user creation optional post-install Job to bootstrap an admin account
  • S3-compatible backup database-aware CronJob (SQLite tar, pg_dump, mysqldump)
  • Ingress support configurable ingress with TLS for HTTP access
  • Extra environment variables any GITEA__SECTION__KEY for app.ini overrides

Documentation

Security

The main rootless process runs as UID/GID 1000, drops all Linux capabilities, disables privilege escalation, uses RuntimeDefault seccomp, and does not mount a Kubernetes API token by default. The upstream entrypoint requires a writable root filesystem during initialization, while durable data and configuration stay on the PVC. Enable networkPolicy.enabled only after confirming the allowed peers include the namespace of your ingress controller or Gateway. When admin bootstrap is configured, its Job is allowed to reach the HTTP port independently of those peer rules.

Security Scan: gitea

Framework Score
MITRE + NSA + SOC2 83.54978%

Security posture acceptable.

Installation

HTTPS Repository

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install gitea helmforge/gitea

OCI Registry

helm install gitea oci://ghcr.io/helmforgedev/helm/gitea

Quick Start

Default installation uses SQLite3 with persistent storage — no external database required:

helm install gitea helmforge/gitea

Access the web UI at http://<service-ip>:3000 and complete the initial setup wizard.

Examples

SQLite with Admin User

gitea:
  rootUrl: https://git.example.com/
  sshDomain: git.example.com
  disableRegistration: true

admin:
  username: gitea_admin
  password: "change-me-now"
  email: [email protected]

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: git.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: gitea-tls
      hosts:
        - git.example.com

PostgreSQL Subchart

gitea:
  rootUrl: https://git.example.com/

postgresql:
  enabled: true
  auth:
    database: gitea
    username: gitea
    password: "db-password"

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: git.example.com
      paths:
        - path: /
          pathType: Prefix

External MySQL

database:
  external:
    vendor: mysql
    host: mysql.database.svc
    port: 3306
    name: gitea
    username: gitea
    password: "db-password"

gitea:
  rootUrl: https://git.example.com/

Custom HTTP Listener and Service Port

containerPorts:
  http: 3100
service:
  http:
    port: 8080

The chart sets GITEA__server__HTTP_PORT=3100, exposes that container port as http, and maps Service port 8080 to the named target. Changing only service.http.port never changes the process listener.

Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | image.repository | gitea/gitea | Container image repository | | image.tag | "28.2.0-rootless" | Image tag | | replicaCount | 1 | Number of replicas | | strategy.type | Recreate | Deployment strategy for single-writer local state | | podAnnotations | {} | Additional annotations for the Gitea pod | | gitea.appName | "Gitea: Git with a cup of tea" | Application display name | | gitea.runMode | prod | Run mode (dev, prod, test) | | gitea.rootUrl | "" | Root URL for links and clone URLs | | gitea.sshDomain | "" | SSH domain in clone URLs | | gitea.sshPort | 2222 | SSH listen port | | gitea.lfsEnabled | true | Enable Git LFS | | gitea.disableRegistration | false | Disable self-registration | | gitea.requireSignIn | false | Require sign-in to view pages | | admin.username | "" | Admin username (triggers admin creation Job) | | admin.password | "" | Admin password | | admin.email | "" | Admin email | | admin.existingSecret | "" | Existing secret with admin credentials | | database.mode | auto | Database mode: auto, sqlite, external, postgresql, mysql | | database.sqlite.file | /var/lib/gitea/data/gitea.db | SQLite file path | | database.external.vendor | postgres | External DB vendor | | database.external.host | "" | External DB host | | database.external.port | "" | External DB port | | database.external.name | gitea | Database name | | database.external.username | gitea | Database username | | database.external.existingSecret | "" | Existing secret for DB password | | postgresql.enabled | false | Deploy PostgreSQL subchart | | mysql.enabled | false | Deploy MySQL subchart | | persistence.enabled | true | Enable persistent storage | | persistence.size | 10Gi | Volume size | | volumePermissions.enabled | false | Opt in to a root initContainer that prepares PVC ownership for UID/GID 1000 | | containerPorts.http | 3000 | HTTP port listened on by the Gitea process | | service.http.type | ClusterIP | HTTP service type | | service.http.port | 3000 | HTTP service port | | service.ssh.enabled | true | Enable SSH service | | service.ssh.type | ClusterIP | SSH service type | | service.ssh.port | 2222 | SSH service port | | service.ssh.nodePort | "" | SSH NodePort (when type is NodePort) | | ingress.enabled | false | Enable ingress | | ingress.ingressClassName | "" | Ingress class | | serviceAccount.automountServiceAccountToken | false | Mount a Kubernetes API token into chart pods | | networkPolicy.enabled | false | Restrict HTTP and SSH ingress to configured peers | | networkPolicy.ingressFrom | [] | Allowed ingress peers; empty means same namespace; admin bootstrap remains allowed | | backup.enabled | false | Enable S3 backup CronJob | | backup.schedule | "0 3 * * *" | Backup cron schedule | | backup.s3.endpoint | "" | S3-compatible endpoint URL | | backup.s3.bucket | "" | S3 bucket name | | backup.s3.existingSecret | "" | Existing secret with S3 credentials |

Database Auto-Detection

When database.mode is auto (default), the chart detects which database to use:

  1. If database.external.host is set → external database
  2. If postgresql.enabled is true → PostgreSQL subchart
  3. If mysql.enabled is true → MySQL subchart
  4. Otherwise → SQLite3 (zero configuration)

Only one database source can be active. The chart fails with a clear error if multiple are configured.

Upgrade Notes

The Deployment now defaults to the Recreate strategy for every database mode, not only SQLite. PostgreSQL and MySQL externalize relational data, but Gitea still keeps repositories, queues, indexes, and configuration on the local data volume. Recreate prevents two Gitea processes from using that single-writer state during an upgrade and avoids ReadWriteOnce multi-attach failures. Only override strategy.type after externalizing every shared-state dependency and validating the storage access mode.

This update moves the default rootless image to 28.2.0-rootless. Back up the database, repositories, LFS objects, packages, attachments, and the retained configuration before upgrading; Gitea runs required database migrations during the first startup.

Gitea 28 introduces an internal proxy for Git network operations. Existing ALLOWED_HOST_LIST, BLOCKED_HOST_LIST, ALLOWED_DOMAINS, and BLOCKED_DOMAINS overrides must be reviewed: wildcard and domain matching changed, the external preset was removed, and an exclusive allow list now requires EGRESS_MODE = strict. Configure replacements through gitea.extraEnv with GITEA__security__... variables.

Completed Actions runs now default to 400 days of retention. Set GITEA__actions__RUN_RETENTION_DAYS to 0 before the upgrade if all historical runs must be retained. Review the v28.0.0 migration notes and the v28.2.0 fixes before production rollout. The rootless UID, ports, work directory, data path, and GITEA_APP_INI contract remain compatible with this chart.

SSH Access

The chart creates a separate SSH service. For external SSH access:

service:
  ssh:
    type: NodePort
    nodePort: 30022

Then clone with: git clone ssh://git@<node-ip>:30022/<user>/<repo>.git

Backup

The backup CronJob is database-aware:

  • SQLite: archives the entire /var/lib/gitea directory
  • PostgreSQL: runs pg_dump and compresses the output
  • MySQL: runs mysqldump and compresses the output

All backups are uploaded to S3-compatible storage using the MinIO client.

Pod Security Restricted

The default install avoids root init containers so it can run in namespaces that enforce the Kubernetes restricted Pod Security profile. The chart preserves the rootless Gitea config path at /etc/gitea/app.ini for upgrade compatibility and mounts it from the config subPath on the data PVC.

The built-in wait-for-db init container uses the same restricted container security context as Gitea. It runs as non-root, disables privilege escalation, and drops all Linux capabilities by default.

Set volumePermissions.enabled=true only when your storage class requires an explicit root chown step. That opt-in mode renders a root initContainer with CHOWN/FOWNER; keep it disabled in restricted namespaces unless your policy explicitly allows that init container.

Architecture

The Deployment serves both HTTP and SSH while Kubernetes exposes each protocol through a separate Service. HTTP traffic from Ingress or Gateway API reaches the named http target port; SSH can remain cluster-local or use a dedicated NodePort. A single PVC stores repositories, LFS objects, attachments, SQLite, and the rootless configuration. PostgreSQL and MySQL may be bundled or external. See DESIGN.md and docs/architecture.md for the complete boundaries and data flow.

Troubleshooting

If the pod does not become ready, inspect the startup probe and all containers:

kubectl describe pod -l app.kubernetes.io/name=gitea -n <namespace>
kubectl logs -l app.kubernetes.io/name=gitea -n <namespace> --all-containers --tail=100

For an overridden HTTP listener, confirm GITEA__server__HTTP_PORT, the named container port, and Service endpoints agree. For SQL modes, inspect the wait-for-db init container and verify its Secret key. See operations and backup for the full runbook.

More Information

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  Client --> HttpService[HTTP Service]
  GitClient --> SshService[SSH Service]
  HttpService --> Gitea[Gitea Deployment]
  SshService --> Gitea
  Gitea --> Data[(Persistent Volume)]
  Gitea --> Database[(SQLite, PostgreSQL, or MySQL)]
  Backup[Backup CronJob] --> ObjectStore[(S3-compatible storage)]
Official Contractvalues.schema.json

Gitea Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

169 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Container image repository.
image.tagstring-Image tag (defaults to appVersion-rootless).
image.pullPolicystring-Image pull policy.
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Override the release name.

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Override the full release name.

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger-Number of replicas.

Strategy(3)

ParameterTypeDefaultDescription
strategy.typestring-Chart configuration parameter
Allowed:RecreateRollingUpdate
strategy.rollingUpdate.maxSurgeintegerstring-Chart configuration parameter
strategy.rollingUpdate.maxUnavailableintegerstring-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Additional annotations for the Gitea pod.

Gitea(9)

ParameterTypeDefaultDescription
gitea.appNamestring-Application display name.
gitea.runModestring-Run mode: dev, prod, test.
Allowed:devprodtest
gitea.rootUrlstring-Root URL for Gitea.
gitea.sshDomainstring-SSH domain shown in clone URLs.
gitea.sshPortinteger-SSH listen port.
gitea.lfsEnabledboolean-Enable Git LFS.
gitea.disableRegistrationboolean-Disable user self-registration.
gitea.requireSignInboolean-Require sign-in to view any page.
gitea.extraEnvarray-Extra environment variables.

Admin(4)

ParameterTypeDefaultDescription
admin.usernamestring-Admin username.
admin.passwordstring-Admin password.
admin.emailstring-Admin email.
admin.existingSecretstring-Existing secret with admin credentials.

Database(10)

ParameterTypeDefaultDescription
database.modestring-Database mode: auto | sqlite | external | postgresql | mysql.
Allowed:autosqliteexternalpostgresqlmysql
database.sqlite.filestring-SQLite database file path.
database.external.vendorstring-Database vendor: postgres | mysql.
Allowed:postgresmysql
database.external.hoststring-External database hostname.
database.external.portstringinteger-External database port.
database.external.namestring-Database name.
database.external.usernamestring-Database username.
database.external.passwordstring-Database password.
database.external.existingSecretstring-Existing secret for database password.
database.external.existingSecretPasswordKeystring-Key in the existing secret.

Postgresql(8)

ParameterTypeDefaultDescription
postgresql.enabledboolean-Deploy PostgreSQL as a subchart.
postgresql.architecturestring-PostgreSQL architecture.
Allowed:standalonereplication
postgresql.auth.databasestring-Chart configuration parameter
postgresql.auth.usernamestring-Chart configuration parameter
postgresql.auth.passwordstring-Chart configuration parameter
postgresql.auth.rootPasswordstring-Chart configuration parameter
postgresql.primary.persistence.enabledboolean-Chart configuration parameter
postgresql.primary.persistence.sizestring-Chart configuration parameter

Mysql(8)

ParameterTypeDefaultDescription
mysql.enabledboolean-Deploy MySQL as a subchart.
mysql.architecturestring-MySQL architecture.
Allowed:standalonereplication
mysql.auth.databasestring-Chart configuration parameter
mysql.auth.usernamestring-Chart configuration parameter
mysql.auth.passwordstring-Chart configuration parameter
mysql.auth.rootPasswordstring-Chart configuration parameter
mysql.primary.persistence.enabledboolean-Chart configuration parameter
mysql.primary.persistence.sizestring-Chart configuration parameter

Persistence(6)

ParameterTypeDefaultDescription
persistence.enabledboolean-Enable persistent storage.
persistence.storageClassstring-Storage class.
persistence.accessModestring-PVC access mode.
persistence.sizestring-Volume size.
persistence.existingClaimstring-Existing PVC name.
persistence.annotationsobject-PVC annotations.

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-CPU and memory resources.

Pod Security(6)

ParameterTypeDefaultDescription
podSecurityContext.runAsNonRootboolean-Chart configuration parameter
podSecurityContext.runAsUserinteger-Chart configuration parameter
podSecurityContext.runAsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined

Container Security(6)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.runAsUserinteger-Chart configuration parameter
securityContext.runAsGroupinteger-Chart configuration parameter

Volume Permissions(9)

ParameterTypeDefaultDescription
volumePermissions.enabledbooleanfalseChart configuration parameter
volumePermissions.image.repositorystring-Chart configuration parameter
volumePermissions.image.tagstring-Chart configuration parameter
volumePermissions.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
volumePermissions.securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
volumePermissions.securityContext.capabilities.addarray-Chart configuration parameter
volumePermissions.securityContext.capabilities.droparray-Chart configuration parameter
volumePermissions.securityContext.runAsNonRootboolean-Chart configuration parameter
volumePermissions.securityContext.runAsUserinteger-Chart configuration parameter

Startup Probe(6)

ParameterTypeDefaultDescription
startupProbe.enabledboolean-Chart configuration parameter
startupProbe.pathstring-Chart configuration parameter
startupProbe.initialDelaySecondsinteger-Chart configuration parameter
startupProbe.periodSecondsinteger-Chart configuration parameter
startupProbe.timeoutSecondsinteger-Chart configuration parameter
startupProbe.failureThresholdinteger-Chart configuration parameter

Liveness Probe(6)

ParameterTypeDefaultDescription
livenessProbe.enabledboolean-Chart configuration parameter
livenessProbe.pathstring-Chart configuration parameter
livenessProbe.initialDelaySecondsinteger-Chart configuration parameter
livenessProbe.periodSecondsinteger-Chart configuration parameter
livenessProbe.timeoutSecondsinteger-Chart configuration parameter
livenessProbe.failureThresholdinteger-Chart configuration parameter

Readiness Probe(6)

ParameterTypeDefaultDescription
readinessProbe.enabledboolean-Chart configuration parameter
readinessProbe.pathstring-Chart configuration parameter
readinessProbe.initialDelaySecondsinteger-Chart configuration parameter
readinessProbe.periodSecondsinteger-Chart configuration parameter
readinessProbe.timeoutSecondsinteger-Chart configuration parameter
readinessProbe.failureThresholdinteger-Chart configuration parameter

Container Ports(1)

ParameterTypeDefaultDescription
containerPorts.httpinteger-Chart configuration parameter

Service & Networking(12)

ParameterTypeDefaultDescription
service.http.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.http.portinteger-Chart configuration parameter
service.http.annotationsobject-Chart configuration parameter
service.http.ipFamilyPolicystringnull-Dual-stack ipFamilyPolicy (GR-058)
Allowed:nullSingleStackPreferDualStackRequireDualStack
service.http.ipFamiliesarray-Dual-stack ipFamilies (GR-058)
service.ssh.enabledboolean-Chart configuration parameter
service.ssh.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.ssh.portinteger-Chart configuration parameter
service.ssh.nodePortstringinteger-Chart configuration parameter
service.ssh.annotationsobject-Chart configuration parameter
service.ssh.ipFamilyPolicystringnull-Dual-stack ipFamilyPolicy (GR-058)
Allowed:nullSingleStackPreferDualStackRequireDualStack
service.ssh.ipFamiliesarray-Dual-stack ipFamilies (GR-058)

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Network Policy(2)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingressFromarray-Allowed ingress peers. Empty permits pods in the same namespace; the admin bootstrap Job is always allowed when enabled.

Backup(31)

ParameterTypeDefaultDescription
backup.enabledboolean-Chart configuration parameter
backup.schedulestring-Chart configuration parameter
backup.suspendboolean-Chart configuration parameter
backup.concurrencyPolicystring-Chart configuration parameter
Allowed:ForbidReplaceAllow
backup.successfulJobsHistoryLimitinteger-Chart configuration parameter
backup.failedJobsHistoryLimitinteger-Chart configuration parameter
backup.backoffLimitinteger-Chart configuration parameter
backup.archivePrefixstring-Chart configuration parameter
backup.images.sqlitestring-Chart configuration parameter
backup.images.postgresqlstring-Chart configuration parameter
backup.images.mysqlstring-Chart configuration parameter
backup.images.uploaderstring-Chart configuration parameter
backup.resourcesobject-Chart configuration parameter
backup.s3.endpointstring-Chart configuration parameter
backup.s3.bucketstring-Chart configuration parameter
backup.s3.prefixstring-Chart configuration parameter
backup.s3.createBucketIfNotExistsboolean-Chart configuration parameter
backup.s3.existingSecretstring-Chart configuration parameter
backup.s3.existingSecretAccessKeyKeystring-Chart configuration parameter
backup.s3.existingSecretSecretKeyKeystring-Chart configuration parameter
backup.s3.accessKeystring-Chart configuration parameter
backup.s3.secretKeystring-Chart configuration parameter
backup.database.hoststring-Chart configuration parameter
backup.database.portstringinteger-Chart configuration parameter
backup.database.namestring-Chart configuration parameter
backup.database.usernamestring-Chart configuration parameter
backup.database.passwordstring-Chart configuration parameter
backup.database.existingSecretstring-Chart configuration parameter
backup.database.existingSecretPasswordKeystring-Chart configuration parameter
backup.database.postgresDumpArgsstring-Chart configuration parameter
backup.database.mysqlDumpArgsstring-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

Gateway(6)

ParameterTypeDefaultDescription
gateway.enabledbooleanfalseChart configuration parameter
gateway.annotationsobject-Chart configuration parameter
gateway.parentRefsarray-Chart configuration parameter
gateway.hostnamesarray-Chart configuration parameter
gateway.pathstring/Chart configuration parameter
gateway.pathTypestringPathPrefixChart configuration parameter
Allowed:PathPrefixExactRegularExpression

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseChart configuration parameter
externalSecrets.apiVersionstringexternal-secrets.io/v1Chart configuration parameter
externalSecrets.refreshIntervalstring1hChart configuration parameter
externalSecrets.secretStoreRef.namestring-Chart configuration parameter
externalSecrets.secretStoreRef.kindstring-Chart configuration parameter
externalSecrets.target.creationPolicystring-Chart configuration parameter
externalSecrets.dataarray-Chart configuration parameter