Gitea : dépôts, accès et API

Gestion des dépôts, des accès et automatisation par l’API REST. Les exemples utilisent le serveur fictif git.exemple.com, l’organisation equipe et le dépôt monprojet.

Se connecter depuis Git

Clé SSH

Générer une clé (voir Git : installation) et copier la clé publique : cat ~/.ssh/id_ed25519.pub.
Dans Gitea : Paramètres (menu du compte), Clés SSH / GPG, Ajouter une clé.
Tester :

ssh -T git@git.exemple.com
git clone git@git.exemple.com:equipe/monprojet.git

Jeton d’accès (HTTPS)

Dans Gitea : Paramètres, Applications, Générer un nouveau jeton (avec les portées minimales). Utiliser le jeton à la place du mot de passe :

git clone https://alice:<jeton>@git.exemple.com/equipe/monprojet.git

Ne pas laisser le jeton dans l’URL des dépôts : configurer un gestionnaire d’identifiants ou utiliser SSH.

Créer un dépôt

Interface : bouton + en haut, Nouveau dépôt. Par la ligne de commande :

git init monprojet && cd monprojet
git add . && git commit -m "feat: initial commit"
git branch -M main
git remote add origin git@git.exemple.com:equipe/monprojet.git
git push -u origin main

Avec ENABLE_PUSH_CREATE_USER = true dans app.ini, pousser vers un dépôt inexistant le crée automatiquement.

API REST

L’API est documentée par une page Swagger sur votre instance : https://git.exemple.com/api/swagger. Authentification : jeton dans l’en-tête Authorization: token ….

export GITEA=https://git.exemple.com/api/v1
export TOKEN=<jeton>
api() { m=$1; u=$2; shift 2; curl -s -X "$m" -H "Authorization: token $TOKEN" -H "Content-Type: application/json" "$GITEA$u" "$@"; }

La fonction api raccourcit les appels suivants (méthode, chemin, options de curl).

Version et utilisateur courant

curl -s "$GITEA/version"
api GET /user

Organisation et dépôt

api POST /orgs -d '{"username":"equipe","visibility":"private"}'
api POST /orgs/equipe/repos -d '{"name":"monprojet","private":true,"auto_init":true,"default_branch":"main"}'
api GET "/repos/search?q=monprojet&limit=5"
api DELETE /repos/equipe/monprojet                    # suppression : définitive

Collaborateurs et équipes

api PUT /repos/equipe/monprojet/collaborators/alice -d '{"permission":"write"}'     # read, write, admin
api GET /repos/equipe/monprojet/collaborators
api DELETE /repos/equipe/monprojet/collaborators/alice

Pour des groupes d’utilisateurs, créer des équipes dans l’organisation (interface : Organisation, Équipes), avec des droits par dépôt.

Protection de la branche principale

api POST /repos/equipe/monprojet/branch_protections \
  -d '{"rule_name":"main","enable_push":false,"required_approvals":1}'
api GET /repos/equipe/monprojet/branch_protections

Le push direct sur main est alors refusé : les changements passent par une demande de fusion approuvée au moins une fois.

Webhooks

api POST /repos/equipe/monprojet/hooks \
  -d '{"type":"gitea","config":{"url":"https://exemple.com/hook","content_type":"json"},"events":["push"],"active":true}'
api GET /repos/equipe/monprojet/hooks

Releases et tags

api POST /repos/equipe/monprojet/releases -d '{"tag_name":"v1.0.0","name":"Version 1.0.0","body":"Première version"}'
api GET /repos/equipe/monprojet/releases

Tickets et demandes de fusion

api POST /repos/equipe/monprojet/issues -d '{"title":"Erreur à la connexion","body":"Détails…"}'
api GET "/repos/equipe/monprojet/pulls?state=open"

Migrer et dupliquer des dépôts

Besoin	Méthode
Importer un dépôt depuis un autre serveur (avec tickets et demandes de fusion)	Interface : +, Nouvelle migration (ou `POST /repos/migrate`)
Copie miroir qui se met à jour (lecture)	Migration avec l’option miroir (pull mirror)
Envoyer automatiquement vers un autre serveur	Dépôt, Paramètres, Dépôt, Miroirs (push mirror)
Déplacer un dépôt entre serveurs sans historique des tickets	`git clone --mirror` puis `git push --mirror` (voir Git : dépôts distants)

Utilisateurs et droits : bonnes pratiques

Un compte par personne, jamais de compte partagé.
Des jetons limités aux portées nécessaires, un par usage (CI, script), révocables séparément.
Des organisations et équipes pour les droits d’accès par dépôt.
La double authentification (Paramètres, Sécurité) pour tous, et obligatoire pour les administrateurs.
La protection de branche sur main.

Dépannage

Symptôme	Piste
`Permission denied (publickey)`	Clé non enregistrée dans Gitea, ou mauvais `SSH_PORT`/`SSH_DOMAIN` (voir Configuration)
`HTTP 401` avec l’API	Jeton absent, expiré ou sans la portée requise
`HTTP 404` pour un dépôt privé	Compte sans droit sur ce dépôt (Gitea répond 404 plutôt que 403)
`push` refusé : branche protégée	Passer par une branche et une demande de fusion
`fatal: repository … not found`	Mauvais chemin `propriétaire/dépôt` ou accès refusé

Pour aller plus loin

API : page Swagger de l’instance (/api/swagger) et docs.gitea.com/api
Suite : Sauvegarde et restauration