Configurer Gitea après l'installation

Une fois Gitea installé et démarré, quelques ajustements dans app.ini transforment votre instance en un serveur prêt pour la production : inscriptions fermées, SSH configuré, mailer opérationnel, et sécurité renforcée.

Toute la configuration de Gitea tient dans un seul fichier : /etc/gitea/app.ini. Les changements prennent effet après un redémarrage du service.

Structure de app.ini

app.ini suit le format INI standard, organisé en sections entre crochets. Les sections principales d’une installation standard sont :

APP_NAME = Mon Gitea        # Nom affiché dans l'interface
RUN_USER = git
RUN_MODE = prod              # prod = logs réduits, erreurs masquées aux utilisateurs

[server]          # URL, ports, SSH
[database]        # Type et chemin de la base
[security]        # Tokens, hashage des mots de passe
[service]         # Inscriptions, e-mail de confirmation
[mailer]          # Envoi d'e-mails (notifications, reset de mot de passe)
[log]             # Niveau et format des journaux
[repository]      # Répertoire des dépôts

La liste complète des options est disponible dans la documentation officielle.

Désactiver les inscriptions publiques

Par défaut, toute personne qui accède à l’interface web peut créer un compte. Pour un usage interne ou en équipe, désactivez cette option immédiatement.

sudo nano /etc/gitea/app.ini

Dans la section [service] :

[service]
DISABLE_REGISTRATION = true   # Seul l'admin peut créer des comptes
REQUIRE_SIGNIN_VIEW  = true   # Les dépôts publics nécessitent une connexion pour être vus

L’admin peut toujours créer des comptes via la CLI ou l’interface web (Administration > Utilisateurs) :

sudo -u git GITEA_WORK_DIR=/var/lib/gitea \
  gitea admin user create \
  --config /etc/gitea/app.ini \
  --username alice \
  --password 'MotDePasse123!' \
  --email alice@example.com \
  --must-change-password=true

L’option --must-change-password=true force l’utilisateur à changer son mot de passe à la première connexion.

Configurer l’URL externe

L’ROOT_URL est l’URL publique de votre instance. Elle est utilisée dans les liens de clonage, les webhooks, et les e-mails de notification.

[server]
DOMAIN   = gitea.monentreprise.com
ROOT_URL = https://gitea.monentreprise.com/
HTTP_PORT = 3000

Configurer SSH

Gitea propose deux modes pour SSH :

SSH intégré — Gitea gère son propre serveur SSH sur un port dédié (recommandé si le port 22 est occupé par sshd)
SSH système — Gitea utilise sshd du système via un script authorized_keys (recommandé pour le port 22 standard)

SSH système (port 22)
SSH intégré (autre port)

Pour utiliser le port 22, Gitea doit pouvoir écrire dans /home/git/.ssh/authorized_keys. L’utilisateur git doit être dans le groupe sshd ou le fichier doit être accessible.

[server]
DISABLE_SSH              = false
SSH_DOMAIN               = gitea.monentreprise.com
SSH_PORT                 = 22
SSH_CREATE_AUTHORIZED_HOSTS_FILE = true

Configurez sshd pour déléguer les clés Git à Gitea :

# Créer le répertoire SSH pour l'utilisateur git
sudo -u git mkdir -p /home/git/.ssh
sudo chmod 700 /home/git/.ssh

# Gitea gère authorized_keys automatiquement lors de l'ajout de clés dans l'interface web

Le serveur SSH intégré de Gitea s’exécute sur un port dédié, indépendamment de sshd. Utile si sshd est déjà sur le port 22 et que vous ne pouvez pas le déplacer.

[server]
DISABLE_SSH      = false
SSH_DOMAIN       = gitea.monentreprise.com
SSH_PORT         = 2222          # Port public affiché dans les URLs de clonage
START_SSH_SERVER = true           # Activer le serveur SSH intégré
SSH_LISTEN_PORT  = 2222          # Port sur lequel Gitea écoute réellement

Les utilisateurs cloneront avec : git@gitea.monentreprise.com:2222:user/repo.git

Configurer le mailer

Le mailer est nécessaire pour les notifications (nouvelles issues, mentions, reset de mot de passe).

SMTP standard
Gmail / OAuth2

[mailer]
ENABLED       = true
FROM          = gitea@monentreprise.com
PROTOCOL      = smtp+starttls
SMTP_ADDR     = smtp.monentreprise.com
SMTP_PORT     = 587
USER          = gitea@monentreprise.com
PASSWD        = `monmotdepasse`    # Entouré de backticks pour échapper les caractères spéciaux

[mailer]
ENABLED        = true
FROM           = moncompte@gmail.com
PROTOCOL       = smtp+starttls
SMTP_ADDR      = smtp.gmail.com
SMTP_PORT      = 587
USER           = moncompte@gmail.com
PASSWD         = `mot_de_passe_application`

Utilisez un mot de passe d’application Google, pas votre mot de passe principal.

Pour tester l’envoi :

# Envoyer un mail de test (redémarre le service d'abord)
sudo systemctl restart gitea.service
# Puis dans l'interface : Administration > E-mail de test

Sécuriser les tokens

Gitea génère deux tokens critiques au premier démarrage :

Token	Rôle
`SECRET_KEY`	Signature des cookies de session et des tokens API
`INTERNAL_TOKEN`	Communication interne entre processus Gitea

Ces valeurs sont automatiquement générées. Ne les modifiez pas après le premier démarrage — cela invaliderait toutes les sessions actives et les tokens API existants.

Pour vérifier qu’ils sont bien présents :

sudo grep -E 'SECRET_KEY|INTERNAL_TOKEN' /etc/gitea/app.ini

Les deux lignes doivent avoir des valeurs non vides.

Personnaliser les limites

Pour un usage intensif, ajustez les paramètres de performance :

[repository]
MAX_CREATION_LIMIT = -1       # -1 = illimité par utilisateur

[service]
MAX_DISPLAY_FILE_SIZE = 8388608   # 8 Mo — taille max d'affichage du code en ligne

[server]
MAX_DISPLAY_FILE_SIZE = 8388608
LANDING_PAGE          = login     # Page d'accueil : login | home | explore

Appliquer les changements

Chaque modification de app.ini nécessite un redémarrage du service :

sudo systemctl restart gitea.service

# Vérifier qu'il redémarre correctement
sudo systemctl status gitea.service --no-pager -l

Vérifier la configuration effective

Gitea peut afficher la configuration telle qu’elle est interprétée :

sudo -u git GITEA_WORK_DIR=/var/lib/gitea \
  gitea doctor check --all \
  --config /etc/gitea/app.ini 2>&1 | tail -20

Un résultat sans [E] (erreur) confirme que la configuration est cohérente.

À retenir

Toute la configuration tient dans /etc/gitea/app.ini — un fichier à sauvegarder en priorité
INSTALL_LOCK = true et DISABLE_REGISTRATION = true sont les deux premières mesures de sécurité
ROOT_URL doit correspondre exactement à l’URL d’accès réelle des utilisateurs
Tout changement dans app.ini nécessite un systemctl restart gitea.service
gitea doctor check --all valide la cohérence de la configuration

Prochaines étapes

Sauvegarder et restaurer Mettre en place une stratégie de backup avec gitea dump.

Mettre à jour Gitea Procédure d'upgrade : flush-queues, backup, remplacement binaire.