Gitea : administration en ligne de commande

La commande gitea offre des outils d’administration, utiles quand l’interface web est inaccessible ou pour automatiser. Les exemples ont été exécutés sur Gitea 28.

Lancer les commandes

Les commandes s’exécutent avec l’utilisateur du service (git) et en indiquant le fichier de configuration :

alias gitea-cli='sudo -u git gitea --config /etc/gitea/app.ini --work-path /var/lib/gitea'

gitea-cli admin user list

Sans alias, la forme complète est sudo -u git gitea --config /etc/gitea/app.ini --work-path /var/lib/gitea admin user list.

Utilisateurs

gitea-cli admin user list
gitea-cli admin user create --admin --username admin --email admin@exemple.com --password 'mot_de_passe_provisoire' --must-change-password
gitea-cli admin user create --username alice --email alice@exemple.com --password 'mot_de_passe_provisoire' --must-change-password=false
gitea-cli admin user change-password --username alice --password 'nouveau_mot_de_passe' --must-change-password=false
gitea-cli admin user must-change-password alice bob       # impose le changement au prochain accès
gitea-cli admin user disable-2fa --username alice         # désactive la double authentification d'un compte
gitea-cli admin user delete --username alice              # supprime (ou --id, --email)
gitea-cli admin user change-type --username robot --user-type Bot   # convertit en compte robot (ou --user-type User)

Exemple de résultat de admin user list :

ID   Username Email             IsActive IsAdmin 2FA
1    admin    admin@exemple.com true     true    false
2    alice    alice@exemple.com true     false   false

Pour ne pas laisser un mot de passe dans l’historique du shell, utiliser --random-password (mot de passe généré et affiché, 12 caractères par défaut, longueur réglable avec --random-password-length), ou l’interface web. L’option --must-change-password impose le changement à la première connexion (activée par défaut pour tous les comptes sauf le premier).

Jetons d’accès

gitea-cli admin user generate-access-token --username alice --token-name ci --scopes "write:repository"

Le jeton (40 caractères hexadécimaux) est affiché une seule fois. Portées courantes : read:repository, write:repository, read:user, write:issue, all. Voir Dépôts, accès et API.

Jeton d’enregistrement d’un runner

gitea-cli actions generate-runner-token

Voir Gitea Actions (CI).

Régénérer des fichiers

gitea-cli admin regenerate hooks         # réinstalle les hooks Git de tous les dépôts (après une restauration ou un déplacement)
gitea-cli admin regenerate keys          # reconstruit ~git/.ssh/authorized_keys
gitea-cli admin repo-sync-releases       # resynchronise les versions avec les tags

Authentification externe

gitea-cli admin auth list                # sources d'authentification (LDAP, OAuth2…)

Diagnostic : `doctor`

gitea-cli doctor check --list            # liste des vérifications disponibles
gitea-cli doctor check --all             # exécute tous les contrôles (13 dans Gitea 28)
gitea-cli doctor check --all --fix       # corrige automatiquement ce qui peut l'être
gitea-cli doctor check --run check-db-consistency

Les contrôles couvrent la cohérence de la base, les hooks, les graphes de commits, l’espace disque, les droits. À lancer après une restauration ou une mise à jour.

Pilotage du processus en cours : `manager`

gitea-cli manager processes              # processus en cours dans Gitea
gitea-cli manager flush-queues           # vide les files de traitement
gitea-cli manager reload-templates       # recharge les modèles personnalisés
gitea-cli manager logging --help         # ajuster la journalisation à chaud
gitea-cli manager shutdown               # arrêt propre

Générer des secrets

gitea generate secret SECRET_KEY         # clé secrète
gitea generate secret INTERNAL_TOKEN
gitea generate secret JWT_SECRET
gitea generate secret LFS_JWT_SECRET

Ces valeurs se placent dans app.ini (section [security], [server], [oauth2]). Elles sont créées automatiquement à l’installation : ne les régénérer que si nécessaire (changer SECRET_KEY rend illisibles les données chiffrées).

Envoyer un message à tous les utilisateurs

gitea-cli admin sendmail --title "Maintenance" --content "Gitea sera indisponible dimanche de 2 h à 3 h."

Nécessite la configuration [mailer].

Dépannage

Symptôme	Piste
`Failed to load config`	Indiquer `--config /etc/gitea/app.ini`
`permission denied`	Exécuter avec `sudo -u git`, pas en `root`
`database is locked`	Le service Gitea tient la base : réessayer, ou arrêter le service pour une opération longue
Un utilisateur ne peut plus se connecter	`admin user change-password` ; si double authentification : `admin user disable-2fa`
Les dépôts refusent les pushs après une restauration	`admin regenerate hooks`

Pour aller plus loin

Documentation : Command Line
Suite : Dépôts, accès et API