Gitea : configuration

Gitea se configure avec le fichier /etc/gitea/app.ini (format INI, sections entre crochets). Après toute modification, redémarrer le service : sudo systemctl restart gitea. Les exemples utilisent des noms génériques.

Un `app.ini` minimal avec SQLite

APP_NAME = Gitea
RUN_USER = git
RUN_MODE = prod
WORK_PATH = /var/lib/gitea

[database]
DB_TYPE = sqlite3
PATH = /var/lib/gitea/data/gitea.db
SQLITE_JOURNAL_MODE = WAL
SQLITE_TIMEOUT = 5000

[server]
DOMAIN = git.exemple.com
ROOT_URL = https://git.exemple.com/
HTTP_ADDR = 127.0.0.1
HTTP_PORT = 3000

[repository]
ROOT = /var/lib/gitea/data/gitea-repositories
DEFAULT_BRANCH = main

[security]
INSTALL_LOCK = true

[service]
DISABLE_REGISTRATION = true

[log]
MODE = file
LEVEL = Info
ROOT_PATH = /var/lib/gitea/log

Ce fichier a été vérifié avec le binaire de Gitea 28 (démarrage, création de l’administrateur, base en mode WAL).

Base de données SQLite

Clé	Rôle
`DB_TYPE = sqlite3`	Moteur SQLite
`PATH`	Fichier de la base
`SQLITE_JOURNAL_MODE = WAL`	Lectures simultanées à une écriture : recommandé
`SQLITE_TIMEOUT`	Attente (en millisecondes) quand la base est occupée, avant l’erreur « database is locked »

Pour contrôler : sqlite3 /var/lib/gitea/data/gitea.db "PRAGMA journal_mode;" doit afficher wal (voir SQLite : sauvegarde et maintenance).

Domaine et adresses

Clé	Rôle
`[server] DOMAIN`	Nom d’hôte public
`[server] ROOT_URL`	URL complète utilisée dans les liens et les adresses de clonage (avec `https://` et `/` final)
`[server] HTTP_ADDR`, `HTTP_PORT`	Adresse et port d’écoute : `127.0.0.1` quand un reverse proxy est devant
`[server] SSH_DOMAIN`	Nom d’hôte affiché dans les adresses SSH de clonage

SSH

Deux modes :

Mode	Réglage	Remarque
OpenSSH du système (défaut avec l’installation par binaire)	`DISABLE_SSH = false`, `SSH_PORT = 22`	Les clés des utilisateurs sont écrites dans `~git/.ssh/authorized_keys` : adresses `git@git.exemple.com:equipe/depot.git`
Serveur SSH intégré	`START_SSH_SERVER = true`, `SSH_LISTEN_PORT = 2222`, `SSH_PORT = 2222`	Pas de dépendance à OpenSSH, mais autre port : `ssh://git@git.exemple.com:2222/equipe/depot.git`
Pas de SSH	`DISABLE_SSH = true`	Accès HTTPS uniquement

[server]
SSH_DOMAIN = git.exemple.com
SSH_PORT = 22
DISABLE_SSH = false

Avec l’OpenSSH du système, reconstruire le fichier des clés si nécessaire :

gitea-cli admin regenerate keys

(alias défini dans la section « Administration en ligne de commande »).

Comptes et visibilité

[service]
DISABLE_REGISTRATION = true             ; pas d'inscription libre
REQUIRE_SIGNIN_VIEW = true              ; contenu visible seulement après connexion
DEFAULT_KEEP_EMAIL_PRIVATE = true
ENABLE_NOTIFY_MAIL = true               ; notifications par e-mail
DEFAULT_ALLOW_CREATE_ORGANIZATION = false

Avec DISABLE_REGISTRATION = true, les comptes se créent par un administrateur (interface ou gitea admin user create).

E-mail

[mailer]
ENABLED = true
PROTOCOL = smtp+starttls
SMTP_ADDR = smtp.exemple.com
SMTP_PORT = 587
FROM = Gitea <gitea@exemple.com>
USER = gitea@exemple.com
PASSWD = <mot-de-passe>

Le fichier app.ini contient alors un mot de passe : le restreindre (chmod 640, propriétaire root:git). Tester l’envoi depuis l’interface d’administration (Configuration, e-mail).

Dépôts

[repository]
ROOT = /var/lib/gitea/data/gitea-repositories
DEFAULT_BRANCH = main
DISABLE_HTTP_GIT = false
ENABLE_PUSH_CREATE_USER = true          ; créer un dépôt en poussant vers une adresse inexistante
MAX_CREATION_LIMIT = -1                 ; -1 : pas de limite par utilisateur

[repository.upload]
FILE_MAX_SIZE = 50                      ; Mo, envoi de fichiers par l'interface

Journaux

[log]
MODE = file
LEVEL = Info
ROOT_PATH = /var/lib/gitea/log

Niveau	Usage
`Info`	Fonctionnement normal
`Warn`, `Error`	Seulement les problèmes
`Debug`, `Trace`	Diagnostic (volumineux)

sudo journalctl -u gitea -f
sudo tail -f /var/lib/gitea/log/gitea.log

Variables d’environnement

Chaque clé peut être définie par une variable GITEA__SECTION__CLE (pratique pour les conteneurs) :

GITEA__server__ROOT_URL=https://git.exemple.com/
GITEA__service__DISABLE_REGISTRATION=true
GITEA__database__DB_TYPE=sqlite3

Reverse proxy avec Caddy

git.exemple.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000
    request_body {
        max_size 100MB
    }
    header {
        Strict-Transport-Security "max-age=31536000"
        X-Content-Type-Options "nosniff"
        -Server
    }
}

Voir les exemples de Caddyfile. Fermer ensuite le port 3000 au public (le service n’écoute que sur 127.0.0.1 avec HTTP_ADDR).

Vérifier la configuration

gitea-cli doctor check --all             # diagnostic complet (voir « Administration »)
curl -s https://git.exemple.com/api/v1/version
sudo systemctl status gitea

Dépannage

Symptôme	Piste
Les modifications de `app.ini` ne sont pas prises en compte	Redémarrer : `sudo systemctl restart gitea`
Boucle de redirection derrière le proxy	`ROOT_URL` en `https://` et `HTTP_ADDR`/`HTTP_PORT` alignés sur `reverse_proxy`
`database is locked`	Mode WAL et `SQLITE_TIMEOUT` (voir plus haut) ; vérifier qu’une sauvegarde ne verrouille pas la base
Adresse de clonage SSH erronée	`SSH_DOMAIN` et `SSH_PORT`
Le service ne démarre plus après modification	`sudo journalctl -u gitea -n 50` : erreur de syntaxe ou chemin inexistant

Pour aller plus loin

Référence : Configuration Cheat Sheet
Suite : Administration en ligne de commande