Introduction

Qu’est-ce que gitrust ?

gitrust est une forge Git self-hosted écrite en Rust, conçue pour les équipes de 3 à 20 personnes qui souhaitent maîtriser leur infrastructure de développement. Elle offre un serveur HTTP (:4000) et SSH (:2222), une CI intégrée via Dagger, la génération de SBOM avec Syft et l’intégration Dependency-Track, une gestion fine des permissions (4 rôles), la double authentification, des labels hiérarchiques et une conformité ANSSI PA-074.

Une instance publique de démonstration est accessible sur demo.gitrust.eu.

À qui s’adresse cette documentation ?

Cette documentation est organisée en quatre parties selon leurs publics respectifs :

• Manuel utilisateur — pour les développeurs qui utilisent une instance gitrust existante : push/pull, pull requests, issues, CI, notifications. Prérequis : savoir utiliser Git en ligne de commande.
• Manuel d’administration — pour les ops et self-hosters qui déploient, configurent et maintiennent une instance en production. Prérequis : administration Linux, notions de réseau et TLS.
• Manuel développeur — pour les contributeurs au code gitrust et les développeurs qui construisent des intégrations sur l’API publique. Prérequis : Rust (pour contribuer) ou un langage client (pour l’API).
• Bibliothèque de templates — pour tous les profils, lorsqu’ils cherchent un point de départ prêt à l’emploi (fichiers .env, docker-compose.yml, configs reverse-proxy, scripts de backup, exemples de clients API).

Comment cette documentation est-elle structurée ?

Cette documentation suit le cadre Diátaxis, qui distingue quatre types de contenu selon le besoin du lecteur :

Chaque manuel (utilisateur, administration, développeur) contient ces quatre types de contenu organisés de manière indépendante.

Naviguer dans la documentation

• Manuel utilisateur — collaborer sur gitrust en tant que développeur
• Manuel d’administration — déployer et exploiter une instance
• Manuel développeur — contribuer au code ou consommer l’API
• Bibliothèque de templates — configs et scripts copiables

Manuel utilisateur

Ce manuel t’accompagne depuis ta première connexion à une instance gitrust jusqu’à l’autonomie complète : pousser du code, collaborer via les pull requests, gérer les issues et automatiser tes workflows avec la CI intégrée. Tu n’as pas besoin d’administrer ni de comprendre l’architecture interne — ce manuel suppose seulement que tu sais utiliser Git en ligne de commande.

Parcours d’apprentissage

Le manuel est structuré comme un parcours progressif de 4 tutoriels. Chaque tutoriel te laisse dans un état stable, vérifié, avant de passer au suivant. L’aide fournie recule d’un cran à chaque étape (du copier-coller intégral vers la composition autonome).

graph LR
    A[Compte créé] --> B[01-premier-pas<br/>20 min]
    B --> C[02-cloner-pousser<br/>25 min]
    C --> D[03-collaborer<br/>25 min]
    D --> E[04-automatiser-ci<br/>20 min]
    E --> F[Utilisateur autonome]

Checkpoint de parcours : avant de passer au tutoriel 02, tu dois pouvoir te connecter à gitrust, voir ton dépôt dans l’interface et l’accès SSH configuré. Si ce n’est pas le cas, relis le tutoriel 01.

Checkpoint de parcours : avant le tutoriel 03, tu dois avoir poussé au moins un commit sur ta branche via SSH. Si ce n’est pas le cas, relis le tutoriel 02.

Checkpoint de parcours : avant le tutoriel 04, tu dois avoir ouvert et mergé une pull request. Si ce n’est pas le cas, relis le tutoriel 03.

Tutoriels — apprendre en faisant

Les tutoriels sont guidés pas-à-pas avec des sorties verbatim attendues. Suis-les dans l’ordre — chacun suppose le précédent complété.

• 01 — Premiers pas : 2FA, clé SSH, premier dépôt — ~20 min
• 02 — Cloner et pousser du code — ~25 min
• 03 — Collaborer : équipes, issues, pull requests — ~25 min
• 04 — Automatiser avec la CI — ~20 min

How-to — recettes pour les tâches courantes

Les how-to répondent à « comment faire X » sans explication de fond. Tu peux les consulter dans n’importe quel ordre selon ton besoin immédiat.

Ces guides supposent que tu as suivi le parcours tutoriels. Ils ne répètent pas les étapes de base.

• Gérer ses clés SSH
• Configurer la 2FA
• Créer un Personal Access Token
• Gérer les équipes et permissions
• Ouvrir une pull request
• Fusionner : fast-forward, squash, merge commit
• Utiliser les labels hiérarchiques
• Importer un dépôt externe
• Consulter le SBOM de ton projet

Référence — informations techniques exactes

La référence est destinée à la consultation ponctuelle, pas à la lecture linéaire. Elle documente les formats, schémas et comportements exacts.

• Modèle de permissions (4 rôles)
• API REST v1 — authentification, pagination, codes d’erreur
• Schéma YAML .gitrust-ci.yml (Easy Mode)
• Syntaxe Markdown supportée
• Notifications : SSE, e-mail, préférences

Explication — comprendre le pourquoi

Les explanations t’aident à construire des modèles mentaux durables. Lis-les quand tu veux comprendre pourquoi gitrust fonctionne ainsi, pas seulement comment.

• Modèle de collaboration gitrust
• Sécurité utilisateur : 2FA, PAT, audit log
• Cycle de vie d’une pull request

Tutoriels — Apprendre gitrust pas à pas

Les tutoriels sont des parcours d’apprentissage guidés. Leur rôle est de te faire acquérir des compétences en te faisant réaliser quelque chose de concret — pas de t’informer sur des fonctionnalités. Chaque tutoriel te laisse dans un état précis, avec quelque chose qui fonctionne réellement.

Mode Diátaxis : Tutorial. Si tu cherches à accomplir une tâche précise que tu sais déjà faire, consulte les guides pratiques. Si tu veux comprendre pourquoi gitrust fonctionne ainsi, consulte les explications.

Parcours utilisateur (~90 min)

graph LR
    A[Compte créé] --> B["01 — Premiers pas<br/>~20 min"]
    B --> C["02 — Cloner et pousser<br/>~25 min"]
    C --> D["03 — Collaborer<br/>~25 min"]
    D --> E["04 — Automatiser CI<br/>~20 min"]
    E --> F[Utilisateur autonome]

    style A fill:#e8f4e8
    style F fill:#e8f4e8

État initial : tu as un compte gitrust actif et Git installé sur ta machine. État final : tu pousses du code, collabores en équipe via issues et PRs, et bénéficies d’une CI automatique.

Le niveau d’aide diminue progressivement d’un tutoriel à l’autre — c’est volontaire :

Les quatre tutoriels

01 — Premiers pas : active la 2FA, ajoute ta clé SSH et crée ton premier dépôt

Active l’authentification à deux facteurs, enregistre ta première clé SSH et crée un dépôt vide. Point d’entrée obligatoire du parcours.

Bloom : O1 Activer (2FA) · O2 Enregistrer (clé SSH) · O3 Créer (dépôt)

02 — Cloner et pousser du code

Génère une clé SSH ed25519, clone ton dépôt en local et pousse ton premier commit. Tu vérifies ensuite le résultat dans l’interface web.

Bloom : O1 Générer (clé SSH) · O2 Cloner (dépôt via SSH) · O3 Pousser (commit)

Avant de commencer : le tutoriel 01 doit être complété — tu dois avoir un dépôt créé et un compte actif.

03 — Collaborer : équipes, issues et pull requests

Crée une équipe, invite un coéquipier, ouvre une issue, travaille sur une branche et soumets ta première pull request. Tu la fusionnes et vérifies que l’issue se ferme automatiquement.

Bloom : O1 Créer (équipe) · O2 Ouvrir (issue) · O3 Ouvrir et fusionner (PR)

Avant de commencer : le tutoriel 02 doit être complété — tu dois avoir un dépôt cloné en local.

04 — Automatiser les tests avec la CI intégrée

Écris un fichier .gitrust-ci.yml minimal, pousse-le et observe le pipeline s’exécuter en temps réel. Tu lis le statut et les logs sur /{owner}/{repo}/ci.

Bloom : O1 Écrire (config CI) · O2 Déclencher (pipeline) · O3 Lire (résultats)

Avant de commencer : le tutoriel 03 doit être complété — tu dois avoir collaboré sur au moins une PR.

Checkpoint de parcours

Tu es prêt pour le tutoriel 03 si : tu peux exécuter git push origin main depuis ton dépôt local sans erreur d’authentification. Sinon, relis le tutoriel 02.

Tu es prêt pour le tutoriel 04 si : tu peux ouvrir une PR, la faire reviewer et la fusionner. Sinon, relis le tutoriel 03.

Après les tutoriels

Une fois les quatre tutoriels complétés, tu n’as plus besoin d’un guide pas-à-pas. Consulte :

• Les guides pratiques pour des recettes ciblées (gérer les clés SSH, configurer la 2FA, importer un dépôt…)
• La référence pour les tableaux de permissions, le schéma CI, l’API REST
• Les explications pour comprendre le modèle de collaboration, la sécurité et le cycle de vie d’une PR

Premiers pas : active la 2FA, ajoute ta clé SSH et crée ton premier dépôt

Objectifs

À la fin de ce tutoriel, tu sauras :

• O1. Activer l’authentification à deux facteurs (2FA) sur ton compte gitrust
• O2. Enregistrer une clé SSH publique dans ton profil pour te connecter sans mot de passe
• O3. Créer un dépôt vide et vérifier qu’il est accessible à l’URL attendue

Pré-requis

• Technique : un compte gitrust existant (e-mail + mot de passe), Git installé (git --version répond), une paire de clés SSH générée ou à générer (ssh-keygen)
• Pédagogique : aucun tutoriel préalable requis — c’est le point de départ du parcours
• Temps estimé : ~20 minutes

Vue d’ensemble

Avant de taper la première commande, prenons 2 minutes pour comprendre ce que tu vas faire et pourquoi.

Un dépôt (repository), c’est comme un dossier de projet avec tout l’historique de ses modifications — une boîte d’archives vivante que Git surveille. Sur gitrust, ce dossier vit sur le serveur et peut être partagé avec ton équipe.

Une clé SSH fonctionne comme une serrure et une clé : tu gardes la clé privée sur ta machine (ne la partage jamais), et tu déposes la clé publique dans ton profil gitrust. Ensuite, Git se connecte automatiquement sans te redemander de mot de passe — gitrust reconnaît ta machine.

La 2FA (authentification à deux facteurs) ajoute un second verrou à ton compte : même si quelqu’un vole ton mot de passe, il ne peut pas se connecter sans le code de ton téléphone. C’est une protection essentielle pour tout compte qui héberge du code.

Voici le flux que tu vas configurer :

sequenceDiagram
    participant T as Ton navigateur
    participant G as gitrust (HTTPS :4000)
    participant S as Ton terminal (SSH :2222)

    T->>G: Connexion avec e-mail + mdp + code 2FA
    T->>G: Dépôt de la clé SSH publique
    S->>G: git push via SSH (authentifié par clé)
    G-->>T: Dépôt visible dans l'interface web

Étape 1 : Connecte-toi et accède aux paramètres de sécurité

Ouvre ton navigateur et va sur l’URL de ton instance gitrust (par exemple https://demo.gitrust.eu). Connecte-toi avec ton e-mail et ton mot de passe.

Une fois connecté, clique sur ton avatar en haut à droite, puis sur Paramètres (/settings). Dans le menu de gauche, sélectionne Sécurité.

Checkpoint : tu dois voir la page Sécurité avec une section « Authentification à deux facteurs » et le statut « Désactivée ». Si tu ne la vois pas, vérifie que tu es bien connecté avec le bon compte.

Étape 2 : Active la 2FA avec une application d’authentification

Sur la page Sécurité, clique sur Activer la 2FA. gitrust affiche un QR code.

1. Ouvre ton application d’authentification (Google Authenticator, Authy, ou tout équivalent compatible TOTP).
2. Scanne le QR code avec l’application.
3. L’application affiche un code à 6 chiffres qui change toutes les 30 secondes.
4. Saisis ce code dans le champ Code de vérification et clique Confirmer.

Sortie attendue (message dans l’interface) :

La 2FA a été activée avec succès.
Conservez vos codes de secours dans un endroit sûr.

gitrust affiche également 10 codes de secours (format XXXX-XXXX). Copie-les et conserve-les hors ligne — ils te permettent de récupérer l’accès si tu perds ton téléphone.

Checkpoint : retourne sur Paramètres → Sécurité. La section 2FA doit maintenant afficher « Activée » en vert. Si elle affiche toujours « Désactivée », recommence l’étape en t’assurant que le code à 6 chiffres est saisi avant qu’il expire.

Étape 3 : Génère ou localise ta clé SSH

Si tu n’as pas encore de paire de clés SSH, génère-en une maintenant dans ton terminal :

ssh-keygen -t ed25519 -C "mon-compte@example.com"

Sortie attendue :

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/toi/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/toi/.ssh/id_ed25519
Your public key has been saved in /home/toi/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx mon-compte@example.com

Appuie sur Entrée pour accepter le chemin par défaut. Tu peux choisir une passphrase ou laisser vide (appuie deux fois sur Entrée). Une passphrase ajoute une couche de sécurité.

Affiche maintenant ta clé publique (le fichier .pub — celui-ci est fait pour être partagé) :

cat ~/.ssh/id_ed25519.pub

Sortie attendue (une seule ligne) :

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx mon-compte@example.com

Copie cette ligne entière dans le presse-papier.

Checkpoint : la commande cat doit afficher une ligne commençant par ssh-ed25519 (ou ssh-rsa si tu as une clé plus ancienne). Si elle affiche « No such file or directory », la génération n’a pas abouti — relance ssh-keygen.

Étape 4 : Enregistre la clé SSH dans ton profil gitrust

Dans ton navigateur, retourne sur Paramètres et clique sur Clés SSH dans le menu de gauche.

Clique sur Ajouter une clé SSH. Un formulaire apparaît :

• Titre : donne un nom descriptif à cette clé (ex. laptop-perso-2026, poste-bureau)
• Clé : colle la ligne copiée à l’étape précédente

Clique Enregistrer la clé.

Sortie attendue (message dans l’interface) :

Clé SSH ajoutée avec succès.

Teste maintenant la connexion SSH depuis ton terminal :

ssh -T git@demo.gitrust.eu -p 2222

Sortie attendue :

Bonjour tonpseudo ! Vous êtes authentifié, mais gitrust ne fournit pas d'accès shell.

Checkpoint : si tu obtiens ce message, ta clé SSH est correctement enregistrée. Si tu obtiens Permission denied (publickey), vérifie que tu as bien copié la clé publique (.pub) et non la clé privée. Consulte la section « Et si ça ne marche pas » ci-dessous.

Étape 5 : Crée ton premier dépôt vide

Dans ton navigateur, clique sur le + en haut à droite (ou navigue vers /repo/new).

Remplis le formulaire :

• Propriétaire : ton pseudo
• Nom du dépôt : mon-premier-depot (lettres, chiffres, tirets uniquement)
• Visibilité : Privé (ou Public selon ta préférence)
• Initialiser le dépôt : coche « Ajouter un README »

Clique sur Créer le dépôt.

Sortie attendue : gitrust te redirige vers la page du dépôt à l’URL :

https://demo.gitrust.eu/tonpseudo/mon-premier-depot

La page affiche un fichier README.md avec le nom du dépôt, et la barre latérale montre 1 commit, 1 branche (main).

Checkpoint : note l’URL affichée dans la barre d’adresse de ton navigateur. Elle doit correspondre au patron https://<instance>/<pseudo>/<nom-depot>. Si tu vois une erreur 404 ou 500, relis le formulaire de création.

Récapitulatif

• ✓ O1 accompli : la 2FA est activée sur ton compte — tu l’as vérifiée sur la page Sécurité qui affiche « Activée »
• ✓ O2 accompli : ta clé SSH publique est enregistrée — tu l’as confirmée avec ssh -T git@... -p 2222 qui a répondu « Vous êtes authentifié »
• ✓ O3 accompli : ton premier dépôt est créé et visible à l’URL /<pseudo>/mon-premier-depot

Et si ça ne marche pas

Prochaine étape

→ 02 — Cloner et pousser du code : clone ton dépôt en local avec SSH, fais ton premier commit et pousse-le sur gitrust (~25 min)

Cloner un dépôt et pousser ton premier commit

Objectifs

À la fin de ce tutoriel, tu sauras :

• O1. Générer une clé SSH ed25519 et la déclarer dans ton profil gitrust (/settings/keys)
• O2. Cloner un dépôt gitrust en local via SSH (git clone git@…)
• O3. Pousser un commit vers gitrust et vérifier le résultat dans l’interface web

Pré-requis

• Technique : Git installé (git --version répond), un terminal, ton instance gitrust accessible
• Pédagogique : tutoriel 01 — Premiers pas complété (compte actif, 2FA configurée, un dépôt créé)
• Temps estimé : ~25 minutes

Vue d’ensemble

Avant de taper la première commande, voici ce que tu vas mettre en place et pourquoi.

SSH (Secure Shell) est le protocole que Git utilise pour envoyer et recevoir du code de manière sécurisée. La différence avec HTTPS : au lieu de saisir un mot de passe à chaque fois, tu déposes une clé publique sur le serveur gitrust, et ta machine prouve son identité grâce à la clé privée correspondante que tu gardes chez toi. C’est à la fois plus sûr et plus pratique.

Voici les trois acteurs de ce tutoriel :

sequenceDiagram
    participant M as Ta machine (terminal)
    participant A as Agent SSH (~/.ssh/)
    participant G as gitrust (:2222 SSH)
    participant W as gitrust (navigateur)

    M->>M: ssh-keygen → génère id_ed25519 + id_ed25519.pub
    M->>W: dépôt de id_ed25519.pub dans /settings/keys
    M->>A: ssh-add id_ed25519 (optionnel)
    M->>G: git clone git@gitrust.example.com:owner/repo.git
    G-->>M: copie locale du dépôt
    M->>M: édite un fichier, git add, git commit
    M->>G: git push origin main
    G-->>W: commit visible dans l'interface

Étape 1 : Génère une clé SSH ed25519

Note : si tu as déjà généré une clé ed25519 pendant le tutoriel 01, passe directement à l’étape 2.

Dans ton terminal, lance la commande suivante (remplace l’adresse e-mail par la tienne) :

ssh-keygen -t ed25519 -C "ton@email.com"

Sortie attendue :

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/toi/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/toi/.ssh/id_ed25519
Your public key has been saved in /home/toi/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx ton@email.com
The key's randomart image is:
+--[ED25519 256]--+
|        .o+      |
|        ...      |
+----[SHA256]-----+

Appuie sur Entrée pour accepter le chemin par défaut. Une passphrase est recommandée — elle chiffre la clé privée sur disque.

Affiche ta clé publique (le fichier .pub — celui-là est fait pour être partagé) :

cat ~/.ssh/id_ed25519.pub

Sortie attendue :

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ton@email.com

Copie cette ligne complète dans le presse-papier.

Checkpoint : la ligne commence obligatoirement par ssh-ed25519. Si elle commence par -----BEGIN tu affiches la clé privée par erreur — arrête-toi et relis la commande.

Étape 2 : Déclare la clé dans ton profil gitrust

Dans ton navigateur, va sur Paramètres → Clés SSH (/settings/keys).

Clique Ajouter une clé SSH. Remplis le formulaire :

• Titre : un nom qui identifie la machine (ex. laptop-maison-2026)
• Clé : colle la ligne ssh-ed25519 … copiée à l’étape 1

Clique Enregistrer.

Sortie attendue (bannière verte dans l’interface) :

Clé SSH ajoutée avec succès.

Vérifie la connexion depuis le terminal :

ssh -T git@gitrust.example.com -p 2222

Sortie attendue :

Bonjour tonpseudo ! Vous êtes authentifié, mais gitrust ne fournit pas d'accès shell.

Checkpoint : tu dois obtenir ce message de bienvenue. Si tu obtiens Permission denied (publickey), relis l’encart « Et si ça ne marche pas » en bas de ce tutoriel.

Étape 3 : Récupère l’URL SSH de ton dépôt

Dans ton navigateur, ouvre la page de ton dépôt (/<tonpseudo>/mon-premier-depot).

Sur la page d’accueil du dépôt, clique sur le bouton Cloner (ou Code). Sélectionne l’onglet SSH et copie l’URL affichée.

Elle a la forme :

git@gitrust.example.com:tonpseudo/mon-premier-depot.git

Checkpoint : l’URL SSH commence par git@ (pas par https://). Si tu ne vois pas d’onglet SSH, l’instance n’a pas de serveur SSH configuré — demande à ton administrateur.

Étape 4 : Clone le dépôt en local

Dans ton terminal, place-toi dans le dossier où tu veux stocker tes projets, puis clone :

cd ~/projets
git clone git@gitrust.example.com:tonpseudo/mon-premier-depot.git

Sortie attendue :

Cloning into 'mon-premier-depot'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
Receiving objects: 100% (3/3), done.

Entre dans le dossier cloné :

cd mon-premier-depot
ls

Sortie attendue :

README.md

Checkpoint : le fichier README.md est présent — ton dépôt est bien cloné. Si Git affiche fatal: repository not found, vérifie l’URL SSH copiée à l’étape précédente.

Étape 5 : Crée un fichier, commite et pousse

Crée un nouveau fichier dans le dépôt :

echo "# Notes de développement" > NOTES.md

Ajoute-le à l’index Git et crée un commit :

git add NOTES.md
git commit -m "ajoute NOTES.md"

Sortie attendue :

[main 3a8c21f] ajoute NOTES.md
 1 file changed, 1 insertion(+)
 create mode 100644 NOTES.md

Pousse vers gitrust :

git push origin main

Sortie attendue :

Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 298 bytes | 298.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To git@gitrust.example.com:tonpseudo/mon-premier-depot.git
   a1b2c3d..3a8c21f  main -> main

Checkpoint : la dernière ligne montre main -> main avec deux SHA différents, ce qui confirme que les objets ont bien été envoyés.

Étape 6 : Vérifie dans l’interface web

Retourne dans ton navigateur sur la page du dépôt (/<tonpseudo>/mon-premier-depot). Rafraîchis la page.

Tu dois voir :

• Le fichier NOTES.md apparaît dans la liste des fichiers
• La barre de commits affiche 2 commits (le README initial + ton nouveau commit)
• Le message de commit ajoute NOTES.md est visible à côté du fichier

Checkpoint : si le fichier NOTES.md n’est pas visible après rafraîchissement, assure-toi que le git push a bien terminé sans erreur (relis la sortie de l’étape 5).

Récapitulatif

• ✓ O1 accompli : tu as généré une clé SSH ed25519 et vérifié son empreinte SHA256 — elle est enregistrée dans /settings/keys
• ✓ O2 accompli : tu as cloné le dépôt en local avec git clone git@… et obtenu une copie fonctionnelle
• ✓ O3 accompli : tu as poussé un commit avec git push origin main et vérifié sa présence dans l’interface web

Et si ça ne marche pas

Prochaine étape

→ 03 — Collaborer : équipes, issues et pull requests : crée une équipe, invite un coéquipier, ouvre une issue et ta première pull request (~25 min)

Collaborer : équipes, issues et pull requests

Objectifs

À la fin de ce tutoriel, tu sauras :

• O1. Créer une équipe et y inviter un coéquipier depuis /teams/new
• O2. Ouvrir une issue pour décrire un problème ou une tâche à réaliser
• O3. Ouvrir une pull request depuis une branche et la fusionner après review

Pré-requis

• Technique : dépôt cloné en local (tutoriel 02 complété), accès à un second compte gitrust (ou un coéquipier disponible)
• Pédagogique : tutoriel 02 — Cloner et pousser complété
• Temps estimé : ~25 minutes

Vue d’ensemble

gitrust organise la collaboration autour de trois concepts qui s’enchaînent naturellement :

• Une équipe (team) regroupe des personnes et définit leur niveau d’accès à un ou plusieurs dépôts. C’est le point d’entrée pour inviter quelqu’un sur un projet.
• Une issue est une unité de travail : un bug à corriger, une feature à ajouter, une question à trancher. Elle porte un numéro (#N) qui sert de référence partout.
• Une pull request (PR) est une demande de fusion d’une branche vers une autre. Elle lie le code proposé à l’issue qu’il résout et déclenche la review de l’équipe.

flowchart LR
    T[Équipe créée<br/>/teams/new] --> R[Dépôt assigné<br/>à l'équipe]
    R --> I[Issue ouverte<br/>&#35;1]
    I --> B[Branche créée<br/>feat/fix-readme]
    B --> PR[Pull Request<br/>ouverte]
    PR --> Rev[Review approuvée]
    Rev --> M[Fusion dans main]
    M --> C[Issue fermée<br/>automatiquement]

Scaffolding niveau 2 : dans ce tutoriel, certaines commandes comportent un trou ___ à compléter. L’aide est donnée juste après le bloc de code — essaie d’abord sans regarder.

Étape 1 : Crée une équipe

Dans ton navigateur, navigue vers /teams/new.

Remplis le formulaire :

• Nom de l’équipe : equipe-alpha (lettres minuscules, chiffres, tirets)
• Description : Équipe de développement principale (optionnel)

Clique Créer l’équipe.

Sortie attendue : gitrust te redirige vers la page de l’équipe /teams/equipe-alpha. La page affiche l’équipe avec toi comme premier membre avec le rôle Owner.

Checkpoint : tu vois la page /teams/equipe-alpha avec ton pseudo listé en tant que membre. Si tu obtiens une erreur 422, le nom contient probablement des caractères interdits — utilise uniquement des minuscules et des tirets.

Étape 2 : Invite un coéquipier et assigne le dépôt

Sur la page de l’équipe, dans la section Membres, saisis le pseudo de ton coéquipier et clique Inviter.

Sortie attendue :

Membre ajouté à l'équipe.

Dans la section Dépôts, clique Ajouter un dépôt. Sélectionne mon-premier-depot dans la liste et choisis le niveau d’accès Developer. Clique Confirmer.

Sortie attendue :

Accès au dépôt accordé.

Checkpoint : ton coéquipier doit maintenant voir mon-premier-depot dans son tableau de bord. Demande-lui de vérifier. Le niveau Developer lui permet de cloner, pousser sur les branches non-protégées et ouvrir des PRs.

Étape 3 : Ouvre une issue

Dans ton navigateur, navigue vers /<tonpseudo>/mon-premier-depot/issues/new.

Remplis le formulaire :

• Titre : Améliorer le README avec une description du projet
• Description :

  Le fichier README.md est vide. Il faudrait ajouter :
  - Une description du projet
  - Les instructions d'installation
  

Clique Ouvrir l’issue.

Sortie attendue : gitrust crée l’issue et te redirige vers /<tonpseudo>/mon-premier-depot/issues/1. La page affiche l’issue avec le statut Ouverte et le numéro #1.

Checkpoint : l’URL dans ton navigateur doit se terminer par /issues/1. Note ce numéro — tu l’utiliseras dans le message de commit pour fermer l’issue automatiquement.

Étape 4 : Crée une branche pour travailler

Dans ton terminal, depuis le dossier mon-premier-depot, crée une nouvelle branche :

git checkout -b ___

Complète ___ avec le nom de branche feat/ameliorer-readme. La convention type/description-courte rend les branches lisibles dans la liste.

Réponse :

git checkout -b feat/ameliorer-readme

Sortie attendue :

Switched to a new branch 'feat/ameliorer-readme'

Modifie le fichier README.md :

cat > README.md << 'EOF'
# mon-premier-depot

Un dépôt de démonstration gitrust.

## Installation

Cloner le dépôt :

```bash
git clone git@gitrust.example.com:tonpseudo/mon-premier-depot.git

EOF

Commite et pousse la branche :

```bash
git add README.md
git commit -m "améliore le README - closes #1"
git push origin feat/ameliorer-readme

Sortie attendue :

[feat/ameliorer-readme 7c3d4e5] améliore le README - closes #1
 1 file changed, 10 insertions(+), 1 deletion(-)
...
To git@gitrust.example.com:tonpseudo/mon-premier-depot.git
 * [new branch]      feat/ameliorer-readme -> feat/ameliorer-readme

Checkpoint : la sortie de git push montre [new branch] feat/ameliorer-readme. Si elle montre rejected, exécute d’abord git pull origin main --rebase.

Étape 5 : Ouvre une pull request

Dans ton navigateur, navigue vers /<tonpseudo>/mon-premier-depot/pulls/new.

gitrust peut avoir détecté ta branche et proposer une bannière « Ouvrir une PR pour feat/ameliorer-readme » — clique dessus si elle apparaît.

Remplis le formulaire :

• Titre : Améliore le README avec description et installation
• Branche source : feat/ameliorer-readme
• Branche cible : main
• Description : Closes #1 (gitrust fermera l’issue automatiquement à la fusion)
• Reviewers : sélectionne ton coéquipier (s’il est disponible)

Clique Ouvrir la pull request.

Sortie attendue : gitrust crée la PR et te redirige vers /<tonpseudo>/mon-premier-depot/pulls/1.

Checkpoint : la PR est bien à l’état Ouverte et l’onglet Fichiers modifiés montre les changements dans README.md. Si la PR est vide (pas de diff), vérifie que tu as bien sélectionné feat/ameliorer-readme comme branche source.

Étape 6 : Fusionne la pull request

Si ton coéquipier peut review, demande-lui d’approuver la PR avant de fusionner. Dans ce tutoriel, tu peux fusionner directement si tu es seul.

Sur la page de la PR, fais défiler jusqu’à la section Fusion. Sélectionne la stratégie Merge commit (par défaut). Clique Fusionner la pull request.

Sortie attendue (message dans l’interface) :

Pull request fusionnée avec succès.

La PR passe au statut Fusionnée (violet). Navigue vers /<tonpseudo>/mon-premier-depot/issues/1 — l’issue doit être Fermée automatiquement grâce au closes #1 dans le message de commit.

Checkpoint : l’issue #1 est au statut Fermée. La page principale du dépôt affiche le nouveau contenu du README.md. Si l’issue est encore ouverte, vérifie que le message de commit contenait exactement closes #1 (respecter la casse n’est pas requis, mais le numéro doit être correct).

Récapitulatif

• ✓ O1 accompli : tu as créé l’équipe equipe-alpha via /teams/new, invité un membre et assigné le dépôt avec le niveau Developer
• ✓ O2 accompli : tu as ouvert l’issue #1 pour décrire la tâche, obtenant une unité de travail traçable et numérotée
• ✓ O3 accompli : tu as ouvert une PR depuis feat/ameliorer-readme, la fusionner a fermé l’issue automatiquement grâce à closes #1

Et si ça ne marche pas

Prochaine étape

→ 04 — Automatiser avec la CI : écris ton premier .gitrust-ci.yml, déclenche un pipeline et lis le résultat (~20 min)

Automatiser les tests avec la CI intégrée

Objectifs

À la fin de ce tutoriel, tu sauras :

• O1. Écrire un fichier .gitrust-ci.yml minimal en mode Easy pour un projet Rust ou Node
• O2. Déclencher un pipeline CI en poussant un commit
• O3. Lire le résultat d’un pipeline (statut, logs) sur la page /{owner}/{repo}/ci

Pré-requis

• Technique : dépôt cloné en local avec au moins un fichier source (tutoriel 02 complété), Git installé
• Pédagogique : tutoriel 03 — Collaborer complété
• Temps estimé : ~20 minutes

Vue d’ensemble

La CI (Continuous Integration, intégration continue) automatise l’exécution de tes tests à chaque push. Au lieu de vérifier manuellement que le code compile et que les tests passent, gitrust le fait pour toi — et signale immédiatement si quelque chose est cassé.

Le mode Easy de gitrust CI utilise un fichier .gitrust-ci.yml que tu places à la racine de ton dépôt. Ce fichier décrit en quelques lignes ce que gitrust doit exécuter : compiler, linter, tester. Le serveur de build reçoit le code, l’exécute dans un container Docker isolé, et renvoie les logs en temps réel.

flowchart LR
    subgraph "Ta machine"
        C[Commit +<br/>git push]
    end
    subgraph "gitrust (:4000)"
        W[CiWorker<br/>Tokio task]
        DB[(Pipeline<br/>en base)]
    end
    subgraph "Serveur de build"
        D[Docker<br/>+ Dagger]
        CI[ci-engine]
    end

    C -->|push SSH/HTTP| W
    W --> DB
    W -->|rsync + SSH| D
    D --> CI
    CI -->|logs ligne par ligne| W
    W --> DB
    DB -->|SSE stream| C

Scaffolding niveau 2 : la configuration CI comporte une section incomplète à compléter. Essaie d’abord sans regarder l’indice.

Étape 1 : Vérifie que la CI est activée sur le dépôt

Dans ton navigateur, ouvre ton dépôt et navigue vers Settings (/{owner}/{repo}/settings).

Fais défiler jusqu’à la section CI. Si tu ne vois pas cette section, l’administrateur de l’instance n’a pas encore activé le CI — contacte-le.

Coche CI activé et Déclencher sur push. Clique Enregistrer.

Checkpoint : la case CI activé est cochée et sauvegardée. Si la section CI n’apparaît pas dans les paramètres, la fonctionnalité n’est pas activée sur cette instance — consulte la section « Et si ça ne marche pas ».

Étape 2 : Crée le fichier .gitrust-ci.yml

Dans ton terminal, depuis la racine du dépôt cloné, crée le fichier de configuration CI.

Pour un projet Rust :

# .gitrust-ci.yml
language: rust

build:
  command: "cargo build"

checks:
  lint: "cargo clippy -- -D warnings"
  format: "cargo fmt -- --check"

tests:
  command: "___"

Complète ___ avec la commande de test Rust standard. Réponse : cargo test.

Pour un projet Node.js :

# .gitrust-ci.yml
language: node

build:
  command: "npm install"

checks:
  lint: "npm run lint"

tests:
  command: "npm test"

Pour ce tutoriel, utilise le fichier le plus adapté à ton projet, ou crée un exemple minimaliste avec Node si tu n’as pas de projet existant :

# Exemple minimal Node — crée les fichiers nécessaires
echo '{"name":"demo","scripts":{"test":"node -e \"console.log(42===42)\"","lint":"echo ok"}}' > package.json

Puis crée .gitrust-ci.yml avec le contenu Node ci-dessus.

Checkpoint : exécute ls -la dans le dépôt — tu dois voir .gitrust-ci.yml dans la liste. La taille du fichier doit être supérieure à 0 octet.

Étape 3 : Commite et pousse pour déclencher la CI

Ajoute le fichier et crée un commit :

git add .gitrust-ci.yml
git commit -m "ajoute configuration CI gitrust"
git push origin main

Sortie attendue :

[main a4f7b8c] ajoute configuration CI gitrust
 1 file changed, 10 insertions(+)
 create mode 100644 .gitrust-ci.yml
...
To git@gitrust.example.com:tonpseudo/mon-premier-depot.git
   3a8c21f..a4f7b8c  main -> main

Immédiatement après le push, dans ton navigateur, navigue vers /{owner}/{repo}/ci.

Sortie attendue : une entrée de pipeline apparaît avec le statut En attente ou En cours, associée au commit a4f7b8c et au message ajoute configuration CI gitrust.

Checkpoint : le pipeline apparaît dans la liste. S’il n’apparaît pas après 10 secondes, rafraîchis la page. S’il n’apparaît toujours pas, vérifie que la CI est bien activée (étape 1) et que le fichier .gitrust-ci.yml est bien à la racine du dépôt (pas dans un sous-dossier).

Étape 4 : Lis les logs du pipeline

Clique sur le pipeline dans la liste pour ouvrir la page de détail.

La page affiche :

• Le statut en cours (Pending → Running → Success ou Failure)
• Le commit et la branche associés
• Les logs en temps réel, mis à jour ligne par ligne

Attends la fin de l’exécution. Pour un projet minimal, cela prend 1 à 3 minutes selon la rapidité du serveur de build.

Sortie attendue pour un pipeline réussi (dernières lignes des logs) :

[build] cargo build: ok
[checks] cargo clippy: ok
[tests] cargo test: ok
Pipeline terminé avec succès.

Pour un pipeline en échec, les logs montrent la commande qui a échoué et le code de retour :

[tests] cargo test: FAILED (exit code 1)
error[E0277]: the trait bound `...` is not satisfied
Pipeline terminé en échec.

Checkpoint : le pipeline passe au statut Réussi (vert) ou Échoué (rouge). Dans les deux cas, tu as atteint l’objectif O3 — tu sais lire le résultat. Si le statut reste bloqué sur En cours plus de 10 minutes, consulte la section « Et si ça ne marche pas ».

Récapitulatif

• ✓ O1 accompli : tu as écrit un fichier .gitrust-ci.yml avec les sections language, build, checks et tests, adapté à ton langage
• ✓ O2 accompli : tu as déclenché le pipeline en poussant un commit — gitrust l’a automatiquement détecté et lancé l’exécution
• ✓ O3 accompli : tu as lu le statut et les logs sur /{owner}/{repo}/ci, identifiant si les étapes build/checks/tests ont réussi ou échoué

Et si ça ne marche pas

Prochaine étape

Tu as maintenant complété le parcours utilisateur de base : compte sécurisé → code versionné → collaboration en équipe → CI automatisée.

Pour aller plus loin :

• Comment gérer les clés SSH — plusieurs machines, rotation des clés
• Référence du schéma .gitrust-ci.yml — toutes les options disponibles
• Comprendre le cycle de vie d’une pull request — les états et transitions d’une PR

Guides pratiques — Recettes orientées tâche

Les guides pratiques (how-to guides) sont des recettes : ils répondent à la question « comment faire X ? » quand tu sais déjà ce que tu veux accomplir. Ils supposent que tu es déjà opérationnel — pas besoin d’explication du contexte ou de prise en main.

Mode Diátaxis : How-to. Si tu apprends gitrust pour la première fois, commence par les tutoriels. Si tu veux comprendre pourquoi gitrust fonctionne ainsi, consulte les explications. Pour les tableaux de référence exhaustifs, consulte la référence.

Les neuf guides pratiques

Sécurité et accès

Gérer ses clés SSH Générer une clé ed25519 ou RSA-4096, l’ajouter ou la supprimer via /settings/keys, vérifier l’empreinte SHA256, diagnostiquer ssh -T git@….

Configurer la double authentification (2FA) Activer le TOTP via /settings/security/2fa/setup, scanner le QR code, sauvegarder les codes de secours, désactiver ou régénérer.

Créer un Personal Access Token (PAT) Créer un token via /settings/tokens, choisir les scopes repo:read/repo:write, l’utiliser avec git clone https:// ou le header Authorization: Bearer, révoquer.

Collaboration et code review

Gérer les équipes et les permissions Créer une équipe, inviter des membres, attribuer des rôles (Owner/Maintainer/Member), assigner un dépôt avec un niveau d’accès (Reader/Developer/Maintainer/Owner).

Ouvrir une pull request Depuis une branche, ouvrir une PR, rédiger la description avec Closes #N, assigner des reviewers, suivre les statuts CI.

Choisir une stratégie de fusion Comparer fast-forward, squash et merge commit — quand utiliser chacune, permissions requises, équivalent API.

Utiliser les labels et les issues Labels à deux niveaux (classification + sujet), filtrer les issues, fermer automatiquement via closes #N dans un commit ou une PR.

Gestion des dépôts

Importer un dépôt externe Importer via l’UI /import, URL HTTPS publique, suivre la progression SSE, gérer les erreurs courantes (timeout, taille, auth).

Consulter le SBOM d’un dépôt Page Security d’un dépôt, vulnérabilités via Dependency-Track, télécharger le fichier CycloneDX.

Après les guides pratiques

Pour les tableaux de référence complets (permissions, schéma CI, API REST, notifications) : consulte la référence.

Comment gérer ses clés SSH

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Ajouter une clé SSH depuis une nouvelle machine
• Générer une clé plus sécurisée (ed25519 au lieu de RSA)
• Vérifier l’empreinte d’une clé avant de l’ajouter
• Supprimer une clé d’une machine perdue ou compromise
• Diagnostiquer une erreur Permission denied (publickey)

Pré-requis

• Un compte gitrust actif
• Un terminal avec ssh-keygen disponible (ssh-keygen --version doit répondre)

Étapes

1. Générer une clé ed25519 (recommandé)

ed25519 est l’algorithme recommandé : clés courtes, très rapides, résistantes aux attaques modernes.

ssh-keygen -t ed25519 -C "description-de-la-machine"

Exemple de description : laptop-maison-2026, serveur-ci, poste-bureau.

Sortie attendue :

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/toi/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Your identification has been saved in /home/toi/.ssh/id_ed25519
Your public key has been saved in /home/toi/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx description-de-la-machine

Une passphrase est fortement recommandée : elle chiffre la clé privée sur le disque. Si ta machine est volée, la clé reste inutilisable sans la passphrase.

2. Générer une clé RSA-4096 (alternative)

Si un outil ou un service impose RSA :

ssh-keygen -t rsa -b 4096 -C "description-de-la-machine"

La clé sera dans ~/.ssh/id_rsa et ~/.ssh/id_rsa.pub. RSA-4096 est sûr mais plus lent qu’ed25519.

3. Afficher la clé publique à copier

La clé publique (fichier .pub) est faite pour être partagée :

cat ~/.ssh/id_ed25519.pub

Sortie (une ligne) :

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx description-de-la-machine

Copie cette ligne entière.

4. Ajouter la clé dans gitrust (/settings/keys)

Dans ton navigateur, navigue vers Paramètres → Clés SSH (/settings/keys).

Clique Ajouter une clé SSH :

• Titre : le même que la description (ex. laptop-maison-2026)
• Clé : colle la ligne ssh-ed25519 … copiée

Clique Enregistrer.

5. Lister les clés enregistrées

La page /settings/keys affiche toutes tes clés avec :

• Leur titre
• Leur empreinte SHA256 (pour vérification)
• La date d’ajout
• Un bouton Supprimer

6. Vérifier l’empreinte SHA256 d’une clé locale

Pour confirmer qu’une clé locale correspond bien à une clé enregistrée dans gitrust :

ssh-keygen -lf ~/.ssh/id_ed25519.pub

Sortie :

256 SHA256:xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx description-de-la-machine (ED25519)

Compare ce SHA256 avec celui affiché dans /settings/keys. Ils doivent être identiques.

7. Tester la connexion SSH

ssh -T git@gitrust.example.com -p 2222

Sortie attendue :

Bonjour tonpseudo ! Vous êtes authentifié, mais gitrust ne fournit pas d'accès shell.

Si tu as plusieurs clés, spécifie laquelle utiliser :

ssh -T -i ~/.ssh/id_ed25519 git@gitrust.example.com -p 2222

8. Supprimer une clé

Dans /settings/keys, clique Supprimer à côté de la clé concernée. La suppression est immédiate — toute connexion utilisant cette clé sera refusée dès la prochaine tentative.

Variantes

Plusieurs machines, plusieurs clés

Tu peux enregistrer autant de clés que nécessaire dans gitrust. Chaque machine a sa propre paire de clés — tu ne copies jamais une clé privée d’une machine à l’autre.

Pour avoir plusieurs clés sur la même machine et choisir laquelle utiliser selon le serveur, crée un fichier ~/.ssh/config :

Host gitrust.example.com
    HostName gitrust.example.com
    User git
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_gitrust

Ensuite git clone git@gitrust.example.com:owner/repo.git utilisera automatiquement cette clé.

Ajouter la clé à l’agent SSH (évite de saisir la passphrase à chaque push)

ssh-add ~/.ssh/id_ed25519

Sur macOS, ajoute --apple-use-keychain pour que la passphrase soit mémorisée dans le trousseau système.

Dépannage ssh -T

Voir aussi

• Tutoriel 02 — Cloner et pousser : mise en place complète SSH + premier clone
• Comprendre la sécurité côté utilisateur : pourquoi les clés SSH sont plus sûres que les mots de passe
• Créer un Personal Access Token : alternative SSH pour les accès HTTPS et les scripts

Comment configurer la double authentification (2FA)

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Activer la 2FA TOTP sur ton compte gitrust
• Scanner le QR code avec une nouvelle application
• Sauvegarder tes codes de secours
• Désactiver la 2FA (par exemple pour changer d’application)
• Régénérer tes codes de secours après les avoir utilisés

Pré-requis

• Un compte gitrust actif
• Une application d’authentification TOTP installée sur ton téléphone : Google Authenticator, Authy, Bitwarden Authenticator, ou tout équivalent compatible RFC 6238

Étapes

1. Accéder à la page de sécurité

Dans ton navigateur, navigue vers Paramètres → Sécurité (/settings/security).

La section Authentification à deux facteurs affiche l’état actuel : « Désactivée » ou « Activée ».

2. Lancer la configuration TOTP

Clique Activer la 2FA. gitrust génère un secret TOTP et affiche un QR code.

3. Scanner le QR code

Dans ton application d’authentification :

1. Ouvre l’application
2. Ajoute un nouveau compte (icône + ou « Ajouter un compte »)
3. Choisis Scanner un QR code
4. Pointe l’appareil photo vers le QR code affiché dans gitrust

L’application ajoute un compte nommé gitrust (tonpseudo) et affiche un code à 6 chiffres qui se renouvelle toutes les 30 secondes.

Si tu ne peux pas scanner le QR code (appareil photo indisponible) : clique sur « Afficher la clé secrète ». Copie la chaîne de 32 caractères et saisis-la manuellement dans ton application (option « Saisir une clé »).

4. Vérifier le code et valider

Dans gitrust, saisis le code à 6 chiffres affiché par ton application dans le champ Code de vérification. Clique Confirmer.

Le code est valide pendant 30 secondes. Si l’horloge de ton téléphone n’est pas synchronisée, le code peut être rejeté — active la synchronisation automatique de l’heure dans les paramètres de ton téléphone.

Sortie attendue :

La 2FA a été activée avec succès.
Conservez vos codes de secours dans un endroit sûr.

5. Sauvegarder les codes de secours

gitrust affiche 10 codes de secours au format XXXX-XXXX. Ces codes permettent de te connecter si tu perds accès à ton application d’authentification.

Actions à effectuer immédiatement :

• Copie les 10 codes
• Stocke-les dans un gestionnaire de mots de passe (Bitwarden, KeePass…) ou sur papier dans un endroit sécurisé
• Ne les stocke pas dans le même appareil que ton application 2FA

Chaque code ne peut être utilisé qu’une seule fois.

Variantes

Désactiver la 2FA

Sur /settings/security, dans la section 2FA, clique Désactiver la 2FA. gitrust te demande de confirmer avec ton mot de passe.

Après désactivation, ton compte n’est protégé que par ton mot de passe. Si ton instance force la 2FA globalement (décision administrateur), tu ne pourras pas la désactiver.

Régénérer les codes de secours

Si tu as utilisé tous tes codes ou crains qu’ils soient compromis :

Sur /settings/security, clique Régénérer les codes de secours. Les anciens codes sont immédiatement invalidés. gitrust affiche 10 nouveaux codes — sauvegarde-les comme à l’étape 5.

Changer d’application d’authentification

1. Désactive la 2FA (voir ci-dessus)
2. Installe la nouvelle application
3. Réactive la 2FA depuis le début (étape 1)

Si tu as encore accès à l’ancienne application, tu peux aussi simplement ajouter le même compte dans la nouvelle application en rescannant le QR code pendant l’activation.

Voir aussi

• Tutoriel 01 — Premiers pas : activation de la 2FA dans le contexte du parcours complet
• Comprendre la sécurité côté utilisateur : pourquoi la 2FA protège même si ton mot de passe est volé
• Créer un Personal Access Token : accès API sans code 2FA interactif

Comment créer un Personal Access Token (PAT)

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Accéder à l’API gitrust depuis un script ou un outil CI sans exposer ton mot de passe
• Cloner un dépôt via HTTPS depuis un environnement où SSH n’est pas disponible
• Révoquer un accès accordé à un outil tiers sans changer ton mot de passe
• Comprendre quels scopes attribuer à un token selon l’usage

Pré-requis

• Un compte gitrust actif

Étapes

1. Accéder à la gestion des tokens

Dans ton navigateur, navigue vers Paramètres → Tokens d’accès (/settings/tokens).

La page liste tes tokens existants avec leur nom, leur date de création et leur date d’expiration.

2. Créer un nouveau token

Clique Créer un token. Remplis le formulaire :

• Nom : un nom descriptif qui rappelle l’usage (ex. script-backup-2026, ci-github-actions, cli-perso)
• Expiration : choisis une durée (30 jours, 90 jours, 1 an, ou sans expiration). Pour les scripts de CI, préfère une expiration explicite.
• Scopes : sélectionne uniquement les permissions nécessaires (principe du moindre privilège)

Clique Générer le token.

3. Copier le token immédiatement

gitrust affiche le token une seule fois :

gr_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copie-le immédiatement dans ton gestionnaire de mots de passe. Cette valeur ne sera plus jamais affichée — si tu la perds, tu devras révoquer le token et en créer un nouveau.

Utiliser le token

Avec git clone via HTTPS

git clone https://tonpseudo:gr_pat_xxxx@gitrust.example.com/owner/repo.git

Pour éviter que le token apparaisse dans l’historique du shell, stocke-le dans une variable d’environnement :

export GITRUST_TOKEN="gr_pat_xxxx"
git clone https://tonpseudo:${GITRUST_TOKEN}@gitrust.example.com/owner/repo.git

Avec l’API REST (header Authorization)

curl -H "Authorization: Bearer gr_pat_xxxx" \
     https://gitrust.example.com/api/v1/user

Réponse attendue :

{
  "id": 42,
  "username": "tonpseudo",
  "email": "ton@email.com"
}

Dans un script Python

import urllib.request
import json

token = "gr_pat_xxxx"
req = urllib.request.Request(
    "https://gitrust.example.com/api/v1/user",
    headers={"Authorization": f"Bearer {token}"}
)
with urllib.request.urlopen(req) as resp:
    user = json.load(resp)
    print(user["username"])

Révoquer un token

Dans /settings/tokens, clique Révoquer à côté du token concerné. La révocation est immédiate — toute requête utilisant ce token recevra une réponse 401 Unauthorized.

Cas où révoquer immédiatement :

• Token exposé accidentellement dans un dépôt public ou des logs
• Machine ou outil auquel le token était destiné est compromise
• Token inutilisé depuis longtemps

Variantes

Token sans expiration

Acceptable pour les outils personnels sur une machine de confiance. À déconseiller pour les environnements partagés (CI d’entreprise, scripts déployés sur un serveur). Préfère dans ces cas un token avec expiration de 90 jours renouvelé via un secret manager.

Plusieurs tokens pour un même outil

Crée un token par environnement (local, staging, prod) avec des scopes distincts. Ainsi, compromettre le token de staging n’expose pas la production.

Voir aussi

• Référence API REST v1 : liste des endpoints et authentification JWT vs PAT
• Comprendre la sécurité côté utilisateur : comment gitrust stocke les tokens (hash, jamais en clair)
• Gérer ses clés SSH : alternative SSH pour les opérations Git

Comment gérer les équipes et les permissions

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Créer une équipe et y regrouper des collaborateurs
• Inviter ou retirer un membre d’une équipe
• Assigner une équipe à un dépôt avec un niveau d’accès précis
• Choisir le bon rôle (Owner / Maintainer / Member) pour chaque membre
• Comprendre la différence entre les rôles d’équipe et les niveaux d’accès aux dépôts

Pré-requis

• Un compte gitrust actif
• Être propriétaire (Owner) de l’équipe ou de l’organisation pour gérer les membres et accès

Étapes

1. Créer une équipe

Navigue vers Équipes → Nouvelle équipe (/teams/new).

Remplis le formulaire :

• Nom : identifiant de l’équipe (lettres minuscules, chiffres, tirets — ex. backend-core, devops-ops)
• Description : optionnel, visible par les membres

Clique Créer l’équipe. gitrust te redirige vers /teams/{slug}.

2. Ajouter des membres

Sur la page de l’équipe (/teams/{slug}), dans la section Membres :

1. Saisis le pseudo du collaborateur dans le champ de recherche
2. Sélectionne son compte dans la liste déroulante
3. Choisis son rôle dans l’équipe (voir tableau ci-dessous)
4. Clique Inviter

Un seul Owner par équipe est requis. Désigne un Owner de secours pour éviter le blocage en cas d’absence.

3. Assigner un dépôt à l’équipe

Sur la page de l’équipe, dans la section Dépôts :

1. Clique Ajouter un dépôt
2. Sélectionne le dépôt dans la liste
3. Choisis le niveau d’accès au dépôt (voir tableau ci-dessous)
4. Clique Confirmer

Pour la référence complète des permissions par action, consulte le modèle de permissions.

4. Retirer un membre

Sur la page de l’équipe, dans la section Membres, clique Retirer à côté du membre concerné. Le retrait est immédiat — le membre perd l’accès aux dépôts de l’équipe.

5. Modifier le niveau d’accès d’un dépôt

Pour changer le niveau d’accès d’un dépôt déjà assigné à une équipe : retire le dépôt (bouton Retirer dans la section Dépôts), puis réassigne-le avec le nouveau niveau.

Variantes

Accès direct à un dépôt (sans équipe)

Il est possible d’ajouter un collaborateur directement sur un dépôt via /{owner}/{repo}/collaborators. Cette approche est adaptée aux cas ponctuels (ex. un prestataire externe sur un seul dépôt). Pour des équipes permanentes, l’approche par équipe est préférable : un seul point de gestion pour plusieurs dépôts.

Un utilisateur appartient à plusieurs équipes

Si un utilisateur appartient à plusieurs équipes qui ont des niveaux d’accès différents sur un même dépôt, c’est le niveau le plus élevé qui s’applique. Par exemple : Team A avec Reader + Team B avec Developer → l’utilisateur a Developer sur ce dépôt.

Voir aussi

• Tutoriel 03 — Collaborer : mise en pratique complète avec une équipe réelle
• Modèle de permissions (référence) : matrice complète des 4 rôles × actions
• Ouvrir une pull request : prérequis d’accès pour ouvrir et fusionner une PR

Comment ouvrir une pull request

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Proposer des modifications de code pour review avant fusion
• Lier une PR à une issue pour la fermer automatiquement à la fusion
• Assigner des reviewers à une PR
• Vérifier que la CI est verte avant de fusionner

Pré-requis

• Un dépôt avec au moins deux branches (ta branche de travail + main ou autre branche cible)
• Le niveau d’accès Developer minimum sur le dépôt

Étapes

1. Pousser ta branche de travail

Avant d’ouvrir une PR, ta branche doit être poussée sur gitrust :

git push origin ma-branche

Sortie attendue :

To git@gitrust.example.com:owner/repo.git
 * [new branch]      ma-branche -> ma-branche

2. Ouvrir le formulaire de nouvelle PR

Navigue vers /{owner}/{repo}/pulls/new.

gitrust peut aussi afficher une bannière de suggestion au sommet de la page du dépôt juste après un push récent : « Ouvrir une pull request pour ma-branche ». Clique dessus si elle apparaît.

3. Remplir le formulaire

Mot-clé Closes #N : si tu écris Closes #3 dans la description ou dans un message de commit sur cette branche, gitrust fermera automatiquement l’issue #3 lors de la fusion.

Clique Ouvrir la pull request.

4. Vérifier les onglets de la PR

Une fois créée, la PR s’affiche sur /{owner}/{repo}/pulls/{num} avec plusieurs onglets :

• Conversation : fil de discussion, commentaires généraux
• Commits : liste des commits inclus dans la PR
• Fichiers modifiés : diff complet, ligne par ligne — c’est ici que les reviewers commentent
• CI : statut du pipeline CI (si configuré)

5. Suivre le statut CI

Si le dépôt a une configuration CI (.gitrust-ci.yml), gitrust exécute automatiquement le pipeline sur la branche de la PR. Le statut apparaît en bas de la PR :

• En attente / En cours : le pipeline tourne
• Réussi (vert) : tous les checks passent
• Échoué (rouge) : au moins un check a échoué — clique sur « Voir les détails » pour lire les logs

6. Répondre à une review

Quand un reviewer laisse des commentaires :

1. Pousse de nouveaux commits sur la même branche pour adresser les remarques
2. Réponds aux commentaires dans l’interface pour indiquer ce qui a été fait
3. Le reviewer peut alors approuver la PR

Variantes

PR en mode brouillon

Si ton code n’est pas encore prêt pour review, ouvre la PR en cochant Brouillon lors de la création. Une PR en brouillon ne peut pas être fusionnée. Elle est visible par l’équipe pour discussion préalable. Passe-la en « Prête pour review » quand tu es prêt.

Mettre à jour la branche avant fusion

Si des commits ont été ajoutés sur main depuis que tu as créé ta branche, rebaser avant de fusionner :

git fetch origin
git rebase origin/main
git push origin ma-branche --force-with-lease

Voir aussi

• Tutoriel 03 — Collaborer : workflow complet issue → branche → PR → fusion
• Stratégies de fusion : choisir entre fast-forward, squash et merge commit
• Cycle de vie d’une pull request : comprendre les états et transitions

Comment choisir une stratégie de fusion

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Comprendre la différence entre fast-forward, squash et merge commit
• Choisir la stratégie adaptée à ton projet ou à ta PR
• Savoir quelles permissions sont requises pour chaque stratégie

Pré-requis

• Une pull request ouverte sur le dépôt
• Le niveau d’accès Developer minimum (pour fusionner une PR dont tu es l’auteur) ou Maintainer (pour fusionner les PRs des autres)

Les trois stratégies

Fast-forward (--ff-only)

Ce que ça fait : déplace simplement le pointeur de la branche cible vers le dernier commit de la branche source. Aucun commit de merge n’est créé. L’historique reste parfaitement linéaire.

Avant :   main: A → B
          feat:       B → C → D

Après :   main: A → B → C → D

Quand l’utiliser :

• Branches courtes avec peu de commits
• Tu veux un historique linéaire lisible avec git log
• La branche n’a pas divergé de main (pas de commits sur main pendant que tu travaillais)

Limitation : impossible si la branche cible a avancé depuis la création de la branche source — il faut d’abord rebaser.

Squash

Ce que ça fait : regroupe tous les commits de la branche en un seul commit sur la branche cible. L’historique de la branche est condensé.

Avant :   main: A → B
          feat:       B → C → D → E (3 commits)

Après :   main: A → B → F
          (F = C+D+E fusionnés en un seul commit)

Quand l’utiliser :

• Branche avec de nombreux micro-commits de type fix typo, wip, encore un fix
• Tu veux que main ne contienne que des commits propres et signifiants
• La PR correspond à une seule unité logique de travail

Limitation : les commits individuels sont perdus pour main — difficile de retrouver quel commit précis a introduit un changement avec git bisect.

Merge commit (--no-ff)

Ce que ça fait : crée un commit de merge explicite qui unit les deux branches. L’historique conserve la trace de la branche et de quand elle a été intégrée.

Avant :   main: A → B
          feat:       B → C → D

Après :   main: A → B → C → D → M
                          ↑___↑
                    (M = commit de merge)

Quand l’utiliser :

• Branches longues avec historique riche qu’on veut conserver
• Tu veux pouvoir git revert l’ensemble de la feature d’un seul coup (revert du commit M)
• Les conventions de l’équipe exigent un historique non-rebasé

Limitation : l’historique du projet devient un graphe orienté (DAG) moins lisible avec git log --oneline.

Tableau de comparaison

Étapes pour fusionner dans gitrust

Sur la page de la PR (/{owner}/{repo}/pulls/{num}), fais défiler jusqu’à la section Fusion :

1. Sélectionne la stratégie dans le menu déroulant (Merge commit, Squash, ou Fast-forward)
2. Si fast-forward est choisi mais impossible (branche divergente), gitrust indique l’erreur — rebaser d’abord
3. Clique Fusionner la pull request
4. Confirme si demandé

Sortie attendue :

Pull request fusionnée avec succès.

Variantes

Fusionner via l’API

curl -X POST \
  -H "Authorization: Bearer gr_pat_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"merge_method": "squash"}' \
  https://gitrust.example.com/api/v1/repos/owner/repo/pulls/1/merge

Valeurs valides pour merge_method : merge, squash, rebase (fast-forward).

Stratégie par défaut de l’équipe

Conventionner une stratégie par dépôt réduit les décisions ad hoc. Les équipes optant pour trunk-based development préfèrent le squash. Les équipes avec des branches longues (GitFlow) préfèrent le merge commit.

Voir aussi

• Ouvrir une pull request : créer la PR avant de la fusionner
• Cycle de vie d’une pull request : comprendre les transitions d’états
• Modèle de collaboration : philosophie gitrust sur les petites PRs

Comment utiliser les labels et les issues

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Créer et organiser des labels sur un dépôt
• Assigner des labels à une issue pour la catégoriser
• Filtrer les issues par label
• Fermer automatiquement une issue depuis un message de commit ou une PR
• Comprendre le système de labels à deux niveaux de gitrust

Pré-requis

• Un dépôt gitrust avec le niveau d’accès Developer minimum

Comprendre les labels à deux niveaux

gitrust organise les labels en deux niveaux : classification et sujet.

• Niveau 1 — Classification : la nature du ticket (bug, feature, docs, chore)
• Niveau 2 — Sujet : la zone fonctionnelle concernée (auth, ci, ui, api)

Combiner les deux niveaux donne une issue catégorisée précisément : une issue avec bug + auth est un bug dans le module d’authentification. Le filtrage par combinaison de labels permet de retrouver rapidement les issues pertinentes.

Étapes

1. Accéder à la gestion des labels

Navigue vers /{owner}/{repo}/labels.

La page liste les labels existants avec leur couleur et leur description.

2. Créer un label

Sur la page des labels, remplis le formulaire en haut :

• Nom : court, en minuscules, sans espaces (ex. bug, feature, auth, ci)
• Couleur : choisis une couleur hexadécimale ou utilise le sélecteur
• Description : optionnel — explique en une phrase quand appliquer ce label

Clique Créer le label.

Labels recommandés pour démarrer :

3. Assigner des labels à une issue

Sur la page d’une issue (/{owner}/{repo}/issues/{num}), dans la barre latérale droite, clique sur Labels.

Sélectionne un ou plusieurs labels dans la liste déroulante. La sélection est appliquée immédiatement.

Ou depuis l’API :

curl -X POST \
  -H "Authorization: Bearer gr_pat_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"label_ids": [1, 3]}' \
  https://gitrust.example.com/api/v1/repos/owner/repo/issues/5/labels

4. Filtrer les issues par label

Sur la page des issues (/{owner}/{repo}/issues), clique sur le menu Labels dans la barre de filtres. Sélectionne un ou plusieurs labels — seules les issues portant ces labels s’affichent.

Pour combiner des filtres (ex. toutes les issues bug dans la zone auth) : sélectionne les deux labels dans le même filtre.

5. Fermer une issue automatiquement

Pour fermer automatiquement une issue lors de la fusion d’une PR ou d’un push sur main, utilise un mot-clé de fermeture dans :

• Le message de commit (si poussé directement sur main)
• La description de la PR (fermeture effective à la fusion)
• Un commentaire de commit dans la branche

Mots-clés acceptés (insensibles à la casse) :

Exemple de message de commit :

git commit -m "corrige la validation email - fixes #5"

Après fusion de la PR contenant ce commit, l’issue #5 passe automatiquement au statut Fermée.

Variantes

Modifier ou supprimer un label

Sur /{owner}/{repo}/labels, chaque label a un bouton Modifier (pour changer le nom, la couleur ou la description) et un bouton Supprimer. La suppression retire le label de toutes les issues auxquelles il était assigné.

Labels suggérés automatiquement

gitrust peut suggérer des labels en fonction du contenu d’une issue. Cette suggestion s’affiche lors de la création d’une issue. Accepte ou ignore selon le contexte.

Voir aussi

• Ouvrir une pull request : utiliser closes #N dans la description de PR
• Tutoriel 03 — Collaborer : ouverture d’issue dans le contexte d’un workflow complet
• Syntaxe Markdown dans les issues : formatage des descriptions d’issues

Comment importer un dépôt externe

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Migrer un dépôt depuis GitHub, GitLab ou tout autre forge Git vers gitrust
• Copier un dépôt public accessible en HTTPS sans avoir à le cloner/pousser manuellement
• Suivre la progression d’un import en cours
• Diagnostiquer un import qui échoue (timeout, dépôt trop volumineux)

Pré-requis

• Un compte gitrust actif
• L’URL HTTPS publique du dépôt source (ex. https://github.com/owner/repo.git)
• Le dépôt source accessible sans authentification (ou les credentials si privé)

Étapes

1. Ouvrir le formulaire d’import

Navigue vers /import dans ton navigateur.

Le formulaire d’import apparaît.

2. Remplir le formulaire

• URL du dépôt source : l’URL HTTPS du dépôt à importer (ex. https://github.com/torvalds/linux.git)
• Nom du dépôt cible : le nom que le dépôt aura dans gitrust (rempli automatiquement depuis l’URL, modifiable)
• Visibilité : Public ou Privé
• Credentials (si dépôt privé) : nom d’utilisateur + mot de passe ou token du service source

Clique Lancer l’import.

3. Suivre la progression

gitrust crée un job d’import asynchrone et te redirige vers /imports/{id}.

La page affiche la progression en temps réel via SSE (Server-Sent Events) :

Connexion au dépôt source…
Récupération des objets : 100% (1234/1234)
Résolution des deltas : 100% (456/456)
Import terminé avec succès.

Les statuts possibles :

4. Accéder au dépôt importé

Une fois le statut Réussi, clique sur le lien vers le dépôt dans l’interface. Le dépôt est disponible à /{tonpseudo}/{nom-depot} avec tout l’historique Git préservé.

5. Annuler un import en cours

Si l’import prend trop longtemps ou a été lancé par erreur, clique Annuler sur la page /imports/{id}.

Variantes

Dépôt privé avec token

Pour importer un dépôt privé depuis GitHub, utilise un token GitHub dans le champ Credentials :

• Nom d’utilisateur : ton pseudo GitHub
• Mot de passe : ton Personal Access Token GitHub (pas ton mot de passe GitHub)

Le token n’est jamais stocké par gitrust après la fin de l’import.

Importer un dépôt volumineux

gitrust impose un timeout par défaut sur les imports. Pour les dépôts très volumineux (plusieurs Go), l’administrateur peut ajuster IMPORT_TIMEOUT dans la configuration de l’instance. Si l’import échoue systématiquement par timeout, cloner manuellement et pousser directement sur gitrust est une alternative :

git clone --mirror https://github.com/owner/repo.git repo.git
cd repo.git
git remote add gitrust git@gitrust.example.com:tonpseudo/repo.git
git push gitrust --mirror

Erreurs courantes

Voir aussi

• Tutoriel 02 — Cloner et pousser : pousser manuellement du code sur un dépôt gitrust
• Modèle de permissions : droits nécessaires pour créer un dépôt

Comment consulter le SBOM d’un dépôt

Quand utiliser ce guide

Utilise ce guide quand tu veux :

• Voir les composants logiciels détectés dans un dépôt (SBOM)
• Consulter les vulnérabilités identifiées par Dependency-Track
• Télécharger le fichier SBOM au format SPDX ou CycloneDX
• Comprendre ce qu’affiche l’onglet Security d’un dépôt

Pré-requis

• Un dépôt gitrust avec au moins un push récent
• La fonctionnalité SBOM activée par l’administrateur de l’instance (CI_SBOM_ENABLED=true)
• Le niveau d’accès Reader minimum sur le dépôt

Étapes

1. Accéder à l’onglet Security du dépôt

Navigue vers /{owner}/{repo}/security.

La page Security s’affiche avec l’encart SBOM.

2. Lire les informations du SBOM

L’encart SBOM affiche pour le dernier push analysé :

3. Consulter les vulnérabilités (si Dependency-Track est configuré)

Si l’administrateur a configuré Dependency-Track, l’encart affiche en plus les compteurs par sévérité :

Un lien Voir dans Dependency-Track permet d’accéder au détail de chaque vulnérabilité (CVE, description, composant affecté, version corrigée).

4. Télécharger le fichier SBOM

Si le SBOM a été généré avec succès, un bouton Télécharger le SBOM est disponible dans l’encart. Le fichier téléchargé est au format CycloneDX JSON — le format standard utilisé par gitrust pour générer et transmettre les SBOM.

Variantes

Statut processing qui ne se résout pas

Si le statut reste processing longtemps, cela signifie que Dependency-Track n’a pas terminé son analyse dans le délai imparti (30 secondes). L’analyse continue en arrière-plan sur Dependency-Track. Pour voir les résultats définitifs, consulte directement l’interface Dependency-Track en cliquant sur le lien de l’encart.

Pas de données SBOM sur un dépôt

Deux raisons possibles :

1. Aucun push depuis l’activation du SBOM : le scan ne se déclenche qu’à chaque push. Pousse un commit pour déclencher le premier scan.
2. Fonctionnalité non activée : l’administrateur n’a pas activé CI_SBOM_ENABLED. Contacte-le.

Voir aussi

• Tutoriel 04 — Automatiser avec la CI : la CI et le SBOM sont deux fonctionnalités distinctes déclenchées par le même push
• Comprendre la sécurité côté utilisateur : pourquoi surveiller les dépendances

Référence — Tableaux et spécifications

La section référence contient des informations factuelles précises destinées à la consultation. Elle ne t’apprend pas à faire quelque chose — pour ça, consulte les tutoriels ou les guides pratiques.

Mode Diátaxis : Reference. Ces pages sont conçues pour être parcourues rapidement, pas lues de bout en bout. Utilise la recherche ou les tableaux pour trouver ce que tu cherches.

Les cinq références

Modèle de permissions Matrice complète des 4 rôles dépôt (Reader / Developer / Maintainer / Owner) croisés avec toutes les actions possibles. Règles d’héritage utilisateur × équipe. À consulter quand tu ne sais pas si un rôle permet une action précise.

API REST v1 Tous les endpoints publics groupés par domaine (auth, user, repos, issues, pulls, CI). Authentification JWT vs PAT, pagination, codes d’erreur. Lien vers l’interface Swagger interactive /api/docs.

Schéma .gitrust-ci.yml Référence complète du fichier de configuration CI en mode Easy : champs language, build, checks, tests, deploy, artifacts, env. Profils disponibles (Rust, Node, Python, Go) avec exemples complets.

Markdown et syntaxe supportée Toute la syntaxe Markdown acceptée dans les issues, PRs et README : titres, code, tableaux, listes de tâches, mentions @, références #N, mots-clés de fermeture d’issue, emojis, Mermaid.

Notifications Matrice des événements (PR assignée, issue mentionnée, review demandée, CI échouée…) × canaux (SSE in-app, email) × préférences via /settings/notifications. Endpoint du stream SSE.

Modèle de permissions — 4 rôles par dépôt

Cette page est une référence factuelle. Pour comprendre comment assigner ces rôles, consulte Gérer les équipes et les permissions.

Les 4 rôles de dépôt

Matrice des actions × rôles

Héritage utilisateur × équipe

Un utilisateur peut avoir un accès à un dépôt par deux voies :

1. Accès direct : ajouté comme collaborateur sur /{owner}/{repo}/collaborators avec un niveau explicite
2. Via une équipe : membre d’une équipe à laquelle le dépôt a été assigné avec un niveau

Règle de résolution : le niveau d’accès effectif est le plus élevé parmi tous les accès (directs + équipes). Il n’y a pas de rôle négatif (interdit explicite) dans gitrust.

Exemple :

Rôles d’équipe vs niveaux d’accès dépôt

Ne pas confondre les deux systèmes :

Un membre avec le rôle Member dans une équipe peut avoir le niveau Owner sur un dépôt — ces deux dimensions sont indépendantes.

Voir aussi

• Gérer les équipes et les permissions : appliquer ces rôles dans l’interface
• Comprendre le modèle de collaboration : philosophie derrière les revues obligatoires

API REST v1

Référence des endpoints publics de l’API gitrust v1. Pour tester interactivement, accède à l’interface Swagger de ton instance sur /api/docs.

Authentification

L’API accepte deux méthodes d’authentification :

JWT Bearer (session web)

Obtenu via POST /api/v1/auth/login. Durée de vie courte, renouvelable via /api/v1/auth/refresh.

Authorization: Bearer <jwt_token>

Personal Access Token (PAT)

Créé dans /settings/tokens. Durée de vie configurable, révocable à tout moment.

Authorization: Bearer gr_pat_xxxx...

Les deux méthodes utilisent le même header Authorization: Bearer. gitrust détecte automatiquement le type par le préfixe du token.

Pagination

Tous les endpoints de liste supportent la pagination par curseur de page :

Exemple :

GET /api/v1/repos/owner/repo/issues?page=2&limit=50

Les réponses paginées incluent les headers :

X-Total-Count: 142
X-Page: 2
X-Per-Page: 50

Codes de réponse

Les erreurs retournent un corps JSON :

{
  "error": "repository not found",
  "code": "REPO_NOT_FOUND"
}

Endpoints — Authentification

Endpoints — Utilisateur

Exemple de réponse GET /api/v1/user :

{
  "id": 42,
  "username": "tonpseudo",
  "email": "ton@email.com",
  "avatar_url": "https://gitrust.example.com/avatars/42.png",
  "created_at": "2026-01-15T10:30:00Z"
}

Endpoints — Dépôts

Exemple de réponse GET /api/v1/repos/owner/repo :

{
  "id": 7,
  "owner": "owner",
  "name": "repo",
  "full_name": "owner/repo",
  "description": "Mon dépôt",
  "private": false,
  "default_branch": "main",
  "stars_count": 3,
  "forks_count": 0,
  "created_at": "2026-02-01T09:00:00Z",
  "updated_at": "2026-04-15T14:22:00Z"
}

Endpoints — Issues

Exemple POST /api/v1/repos/owner/repo/issues :

{
  "title": "Bug: validation email incorrecte",
  "body": "La validation rejette les adresses avec un + dans le local-part."
}

Endpoints — Pull Requests

Exemple POST /api/v1/repos/owner/repo/pulls/{num}/merge :

{
  "merge_method": "squash",
  "commit_title": "feat: améliore la validation email (#5)"
}

Valeurs merge_method : merge (merge commit), squash, rebase (fast-forward).

Endpoints — CI

Documentation interactive

L’interface Swagger complète est disponible sur ton instance à /api/docs. Elle permet de tester chaque endpoint directement depuis le navigateur avec ton token d’authentification.

La spécification OpenAPI brute (YAML) est disponible sur /api/docs/openapi.yaml.

Voir aussi

• Créer un Personal Access Token : obtenir les credentials pour l’API
• Référence des notifications : événements SSE disponibles

Schéma du fichier .gitrust-ci.yml (mode Easy)

Référence complète du fichier de configuration CI pour le mode Easy de gitrust. Ce fichier doit se trouver à la racine du dépôt.

Pour une introduction pratique, consulte le tutoriel 04 — Automatiser avec la CI.

Structure générale

language: <string>       # Profil de langage (requis)

build:
  command: <string>      # Commande de build

checks:
  <nom>: <string>        # Une ou plusieurs commandes de vérification
  <nom>: <string>

tests:
  command: <string>      # Commande de test principale

deploy:                  # Optionnel
  command: <string>
  only_on: <string>      # Branche déclenchant le déploiement (ex. "main")

artifacts:               # Optionnel
  paths:
    - <chemin>

env:                     # Variables d'environnement pour toutes les étapes
  <NOM>: <valeur>

Champ language

Type : string — Requis

Charge un profil préconfigué avec les outils et l’image Docker adaptés au langage.

Si ton langage n’est pas listé, utilise language: node ou language: python comme base générique et surcharge les commandes manuellement. Les profils sont définis sur le serveur de build dans deployment/ci-engine/profiles/.

Section build

Optionnel

Exécutée en premier. Arrête le pipeline en cas d’échec (code de sortie non nul).

build:
  command: "cargo build --release"

Section checks

Optionnel

Dictionnaire de vérifications statiques (lint, format, sécurité). Chaque clé est un nom arbitraire affiché dans les logs. Les checks sont exécutés en parallèle si le serveur de build le supporte.

checks:
  lint: "cargo clippy -- -D warnings"
  format: "cargo fmt -- --check"
  audit: "cargo audit"

Section tests

Optionnel

Commande de test principale. Exécutée après build et checks.

tests:
  command: "cargo test --release"

Section deploy

Optionnel

Déploiement conditionnel. Exécuté uniquement sur la branche spécifiée dans only_on.

deploy:
  command: "./scripts/deploy.sh production"
  only_on: "main"

Si only_on est omis, le déploiement s’exécute sur toutes les branches — généralement non souhaitable.

Section artifacts

Optionnel

Chemins des fichiers ou dossiers à conserver après le pipeline. Les artefacts sont accessibles depuis la page de détail du pipeline dans l’UI.

artifacts:
  paths:
    - target/release/mon-binaire
    - dist/
    - coverage/

Section env

Optionnel

Variables d’environnement disponibles dans toutes les commandes du pipeline. Ne jamais placer de secrets ici — utilise les variables CI chiffrées via l’UI (/{owner}/{repo}/ci/variables).

env:
  RUST_BACKTRACE: "1"
  NODE_ENV: "test"

Les variables définies dans l’UI ont priorité sur celles du fichier YAML en cas de conflit de nom.

Exemples complets par langage

Rust

language: rust

build:
  command: "cargo build --release"

checks:
  lint: "cargo clippy -- -D warnings"
  format: "cargo fmt -- --check"

tests:
  command: "cargo test --release"

artifacts:
  paths:
    - target/release/mon-binaire

Node.js

language: node

build:
  command: "npm ci"

checks:
  lint: "npm run lint"
  typecheck: "npm run typecheck"

tests:
  command: "npm test"

artifacts:
  paths:
    - dist/

Python

language: python

build:
  command: "pip install -r requirements.txt"

checks:
  lint: "flake8 src/"
  format: "black --check src/"

tests:
  command: "pytest --tb=short"

Go

language: go

build:
  command: "go build ./..."

checks:
  lint: "golangci-lint run ./..."
  vet: "go vet ./..."

tests:
  command: "go test ./..."

Détection automatique du mode

gitrust détecte le mode à exécuter lors d’un push selon la règle suivante :

Si les deux sont présents, le mode Power a la priorité.

Voir aussi

• Tutoriel 04 — Automatiser avec la CI : mise en pratique pas à pas
• Référence API REST — CI : déclencher et interroger les pipelines via l’API

Markdown et syntaxe supportée

Référence de la syntaxe Markdown acceptée dans les issues, les pull requests, les commentaires et les fichiers README des dépôts gitrust.

Titres

# Titre niveau 1
## Titre niveau 2
### Titre niveau 3
#### Titre niveau 4

Les titres génèrent des ancres de navigation (ex. #titre-niveau-2).

Mise en forme du texte

Blocs de code

Délimiter par trois backticks. Spécifier le langage pour la coloration syntaxique :

```rust
fn main() {
    println!("Hello, gitrust!");
}
```

Langages supportés pour la coloration : rust, go, python, javascript, typescript, json, yaml, toml, bash, sql, html, css, markdown, et la plupart des langages courants.

Listes

Liste non ordonnée

- Premier élément
- Deuxième élément
  - Élément imbriqué

Liste ordonnée

1. Première étape
2. Deuxième étape
3. Troisième étape

Liste de tâches (cases à cocher)

- [x] Tâche accomplie
- [ ] Tâche en attente
- [ ] Autre tâche

Rendu : cases cliquables dans les issues et les PRs. Cocher une case met à jour le texte en temps réel.

Tableaux

| Colonne A | Colonne B | Colonne C |
|-----------|-----------|-----------|
| Valeur 1  | Valeur 2  | Valeur 3  |
| Valeur 4  | Valeur 5  | Valeur 6  |

Alignement des colonnes :

| Gauche | Centre | Droite |
|:-------|:------:|-------:|
| texte  | texte  |  texte |

Liens et images

[Texte du lien](https://example.com)
[Lien relatif](../how-to/gerer-cles-ssh.md)
![Texte alternatif](https://example.com/image.png)

Citations

> Ceci est une citation.
> Elle peut s'étendre sur plusieurs lignes.

Ligne de séparation horizontale

---

Références aux issues et aux PRs

gitrust transforme automatiquement les références en liens cliquables :

Mentions d’utilisateurs

@tonpseudo

gitrust envoie une notification à l’utilisateur mentionné et crée un lien vers son profil.

Mots-clés de fermeture d’issue

Utilisés dans les messages de commit ou les descriptions de PR pour fermer automatiquement une issue lors de la fusion :

Closes #5
Fixes #12
Resolves #8

Insensibles à la casse. Plusieurs issues peuvent être référencées :

Closes #5, fixes #7

Emojis

La syntaxe :nom_emoji: est supportée :

Labels dans les descriptions

Les labels assignés à une issue sont affichés dans la barre latérale et non directement dans le corps Markdown. Pour référencer un label dans le texte, utilise son nom entre backticks : `bug`.

Diagrammes Mermaid

gitrust supporte les blocs Mermaid dans les README et les wikis (pas dans les commentaires d’issues) :

```mermaid
graph LR
    A[Début] --> B[Étape 1]
    B --> C[Fin]
```

Types supportés : graph, sequenceDiagram, flowchart, stateDiagram-v2, classDiagram, gantt, pie.

Voir aussi

• Utiliser les labels et les issues : appliquer les labels et références d’issues
• Ouvrir une pull request : rédiger une description de PR efficace

Notifications

Référence des événements déclenchant des notifications, des canaux disponibles et des préférences configurables via /settings/notifications.

Canaux de notification

gitrust envoie les notifications par deux canaux :

Matrice des événements × canaux

✓ = activé par défaut — — = non envoyé par défaut (peut être activé dans les préférences)

Configurer les préférences

Navigue vers Paramètres → Notifications (/settings/notifications).

La page affiche un tableau de cases à cocher pour chaque type d’événement × canal. Décoche les emails que tu ne veux pas recevoir et sauvegarde.

Stream SSE en temps réel

Les notifications SSE sont disponibles sur le endpoint :

GET /notifications/stream

Connexion en text/event-stream. Chaque notification est un événement JSON :

data: {"id": 42, "type": "pr_assigned", "repo": "owner/repo", "pr_num": 7, "created_at": "2026-04-17T10:15:00Z"}

Ce stream alimente l’icône cloche de l’interface. Il peut aussi être consommé par des outils externes (scripts, bots) via un PAT.

Marquer les notifications comme lues

• Une notification : POST /notifications/{id}/read
• Toutes les notifications : POST /notifications/read-all
• Via l’interface : clique sur une notification dans la liste /notifications, ou utilise le bouton Tout marquer comme lu

Voir aussi

• Créer un Personal Access Token : accéder au stream SSE par script
• API REST v1 : les endpoints de notifications ne sont pas listés dans l’API v1 publique — le stream SSE est le seul canal programmatique exposé

Explications — Comprendre gitrust en profondeur

Les explications sont des textes de compréhension : elles répondent à la question « pourquoi gitrust fonctionne-t-il ainsi ? » et construisent des modèles mentaux durables. Elles ne te font pas réaliser quelque chose — pour ça, consulte les tutoriels ou les guides pratiques.

Mode Diátaxis : Explanation. Les explications s’adressent à quelqu’un qui maîtrise déjà les opérations de base et veut comprendre les principes sous-jacents pour mieux décider, diagnostiquer et argumenter.

Les trois explications

Modèle de collaboration sur gitrust Philosophie des petites PRs, review obligatoire, auto-merge refusé. Analogie avec la relecture scientifique. Diagramme du cycle de travail. Comparaison avec les alternatives (trunk-based sans PR, GitFlow).

Bloom ciblé : expliquer la philosophie (2) · analyser les compromis PR courtes vs PR longues (4) · évaluer l’adéquation au contexte (5)

Sécurité côté utilisateur Pourquoi la 2FA protège même si le mot de passe est volé. Comment gitrust stocke les clés SSH (clé publique uniquement), les PAT (hash SHA-256) et les secrets TOTP. Analogie coffre-fort bancaire. Matrice vecteurs d’attaque × protections.

Bloom ciblé : expliquer le rôle de la 2FA (2) · analyser la surface d’attaque de chaque mécanisme (4) · évaluer la combinaison de protections adaptée (5)

Cycle de vie d’une pull request Diagramme Mermaid complet des états (Draft → Open → ReviewRequested → ChangesRequested → Approved → Merged / Closed) avec toutes les transitions manuelles et automatiques. Pourquoi une approbation est invalidée après un nouveau push. Comparaison review obligatoire vs optionnelle.

Bloom ciblé : identifier les états et transitions (2) · analyser les conditions de fusion (4) · évaluer les stratégies de review selon le contexte (5)

Comprendre le modèle de collaboration sur gitrust

Ce que tu vas comprendre

• Expliquer pourquoi gitrust impose une review avant toute fusion sur main (Bloom 2)
• Analyser les compromis entre petites PRs fréquentes et grosses PRs rares (Bloom 4)
• Évaluer si le modèle de review obligatoire convient à un contexte donné (Bloom 5)

Le problème concret

Tu travailles seul sur une feature pendant deux semaines. La branche diverge, s’accumule. Quand tu ouvres enfin une PR, elle contient 800 lignes de diff. Personne dans l’équipe ne veut (ni ne peut) la reviewer sérieusement — le review se réduit à « ça a l’air bien, LGTM ». Le code est fusionné avec des bugs qui auraient été détectés si quelqu’un avait lu attentivement 50 lignes.

gitrust est conçu pour rendre ce scénario difficile et le modèle opposé — petites PRs fréquentes, review courte et sincère — naturel et peu coûteux.

L’analogie

Imagine un journal scientifique avec comité de lecture. Chaque article soumis est lu par deux relecteurs indépendants avant publication. Les articles courts et bien ciblés obtiennent des retours rapides et précis. Les articles de 80 pages avec 200 références prennent six mois et reviennent avec des commentaires superficiels.

La code review dans gitrust fonctionne exactement comme le comité de lecture : plus le changement proposé est petit et focalisé, plus la review est rapide, sincère et utile. L’auto-merge (fusionner sa propre PR sans review externe) est interdit pour la même raison qu’un auteur ne peut pas valider lui-même son propre article : le biais de l’auteur rend les erreurs invisibles.

Le modèle

flowchart TD
    subgraph "Philosophie gitrust"
        A[Issue tracée<br/>avant tout travail]
        B[Branche courte<br/>1 issue = 1 branche]
        C[PR petite<br/>≤200 lignes idéalement]
        D[Review sincère<br/>par au moins 1 pair]
        E[CI verte<br/>avant fusion]
        F[Fusion dans main<br/>historique propre]
    end

    A --> B --> C --> D --> E --> F
    F -->|Nouvelle issue| A

Trois principes structurants :

1. Toute modification passe par une PR

gitrust n’interdit pas le push direct sur main au niveau du protocole Git, mais le modèle de collaboration encourage systématiquement la PR : c’est le seul endroit où la CI est déclenchée, où la review est documentée, où l’issue est liée et fermée automatiquement.

Les équipes qui veulent appliquer cela strictement protègent la branche main dans les paramètres du dépôt (niveau Maintainer requis pour le push direct).

2. L’auto-merge est refusé par convention

gitrust ne force pas techniquement la review externe — un Owner peut fusionner sa propre PR. Mais la convention du projet, renforcée par l’outillage (assignation de reviewers, statut « En attente de review »), crée une pression sociale pour attendre une approbation externe.

L’exception acceptable : un dépôt solo où l’on est seul contributeur. Dans ce cas, la CI joue le rôle du reviewer.

3. La taille d’une PR est un signal de qualité

Alternatives et compromis

Trunk-based development sans PR

Certaines équipes poussent directement sur main (trunk) avec feature flags pour isoler les fonctionnalités en développement. Plus rapide, moins de friction, mais nécessite une discipline de test très forte et une culture de confiance élevée. Adapté aux petites équipes seniors avec une couverture de tests élevée.

GitFlow avec longues branches de release

GitFlow maintient des branches develop, release/*, hotfix/* avec des cycles de merge longs. Adapté aux logiciels avec releases versionnées (ex. bibliothèques), inadapté aux services web déployés en continu.

Le choix de gitrust

gitrust adopte une variante de trunk-based development avec PR courtes : pas de develop séparée, pas de longues branches de feature, mais une PR obligatoire même pour les petits changements. C’est le compromis entre la vitesse du trunk-based et la traçabilité des PRs.

Vérifier ta compréhension

1. Un développeur propose une PR de 900 lignes modifiant le système d’authentification. Quelles questions lui poser pour l’aider à la découper ? (Bloom 2 — expliquer)

2. Ton équipe travaille sur un projet open-source avec des contributeurs externes que tu ne connais pas. Quels mécanismes de gitrust utiliserais-tu pour maintenir la qualité du code sans bloquer les contributions ? (Bloom 4 — analyser)

Pour aller plus loin

• Ouvrir une pull request : mettre en pratique ce modèle
• Stratégies de fusion : choisir la stratégie cohérente avec l’historique souhaité
• Cycle de vie d’une pull request : les états et transitions d’une PR de l’ouverture à la fusion

Comprendre la sécurité côté utilisateur

Ce que tu vas comprendre

• Expliquer pourquoi la 2FA protège même si ton mot de passe est volé (Bloom 2)
• Analyser les différences entre clé SSH, mot de passe et PAT en termes de surface d’attaque (Bloom 4)
• Évaluer quelle combinaison de protections adopter selon ton niveau d’exposition (Bloom 5)

Le problème concret

Ton mot de passe a été compromis. Peut-être lors d’une fuite de données d’un autre service où tu utilisais le même mot de passe. L’attaquant se connecte à ton compte gitrust, clone tous tes dépôts privés, y dépose un backdoor et efface l’historique. Tu ne t’en aperçois que trois jours plus tard.

gitrust fournit quatre mécanismes de protection indépendants pour rendre ce scénario soit impossible, soit détectable immédiatement. Ce document explique comment ils s’articulent.

L’analogie

Imagine un coffre-fort bancaire avec plusieurs couches de sécurité :

• La porte principale (mot de passe) : nécessaire mais insuffisante seule
• Le code secret temporaire (2FA TOTP) : change toutes les 30 secondes, connu uniquement de toi
• La clé physique nominative (clé SSH) : associée à une machine précise, inopérante sans la clé privée
• Le badge d’accès limité (PAT) : n’ouvre que certaines salles, révocable instantanément

Chaque couche est indépendante. Compromettre l’une n’ouvre pas les autres.

Le modèle

graph TD
    subgraph "Vecteurs d'attaque"
        V1[Mot de passe volé<br/>phishing / fuite DB]
        V2[Machine compromise<br/>malware / vol]
        V3[Token exposé<br/>commit accidentel / log]
    end

    subgraph "Protections gitrust"
        P1[2FA TOTP<br/>code valide 30s]
        P2[Clé SSH + passphrase<br/>liée à la machine]
        P3[PAT à durée limitée<br/>scope minimal]
        P4[Audit log<br/>connexions tracées]
    end

    V1 -->|bloqué par| P1
    V2 -->|atténué par| P2
    V3 -->|atténué par| P3
    V1 & V2 & V3 -->|détectable via| P4

2FA — pourquoi le mot de passe seul ne suffit plus

Le mot de passe est un secret statique : une fois volé, il est valable indéfiniment jusqu’à ce que tu le changes. Un code TOTP (Time-based One-Time Password) est un secret dynamique : il expire en 30 secondes et ne peut être utilisé qu’une seule fois. Même si un attaquant intercepte ton code TOTP, il est déjà expiré au moment où il essaie de l’utiliser.

gitrust stocke uniquement le secret TOTP (une chaîne de 32 caractères) qui permet de générer des codes — jamais les codes eux-mêmes. Ce secret est chiffré en base.

Clés SSH — une identité par machine

Une clé SSH ed25519 est une paire mathématique (clé privée + clé publique) liée à une machine. gitrust ne stocke que la clé publique — celle-ci ne permet pas de reconstruire la clé privée. Pour s’authentifier, ta machine doit prouver qu’elle possède la clé privée en signant un challenge.

Ce que gitrust stocke : clé publique + empreinte SHA256 (pour identification) + date d’ajout.

Ce que gitrust ne stocke jamais : la clé privée (elle ne quitte jamais ta machine).

Si ta machine est volée, supprimer la clé dans /settings/keys révoque immédiatement l’accès — même si le voleur a copié les fichiers ~/.ssh/.

PAT — accès minimal et révocable

Un Personal Access Token est haché (SHA-256) dès sa création. gitrust ne stocke que le hash — si un attaquant accède à la base de données, les tokens en clair ne sont pas exposés. La valeur réelle du token (gr_pat_xxxx) n’est affichée qu’une seule fois à la création.

Le scope minimal (repo:read uniquement pour un script de lecture) limite les dégâts si un token est exposé. La date d’expiration garantit qu’un token oublié dans un vieux script ne reste pas valide indéfiniment.

Audit log — tout est tracé

Gitrust enregistre les connexions réussies et les tentatives échouées dans un journal d’audit accessible via /settings/activity. Si tu constates des connexions depuis des IP inconnues ou à des heures inhabituelles, c’est le signal d’une compromission.

Alternatives et compromis

Mot de passe fort sans 2FA

Un mot de passe long et unique (généré par un gestionnaire de mots de passe) réduit considérablement le risque de compromission par brute-force ou réutilisation. Mais il ne protège pas contre le phishing (tu es trompé pour le saisir sur un faux site) ni contre les fuites de base de données. La 2FA couvre ces deux vecteurs.

Clé SSH sans passphrase

Plus pratique (pas de saisie à chaque push), mais si ta machine est volée ou compromise par un malware, la clé privée est directement utilisable. Une passphrase chiffre la clé sur le disque — seule une combinaison vol physique + connaissance de la passphrase permet l’accès.

PAT sans expiration

Acceptable pour les outils personnels sur une machine de confiance. Inacceptable pour un token partagé dans un environnement CI, un script de serveur, ou un dépôt accessible à plusieurs personnes.

Vérifier ta compréhension

1. Un collègue dit « je n’ai pas besoin de la 2FA, mon mot de passe fait 30 caractères aléatoires ». Quels scénarios d’attaque son mot de passe fort ne couvre-t-il pas ? (Bloom 2 — expliquer)

2. Tu découvres que ton token PAT a été accidentellement commité dans un dépôt public il y a 6 heures. Quelles actions effectues-tu dans quel ordre, et pourquoi ? (Bloom 4 — analyser)

Pour aller plus loin

• Configurer la double authentification (2FA) : activer le TOTP pas à pas
• Gérer ses clés SSH : générer, déclarer et révoquer des clés
• Créer un Personal Access Token : scopes, expiration, révocation

Comprendre le cycle de vie d’une pull request

Ce que tu vas comprendre

• Identifier les états possibles d’une PR et les transitions entre eux (Bloom 2)
• Analyser pourquoi certaines transitions sont automatiques et d’autres manuelles (Bloom 4)
• Évaluer à quel moment une PR est prête à être fusionnée (Bloom 5)

Le problème concret

Tu as ouvert une PR il y a trois jours. Un reviewer a laissé des commentaires. Tu as poussé des corrections. La CI a repassé au vert. Mais tu ne sais pas si tu dois re-demander une review, si tu peux fusionner maintenant, ou si quelque chose bloque encore. L’état de la PR n’est pas clair.

Comprendre le cycle de vie d’une PR te permet de lire son état actuel d’un coup d’œil et de savoir exactement quelle action effectuer ensuite.

L’analogie

Une pull request ressemble à un dossier de demande de permis de construire :

• Ouvert : le dossier est déposé, les voisins (reviewers) peuvent faire des remarques
• En cours de review : l’architecte (reviewer) examine les plans et demande des modifications
• Approuvé : l’architecte signe les plans modifiés
• CI verte : les normes techniques sont vérifiées automatiquement (sécurité incendie, etc.)
• Fusionné : le permis est accordé, les travaux peuvent commencer sur main
• Refusé / fermé : le dossier est archivé sans suite

Comme pour un permis, une PR peut être rouverte si elle a été fermée par erreur ou prématurément.

Le modèle — diagramme de séquence complet

stateDiagram-v2
    [*] --> Draft : créer en brouillon
    [*] --> Open : créer directement

    Draft --> Open : marquer "Prête pour review"
    Open --> Draft : repasser en brouillon

    Open --> ReviewRequested : assigner un reviewer
    ReviewRequested --> ChangesRequested : reviewer demande modifications
    ReviewRequested --> Approved : reviewer approuve

    ChangesRequested --> ReviewRequested : auteur pousse corrections<br/>+ re-demande review
    Approved --> Open : nouveau push (invalidation auto)

    Open --> Closed : fermer sans fusionner
    Closed --> Open : rouvrir

    Approved --> Merged : fusionner (CI verte requise si configurée)
    Open --> Merged : fusionner (si permissions suffisantes)

    Merged --> [*]
    Closed --> [*]

Les états en détail

Draft (Brouillon)

La PR est visible par l’équipe mais ne peut pas être fusionnée. Utilise cet état pour :

• Partager du code en cours de travail pour des commentaires précoces
• Réserver un numéro de PR pour une issue
• Travailler en collaboration sur la même branche

Transition manuelle : l’auteur clique Marquer comme prête pour review.

Open (Ouverte)

État par défaut à la création. La PR peut être commentée, reviewée et fusionnée (selon les permissions). C’est l’état de travail normal.

ReviewRequested (Review demandée)

Un reviewer a été assigné. gitrust lui envoie une notification. La PR attend son verdict. L’auteur peut continuer à pousser des commits pendant ce temps.

ChangesRequested (Modifications demandées)

Le reviewer a explicitement demandé des changements. La PR est bloquée — elle ne peut pas être fusionnée tant que le reviewer n’a pas approuvé ou n’a pas retiré son refus.

Transition de sortie : l’auteur pousse les corrections et re-demande une review (bouton Re-request review).

Approved (Approuvée)

Au moins un reviewer a approuvé. La PR peut être fusionnée si la CI est verte.

Invalidation automatique : si l’auteur pousse un nouveau commit après l’approbation, le statut repasse à Open — le reviewer doit approuver à nouveau. Ce comportement garantit que ce qui est fusionné correspond exactement à ce qui a été approuvé.

Merged (Fusionnée)

État terminal. Le code est dans la branche cible. La PR est archivée en lecture seule. Si la description contenait closes #N, l’issue N est fermée automatiquement à ce moment.

Closed (Fermée)

Fermée sans fusion — le travail a été abandonné ou la PR était incorrecte. Peut être rouverte si nécessaire. Les commits de la branche ne sont pas supprimés.

Transitions automatiques

Alternatives et compromis

Review obligatoire vs optionnelle

gitrust permet de fusionner une PR sans review externe si l’on a les permissions Owner ou Maintainer. Certaines équipes configurent une branche protégée exigeant au moins une approbation — ce qui rend la review techniquement obligatoire. D’autres s’appuient sur la convention sans protection forcée. La protection forcée convient aux projets critiques ou réglementés ; la convention suffit pour les petites équipes de confiance.

Invalidation automatique après push

Certaines forges (GitHub) ont rendu ce comportement optionnel. gitrust invalide systématiquement l’approbation après un nouveau push — c’est plus strict mais garantit que le reviewer a vu exactement le code fusionné. Inconvénient : un correctif de typo force une re-review complète.

Vérifier ta compréhension

1. Une PR est à l’état ChangesRequested. L’auteur pousse ses corrections mais ne re-demande pas de review. Que se passe-t-il ? Peut-on fusionner ? (Bloom 2 — identifier l’état)

2. Tu es Maintainer d’un dépôt. Une PR approuvée contient un conflit de merge introduit par un commit récent sur main. Quelles options as-tu, et quels sont les avantages et inconvénients de chacune ? (Bloom 4 — analyser les compromis)

Pour aller plus loin

• Ouvrir une pull request : créer et suivre une PR
• Stratégies de fusion : choisir entre fast-forward, squash et merge commit
• Modèle de collaboration : pourquoi la review est centrale dans gitrust

Manuel d’administration

Ce manuel s’adresse aux opérateurs et self-hosters qui déploient, configurent et maintiennent une instance gitrust en production. Il couvre l’intégralité du cycle de vie d’une instance : premier démarrage, mise en production, sauvegarde, mise à jour et dépannage. Il suppose des connaissances en administration Linux, en réseau et en TLS — il n’explique pas ces prérequis.

Parcours d’apprentissage

Le parcours administrateur est structuré en 4 tutoriels qui représentent environ 3 heures au total. L’étayage est dégressif : le premier tutoriel fournit tout clé en main, le dernier demande de composer soi-même à partir des recettes disponibles.

graph LR
    A[VM prête<br/>Docker installé] --> B[01-installation-docker<br/>30 min]
    B --> C[02-installation-systemd<br/>45 min]
    C --> D[03-premier-demarrage<br/>20 min]
    D --> E[04-mise-en-production<br/>90 min]
    E --> F[Admin opérationnel]

Checkpoint de parcours : avant de passer au tutoriel 02, vous devez avoir une instance gitrust accessible sur http://localhost:4000 avec un compte administrateur fonctionnel. Si ce n’est pas le cas, relisez le tutoriel 01.

Checkpoint de parcours : avant le tutoriel 04, vous devez avoir une instance démarrée avec une configuration SMTP et un reverse-proxy TLS opérationnel. Si ce n’est pas le cas, relisez le tutoriel 03.

Tutoriels — apprendre en faisant

Les tutoriels sont guidés pas-à-pas avec des sorties verbatim attendues. Suivez-les dans l’ordre — chacun suppose le précédent complété.

• 01 — Installation Docker : stack docker-compose complète — ~30 min
• 02 — Installation systemd : binaire natif + service — ~45 min
• 03 — Premier démarrage : admin bootstrap, migrations — ~20 min
• 04 — Mise en production — ~90 min

How-to — recettes pour les tâches courantes

Les how-to répondent à « comment faire X » sans explication de fond. Consultez-les dans n’importe quel ordre selon votre besoin.

• Sauvegarder et restaurer
• Mettre à jour l’instance
• Configurer SMTP
• Configurer OAuth (Google, GitHub)
• Configurer un CI runner distant
• Intégrer Dependency-Track (SBOM)
• Durcir avec Fail2ban
• Tuner le rate limiting
• Forcer la 2FA globalement
• Dépanner SSH
• Dépanner la CI
• Gérer les utilisateurs depuis /admin
• Auditer l’instance

Référence — informations techniques exactes

La référence documente de façon exhaustive les paramètres, schémas et comportements. Elle est destinée à la consultation ponctuelle.

• Variables d’environnement (.env)
• Paramètres dynamiques (app_settings)
• Schéma de base de données
• Ports et services (4000 HTTP, 2222 SSH, 5432 PG)
• Conformité ANSSI PA-074

Explication — comprendre le pourquoi

Les explanations construisent les modèles mentaux nécessaires pour prendre de bonnes décisions d’exploitation. Lisez-les quand vous voulez comprendre les choix d’architecture, pas seulement les appliquer.

• Architecture globale de gitrust
• Modèle de déploiement : mono-machine vs HA
• CI Dagger : pourquoi et comment
• Stratégie de sauvegarde 3-2-1 adaptée gitrust

Tutoriels — Manuel d’administration

Les tutoriels vous guident pas à pas, du premier démarrage jusqu’à une instance gitrust en production. Chaque tutoriel part d’un état précis et vous mène à un résultat observable et vérifiable.

Avant de commencer : lisez l’encart de pré-requis en tête de chaque tutoriel. Le parcours est conçu pour être suivi dans l’ordre — chaque étape suppose la précédente réalisée.

Parcours d’apprentissage

graph LR
    A[VM prête<br/>Linux + Docker<br/>ou Rust toolchain] --> B[01-installation-docker<br/>~30 min]
    B --> C[02-installation-systemd<br/>~45 min]
    C --> D[03-premier-demarrage<br/>~20 min]
    D --> E[04-mise-en-production<br/>~90 min]
    E --> F[Admin opérationnel<br/>Instance sécurisée]

    style A fill:#f5f5f5
    style F fill:#d4edda

Scaffolding dégressif — le niveau d’aide recule d’un cran à chaque tutoriel :

Checkpoint de parcours : avant de passer au tutoriel suivant, vous devez savoir faire :

• Après 01 ou 02 : curl http://localhost:4000/ retourne un code HTTP ; ssh-keyscan -p 2222 localhost retourne un fingerprint
• Après 03 : connexion réussie à /admin avec le compte bootstrap
• Après 04 : accès HTTPS depuis l’extérieur, SMTP configuré, première sauvegarde réalisée

Liste des tutoriels

01 — Installation avec Docker Compose

Déployer gitrust + PostgreSQL en quelques minutes avec Docker Compose. Point d’entrée recommandé pour découvrir la plateforme.

État initial : VM Linux avec Docker installé
État final : gitrust accessible sur http://localhost:4000, SSH sur :2222

02 — Installation avec systemd (binaire natif)

Installer gitrust comme un binaire natif sur Debian/Ubuntu, créer l’utilisateur système gitrust, configurer PostgreSQL, écrire le fichier gitrust.service avec durcissement systemd.

État initial : VM Debian 12 / Ubuntu 22.04 LTS
État final : systemctl status gitrust affiche active (running), ports 4000 et 2222 répondent

03 — Premier démarrage

Bootstrap du compte administrateur, vérification de la clé SSH hôte générée automatiquement, confirmation que les trois services (HTTP, SSH, PostgreSQL) sont sains, premier accès à /admin.

État initial : tutoriel 01 ou 02 complété
État final : connecté à /admin, fingerprint SSH noté, migrations confirmées dans les logs

04 — Mise en production

Reverse-proxy Nginx avec TLS, configuration SMTP, première sauvegarde, monitoring de base. Généralisation à partir d’un exemple de déploiement réseau local.

État initial : tutoriel 03 complété, domaine/DNS prêt
État final : accès HTTPS depuis l’extérieur, e-mails fonctionnels, sauvegarde planifiée

Après les tutoriels

Une fois le parcours complété, vous pouvez utiliser les guides pratiques (how-to) de manière autonome pour des tâches spécifiques : configurer OAuth, régler le rate limiting, dépanner SSH, etc.

→ Guides pratiques (how-to)

Installation Docker : démarrez gitrust en 30 minutes avec docker-compose

Objectifs

À la fin de ce tutoriel, vous saurez :

• O1. Déployer la stack gitrust minimale (application + PostgreSQL) avec docker-compose
• O2. Vérifier que les trois services démarrent correctement et sont en bonne santé
• O3. Créer le premier compte administrateur et accéder à l’interface web

Pré-requis

• Technique : une VM ou machine Linux (Debian 12 / Ubuntu 22.04 ou supérieur), Docker Engine ≥ 24 installé (docker --version répond), Docker Compose plugin installé (docker compose version répond), ports 4000 et 2222 libres sur la machine
• Pédagogique : aucun tutoriel gitrust préalable requis — c’est le point de départ du parcours administrateur
• Temps estimé : ~30 minutes

Vue d’ensemble

Avant de lancer la moindre commande, comprenons ce que docker-compose va orchestrer et pourquoi.

gitrust est composé de trois services principaux dans sa configuration minimale. Pensez-y comme trois pièces d’un appartement qui s’appellent entre elles via un réseau interne :

graph TB
    subgraph internet ["Internet / votre navigateur"]
        B[Navigateur :4000]
        S[Client git/SSH :2222]
    end

    subgraph docker ["Réseau Docker gitrust_net"]
        A["gitrust-app<br/>(Rust, port 4000 + 2222)<br/>Lit la config depuis .env"]
        P["postgres<br/>(PostgreSQL 16, port 5432)<br/>Stocke comptes, dépôts, issues"]
        R["redis (optionnel)<br/>(Redis 7, port 6379)<br/>Sessions web + cache"]
    end

    B -->|HTTP| A
    S -->|SSH| A
    A -->|SQL| P
    A -.->|sessions| R

gitrust-app est le cœur : serveur HTTP (:4000) + serveur SSH (:2222) compilé en Rust. Il lit sa configuration depuis un fichier .env et écrit les dépôts Git bare sur un volume Docker. PostgreSQL stocke toutes les données relationnelles (comptes, organisations, dépôts, issues, PRs). Redis est optionnel dans la configuration minimale — il gère les sessions web et le cache quand il est présent.

Dans ce tutoriel, nous utilisons la stack minimale (app + PostgreSQL) suffisante pour évaluer gitrust et démarrer une petite instance. La stack production avec Redis et SMTP se trouve dans template/docker/docker-compose.production.yml.

Étape 1 : Créez le répertoire de travail et le fichier de configuration

Créez un répertoire dédié à votre instance gitrust et positionnez-vous dedans :

mkdir -p /opt/gitrust && cd /opt/gitrust

Créez le fichier de configuration .env avec les valeurs minimales. Changez impérativement les valeurs marquées CHANGE_ME :

cat > .env << 'EOF'
# === gitrust — configuration minimale ===
# Changez toutes les valeurs CHANGE_ME avant de démarrer

# Clé secrète de l'application (générez avec : openssl rand -hex 32)
SECRET_KEY=CHANGE_ME_openssl_rand_hex_32

# URL publique de l'instance (sans slash final)
APP_URL=http://localhost:4000

# Base de données PostgreSQL
DATABASE_URL=postgres://gitrust:CHANGE_ME_db_password@postgres:5432/gitrust
POSTGRES_USER=gitrust
POSTGRES_PASSWORD=CHANGE_ME_db_password
POSTGRES_DB=gitrust

# Serveur SSH (port exposé à l'extérieur)
SSH_PORT=2222

# Mode de l'application
RUST_LOG=info
APP_ENV=production
EOF

Générez maintenant une clé secrète robuste et remplacez la valeur dans .env :

SECRET=$(openssl rand -hex 32)
sed -i "s/CHANGE_ME_openssl_rand_hex_32/$SECRET/" .env

Choisissez également un mot de passe pour PostgreSQL et remplacez les deux occurrences :

DB_PASS=$(openssl rand -hex 16)
sed -i "s/CHANGE_ME_db_password/$DB_PASS/g" .env

Sortie attendue (vérification) :

grep SECRET_KEY .env
# → SECRET_KEY=4a7f2c9e1b8d3f6a0e5c2b9d7f4a1e8c3b6d9f2a5e8c1b4d7f0a3e6c9b2d5f8a

Checkpoint : exécutez grep CHANGE_ME .env — la commande doit ne rien retourner. Si elle retourne des lignes, ces valeurs n’ont pas été remplacées et le démarrage échouera.

Étape 2 : Créez le fichier docker-compose.yml

Créez le fichier docker-compose.yml suivant dans /opt/gitrust/. Ce contenu correspond à la stack minimale gitrust — il est reproduit ici intégralement pour que vous puissiez démarrer sans dépendance externe :

cat > docker-compose.yml << 'EOF'
# docker-compose.minimal.yml — Stack gitrust minimale (app + PostgreSQL)
# Cas d'usage : évaluation, développement, petite instance (<10 utilisateurs)
# Pour la production : utilisez docker-compose.production.yml (+ Redis + SMTP)
#
# Usage :
#   docker compose up -d
#   docker compose logs -f gitrust
#   docker compose down

version: "3.9"

services:
  # ── Base de données ───────────────────────────────────────────────────────
  postgres:
    image: postgres:16-alpine
    container_name: gitrust_postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      # Données persistantes — ne supprimez pas ce volume sans sauvegarde
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - gitrust_net

  # ── Application gitrust ───────────────────────────────────────────────────
  gitrust:
    image: ghcr.io/gitrust/gitrust:latest
    container_name: gitrust_app
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    env_file:
      # Lit toutes les variables depuis .env — ne commitez jamais ce fichier
      - .env
    ports:
      # Interface web — exposée sur toutes les interfaces de la machine hôte
      - "4000:4000"
      # Serveur SSH Git — exposé sur le port configuré dans .env
      - "${SSH_PORT:-2222}:2222"
    volumes:
      # Dépôts Git bare — données critiques, sauvegardez ce volume
      - git_repos:/var/lib/gitrust/repositories
      # Clés SSH du serveur — générées au premier démarrage, persistez-les
      - ssh_host_keys:/etc/gitrust/ssh
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    networks:
      - gitrust_net

volumes:
  # postgres_data : données relationnelles (comptes, dépôts, issues, PRs)
  postgres_data:
  # git_repos : dépôts Git bare (le contenu réel des commits)
  git_repos:
  # ssh_host_keys : clés SSH hôte (fingerprint de votre serveur)
  ssh_host_keys:

networks:
  gitrust_net:
    driver: bridge
EOF

Checkpoint : vérifiez que les deux fichiers sont présents dans /opt/gitrust/ :

ls -la /opt/gitrust/

Sortie attendue :

total 16
drwxr-xr-x 2 root root 4096 avr 17 10:00 .
drwxr-xr-x 8 root root 4096 avr 17 09:55 ..
-rw------- 1 root root  612 avr 17 10:00 .env
-rw-r--r-- 1 root root 2048 avr 17 10:00 docker-compose.yml

Étape 3 : Démarrez la stack et suivez les logs

Démarrez tous les services en arrière-plan :

docker compose up -d

Sortie attendue :

[+] Running 4/4
 ✔ Network gitrust_gitrust_net    Created                          0.1s
 ✔ Volume "gitrust_postgres_data" Created                          0.0s
 ✔ Container gitrust_postgres     Started                          0.8s
 ✔ Container gitrust_app          Started                          1.2s

Suivez les logs de l’application pour observer le démarrage (les migrations s’exécutent automatiquement) :

docker compose logs -f gitrust

Sortie attendue (les 15-20 premières secondes) :

gitrust_app  | 2026-04-17T10:00:15Z INFO  gitrust > Starting gitrust v0.9.0
gitrust_app  | 2026-04-17T10:00:15Z INFO  gitrust > Connecting to database...
gitrust_app  | 2026-04-17T10:00:16Z INFO  gitrust > Running database migrations...
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > Applied 42 migrations successfully
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > Generating SSH host keys...
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > SSH host key fingerprint: SHA256:xxxxxxxxxxxxxxxxxxxx
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > HTTP server listening on 0.0.0.0:4000
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > SSH server listening on 0.0.0.0:2222
gitrust_app  | 2026-04-17T10:00:17Z INFO  gitrust > gitrust is ready

Appuyez sur Ctrl+C pour quitter le suivi des logs (les containers continuent de tourner).

Checkpoint : vérifiez l’état de santé des services :

docker compose ps

Sortie attendue :

NAME              IMAGE                          COMMAND                  SERVICE    CREATED         STATUS                   PORTS
gitrust_app       ghcr.io/gitrust/gitrust:latest "/usr/local/bin/gitr…"  gitrust    2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:4000->4000/tcp, 0.0.0.0:2222->2222/tcp
gitrust_postgres  postgres:16-alpine             "docker-entrypoint.s…"  postgres   2 minutes ago   Up 2 minutes (healthy)   5432/tcp

Les deux containers doivent afficher (healthy). Si l’un affiche (starting), attendez 30 secondes et relancez la commande. S’il affiche (unhealthy), consultez les logs avec docker compose logs gitrust ou docker compose logs postgres.

Étape 4 : Créez le premier compte administrateur

Ouvrez votre navigateur et rendez-vous sur http://localhost:4000.

Vous devriez voir la page d’accueil gitrust avec un formulaire d’inscription. Comme l’instance est vierge, le premier compte créé devient automatiquement administrateur.

Remplissez le formulaire :

• Pseudo : votre identifiant administrateur (ex. admin)
• E-mail : votre adresse e-mail
• Mot de passe : choisissez un mot de passe robuste (≥ 12 caractères)

Cliquez sur Créer mon compte.

Sortie attendue dans les logs (visible avec docker compose logs -f gitrust) :

gitrust_app  | 2026-04-17T10:05:00Z INFO  gitrust::auth > New user registered: admin (id=1)
gitrust_app  | 2026-04-17T10:05:00Z INFO  gitrust::admin > First user promoted to administrator: admin

Checkpoint final : connectez-vous avec vos identifiants. Après la connexion, vérifiez que le menu en haut à droite affiche un lien Administration (ou naviguez vers http://localhost:4000/admin). Cette page n’est accessible qu’aux administrateurs — sa présence confirme que votre compte a bien le rôle admin.

L’URL de votre instance est http://localhost:4000 et votre compte administrateur est opérationnel.

Récapitulatif

• ✓ O1 accompli : la stack docker-compose est déployée — docker compose ps affiche deux containers (healthy)
• ✓ O2 accompli : les trois services (app, PostgreSQL, réseau interne) démarrent correctement — les logs montrent « gitrust is ready » et les migrations sont appliquées
• ✓ O3 accompli : le premier compte administrateur est créé et la page /admin est accessible

Et si ça ne marche pas

Prochaine étape

→ 02 — Installation systemd : binaire natif + service : découvrez l’installation sans Docker pour un déploiement production avec hardening AppArmor (~45 min)

Ou si vous souhaitez rendre cette instance accessible depuis Internet :

→ 04 — Mise en production : reverse-proxy TLS, SMTP, sauvegarde automatique (~90 min)

Installer gitrust comme service systemd (binaire natif)

Objectifs

À la fin de ce tutoriel, vous saurez :

• O1. Créer un utilisateur système gitrust dédié et structurer l’arborescence /opt/gitrust
• O2. Configurer PostgreSQL pour gitrust et vérifier la connexion
• O3. Écrire et activer un fichier gitrust.service avec durcissement systemd
• O4. Démarrer gitrust et confirmer que le serveur HTTP et SSH répondent

Pré-requis

• Technique : Debian 12 ou Ubuntu 22.04 LTS (ou dérivé) ; accès root ou sudo ; curl, rsync, psql installés ; Docker non requis (c’est précisément l’alternative binaire natif)
• Pédagogique : Tutoriel 01-installation-docker lu ou notions équivalentes d’administration Linux
• Temps estimé : ~45 minutes

Vue d’ensemble

L’installation binaire natif place gitrust comme un service systemd classique, au même titre que nginx ou PostgreSQL. Il n’y a aucun conteneur : le binaire Rust s’exécute directement sous un utilisateur système dédié, avec un durcissement systemd (PrivateTmp, ProtectSystem, NoNewPrivileges).

graph LR
    A[Binaire gitrust<br/>/opt/gitrust/gitrust] -->|ExecStart| B[systemd unit<br/>gitrust.service]
    B -->|User=gitrust| C[Utilisateur système<br/>gitrust]
    C -->|R/W| D[/opt/gitrust/data<br/>repos + clé SSH]
    A -->|DATABASE_URL| E[PostgreSQL :5432]
    A -->|:4000| F[Navigateur / nginx]
    A -->|:2222| G[Client Git SSH]

Modèle mental : pensez à gitrust comme à nginx — un processus unique, lancé par systemd, propriétaire de ses données, sans jamais tourner en root.

Étape 1 : Créer l’utilisateur et l’arborescence

Créez un utilisateur système sans shell de login ni répertoire home personnel :

sudo useradd \
  --system \
  --home-dir /opt/gitrust \
  --shell /usr/sbin/nologin \
  --comment "Gitrust service" \
  gitrust

Créez l’arborescence de travail :

sudo mkdir -p /opt/gitrust/data/repos
sudo mkdir -p /opt/gitrust/static
sudo chown -R gitrust:gitrust /opt/gitrust
sudo chmod 750 /opt/gitrust

Sortie attendue (vérification) :

$ ls -la /opt/gitrust/
total 20
drwxr-x--- 4 gitrust gitrust 4096 ...
drwxr-xr-x 3 gitrust gitrust 4096 ...  data/
drwxr-xr-x 2 gitrust gitrust 4096 ...  static/

Checkpoint O1 : id gitrust doit retourner une ligne avec uid=NNN(gitrust) gid=NNN(gitrust). Si la commande échoue, relisez l’étape 1.

Étape 2 : Installer PostgreSQL et créer la base gitrust

Installez PostgreSQL si ce n’est pas fait :

sudo apt-get update
sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql

Créez l’utilisateur et la base de données :

sudo -u postgres psql <<'SQL'
CREATE USER gitrust WITH PASSWORD 'CHOISIR_UN_MOT_DE_PASSE_FORT';
CREATE DATABASE gitrust OWNER gitrust;
GRANT ALL PRIVILEGES ON DATABASE gitrust TO gitrust;
SQL

Vérifiez la connexion :

psql "postgres://gitrust:CHOISIR_UN_MOT_DE_PASSE_FORT@localhost:5432/gitrust" \
  -c "SELECT version();"

Sortie attendue :

                                                  version
------------------------------------------------------------------------------------------------------------
 PostgreSQL 15.x on x86_64-pc-linux-gnu, ...
(1 row)

Checkpoint O2 : Si psql retourne version(), la base est accessible. Conservez le mot de passe PostgreSQL pour l’étape suivante.

Étape 3 : Déployer le binaire gitrust

Sur votre machine de développement (ou sur le serveur si vous compilez localement) :

# Depuis la racine du dépôt gitrust
cargo build --release

Puis transférez vers le serveur :

# Depuis la machine de développement
rsync -avz target/release/gitrust  user@VOTRE_SERVEUR:/opt/gitrust/gitrust
rsync -avz static/                 user@VOTRE_SERVEUR:/opt/gitrust/static/

Sur le serveur, rendez le binaire exécutable et attribuez-le à l’utilisateur gitrust :

sudo chown gitrust:gitrust /opt/gitrust/gitrust
sudo chmod 750 /opt/gitrust/gitrust
sudo chown -R gitrust:gitrust /opt/gitrust/static/

Alternative : si vous utilisez deployment/deploy.sh (fourni dans le dépôt source), il effectue les étapes 1 à 5 automatiquement. Ce tutoriel décompose les étapes pour que vous compreniez ce que le script fait.

Étape 4 : Créer le fichier de configuration .env

Créez /opt/gitrust/.env avec les valeurs minimales de production :

sudo -u gitrust tee /opt/gitrust/.env <<'EOF'
# === BASE DE DONNÉES ===
DATABASE_URL=postgres://gitrust:CHOISIR_UN_MOT_DE_PASSE_FORT@localhost:5432/gitrust

# === SERVEUR HTTP ===
SERVER_HOST=127.0.0.1
SERVER_PORT=4000
RUST_LOG=info

# === SERVEUR SSH ===
SSH_PORT=2222
SSH_LISTEN_ADDR=0.0.0.0
SSH_HOST_KEY_PATH=/opt/gitrust/data/ssh_host_ed25519_key
SSH_PUBLIC_HOST=VOTRE_DOMAINE_OU_IP

# === DÉPÔTS GIT ===
GIT_REPOS_BASE_PATH=/opt/gitrust/data/repos

# === FICHIERS STATIQUES ===
STATIC_FILES_PATH=/opt/gitrust/static

# === JWT (OBLIGATOIRE — générer avec : openssl rand -hex 64) ===
JWT_SECRET=REMPLACER_PAR_OPENSSL_RAND_HEX_64
JWT_EXPIRATION_MINUTES=15
JWT_ISSUER=gitrust

# === SESSIONS ===
SESSION_TIMEOUT_MINUTES=30
SESSION_BACKEND=seaorm

# === COOKIES ===
COOKIE_SECURE=true
COOKIE_SAME_SITE=Lax
APP_DEBUG=false

# === ADMIN INITIAL ===
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@VOTRE_DOMAINE
ADMIN_PASSWORD=REMPLACER_PAR_MOT_DE_PASSE_FORT

# === EMAIL (optionnel au démarrage initial, configurer ensuite) ===
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
EMAIL_BASE_URL=https://VOTRE_DOMAINE
EOF

Sécurisez le fichier (il contient des secrets) :

sudo chmod 600 /opt/gitrust/.env
sudo chown gitrust:gitrust /opt/gitrust/.env

Générez le vrai secret JWT :

openssl rand -hex 64

Copiez la sortie et remplacez REMPLACER_PAR_OPENSSL_RAND_HEX_64 dans /opt/gitrust/.env.

Checkpoint : sudo -u gitrust stat /opt/gitrust/.env doit afficher Mode: 0600 et Uid: gitrust.

Étape 5 : Créer le fichier gitrust.service

Créez le fichier d’unité systemd :

sudo tee /etc/systemd/system/gitrust.service <<'EOF'
[Unit]
Description=Gitrust - Self-hosted Git platform
Documentation=https://gitrust.eu/fr/docs/
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=simple
User=gitrust
Group=gitrust
WorkingDirectory=/opt/gitrust
EnvironmentFile=/opt/gitrust/.env
ExecStart=/opt/gitrust/gitrust
Restart=on-failure
RestartSec=5
TimeoutStartSec=30
TimeoutStopSec=30

# --- Durcissement systemd ---
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictRealtime=true
RestrictSUIDSGID=true
LockPersonality=true

# Répertoires en écriture autorisés
ReadWritePaths=/opt/gitrust/data

# Si gitrust écoute sur un port < 1024 (ex: 80) :
# AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target
EOF

Rechargez systemd et activez le service :

sudo systemctl daemon-reload
sudo systemctl enable gitrust

Sortie attendue :

Created symlink /etc/systemd/system/multi-user.target.wants/gitrust.service → /etc/systemd/system/gitrust.service.

Checkpoint O3 : systemctl is-enabled gitrust doit afficher enabled.

Étape 6 : Premier démarrage et vérification

Démarrez le service :

sudo systemctl start gitrust

Attendez 3 secondes, puis vérifiez le statut :

sudo systemctl status gitrust

Sortie attendue :

● gitrust.service - Gitrust - Self-hosted Git platform
     Loaded: loaded (/etc/systemd/system/gitrust.service; enabled; vendor preset: enabled)
     Active: active (running) since ... ago
   Main PID: XXXX (gitrust)
      Tasks: N (limit: NNNN)
     Memory: NNM
        CPU: NNNms
     CGroup: /system.slice/gitrust.service
             └─XXXX /opt/gitrust/gitrust

Vérifiez que les ports répondent :

# HTTP
curl -s -o /dev/null -w "%{http_code}" http://localhost:4000/
# Attendu : 200 ou 302

# SSH (vérification du fingerprint)
ssh-keyscan -p 2222 -H localhost 2>/dev/null | head -1
# Attendu : [localhost]:2222 ssh-ed25519 AAAA...

Consultez les logs pour les migrations automatiques :

sudo journalctl -u gitrust -n 50 --no-pager

Cherchez les lignes :

INFO gitrust_core::migrations: Running migrations...
INFO gitrust_core::migrations: Applied migration m20260325_000001_create_repositories
...
INFO gitrust_core::migrations: All migrations applied successfully
INFO rustwarden_core::services::default_admin_service: Admin user 'admin' created

Checkpoint O4 : curl http://localhost:4000/ retourne du HTML (code 200 ou 302). Le service est opérationnel.

Récapitulatif

• ✓ O1 accompli en créant l’utilisateur système gitrust et l’arborescence /opt/gitrust
• ✓ O2 accompli en configurant PostgreSQL et en vérifiant la connexion avec psql
• ✓ O3 accompli en rédigeant gitrust.service avec les directives de durcissement systemd
• ✓ O4 accompli en démarrant le service et en confirmant la réponse HTTP et SSH

Et si ça ne marche pas

Prochaine étape

→ 03 — Premier démarrage : bootstrap admin, clé SSH hôte, vérification santé

Premier démarrage : bootstrap admin, clé SSH hôte et vérification santé

Objectifs

À la fin de ce tutoriel, vous saurez :

• O1. Expliquer comment gitrust crée automatiquement le compte administrateur initial à partir des variables ADMIN_*
• O2. Identifier et vérifier la clé SSH hôte Ed25519 générée automatiquement au premier démarrage
• O3. Confirmer que les trois services (HTTP :4000, SSH :2222, PostgreSQL :5432) sont sains via des commandes de vérification
• O4. Vous connecter à l’interface d’administration /admin pour la première fois

Pré-requis

• Technique : gitrust installé et démarré via 01-installation-docker ou 02-installation-systemd ; curl, ssh-keyscan, psql disponibles
• Pédagogique : Tutoriel 01 ou 02 complété — gitrust doit être active (running)
• Temps estimé : ~20 minutes

Vue d’ensemble

Le premier démarrage de gitrust effectue automatiquement trois opérations critiques, dans cet ordre :

sequenceDiagram
    participant S as systemd / Docker
    participant G as gitrust (binaire)
    participant PG as PostgreSQL
    participant FS as Système de fichiers

    S->>G: ExecStart / docker run
    G->>PG: Connexion DATABASE_URL
    G->>PG: AppMigrator::run_migrations()
    PG-->>G: Migrations OK (18 tables créées)
    G->>FS: SSH_HOST_KEY_PATH absent ?
    FS-->>G: Absent
    G->>FS: Génère Ed25519 host key
    G->>PG: ensure_default_admin() — users vide ?
    PG-->>G: Vide
    G->>PG: INSERT admin (ADMIN_USERNAME, ADMIN_EMAIL, hash(ADMIN_PASSWORD))
    G-->>S: Listening on :4000 (HTTP) et :2222 (SSH)

Modèle mental : c’est le même principe qu’un routeur domestique — à la première mise sous tension, il crée un mot de passe admin par défaut (ici fourni par vous via .env) et ne recommence jamais s’il existe déjà des données.

Étape 1 : Vérifier les migrations automatiques

Les migrations sont appliquées à chaque démarrage, mais seulement si elles n’ont pas encore été jouées. Elles sont idempotentes.

Consultez les logs :

# Installation systemd
sudo journalctl -u gitrust --since "10 minutes ago" --no-pager | grep -E "migrat|admin|listen"

# Installation Docker
docker compose logs gitrust 2>&1 | grep -E "migrat|admin|listen"

Sortie attendue (premier démarrage) :

INFO gitrust_core::migrations: Running migrations...
INFO gitrust_core::migrations: Applied migration m20260305_000001_initial_schema
INFO gitrust_core::migrations: Applied migration m20260306_000002_create_app_settings_table
...
INFO gitrust_core::migrations: Applied migration m20260327_000013_create_pr_comments
INFO gitrust_core::migrations: All migrations applied successfully (18 applied)
INFO rustwarden_core::services::default_admin_service: Admin user 'admin' created
INFO gitrust_web: HTTP server listening on 127.0.0.1:4000
INFO gitrust_ssh: SSH server listening on 0.0.0.0:2222

Sortie attendue (démarrage suivant) :

INFO gitrust_core::migrations: Running migrations...
INFO gitrust_core::migrations: No pending migrations

Checkpoint O1 : si vous voyez Admin user 'admin' created, le bootstrap admin a fonctionné. Si vous voyez Admin user already exists, skipping, un compte admin existait déjà — c’est normal si ce n’est pas le tout premier démarrage.

Étape 2 : Vérifier la clé SSH hôte

gitrust génère une clé Ed25519 à SSH_HOST_KEY_PATH si elle n’existe pas. Cette clé identifie votre instance auprès des clients Git.

Vérifiez que la clé existe :

# Systemd
sudo -u gitrust ls -la /opt/gitrust/data/ssh_host_ed25519_key*

# Docker (le volume est monté dans /data dans le conteneur)
docker compose exec gitrust ls -la /data/ssh_host_ed25519_key*

Sortie attendue :

-rw------- 1 gitrust gitrust  399 ...  /opt/gitrust/data/ssh_host_ed25519_key
-rw-r--r-- 1 gitrust gitrust   93 ...  /opt/gitrust/data/ssh_host_ed25519_key.pub

Affichez le fingerprint SHA256 (à conserver précieusement — vos utilisateurs vérifieront ce fingerprint lors du premier git clone) :

# Systemd
sudo -u gitrust ssh-keygen -l -f /opt/gitrust/data/ssh_host_ed25519_key.pub

# Docker
docker compose exec gitrust ssh-keygen -l -f /data/ssh_host_ed25519_key.pub

Sortie attendue :

256 SHA256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX gitrust-host-key (ED25519)

Important : notez ce fingerprint SHA256 dans votre documentation interne. Vos utilisateurs devront le comparer lors du premier ssh-keyscan ou lors du message The authenticity of host ... can't be established. Si vous régénérez cette clé après que des utilisateurs ont cloné des dépôts, leur ~/.ssh/known_hosts sera en conflit et tous les push/pull échoueront.

Checkpoint O2 : les deux fichiers existent avec les bonnes permissions (clé privée 600, clé publique 644).

Étape 3 : Vérifier la santé des trois services

HTTP :4000

curl -v http://localhost:4000/ 2>&1 | grep -E "^< HTTP|Location"

Sortie attendue :

< HTTP/1.1 302 Found
< location: /login

Une redirection vers /login signifie que gitrust répond et que le routeur fonctionne.

SSH :2222

ssh-keyscan -p 2222 -H localhost 2>/dev/null

Sortie attendue :

[localhost]:2222 ssh-ed25519 AAAA... (votre clé hôte)

Si aucune sortie, le serveur SSH n’écoute pas encore — consultez les logs.

PostgreSQL :5432

# Depuis l'hôte
psql "postgres://gitrust:VOTRE_MOT_DE_PASSE@localhost:5432/gitrust" \
  -c "SELECT COUNT(*) AS nb_tables FROM information_schema.tables WHERE table_schema='public';"

Sortie attendue :

 nb_tables
-----------
        18
(1 row)

18 tables = toutes les migrations ont été appliquées.

Checkpoint O3 : les trois commandes répondent comme attendu. Si l’une échoue, consultez la section « Et si ça ne marche pas ».

Étape 4 : Premier accès à l’interface d’administration

Ouvrez votre navigateur sur http://VOTRE_SERVEUR:4000/login (ou https:// si vous avez déjà configuré un reverse-proxy TLS).

Connectez-vous avec :

• Identifiant : valeur de ADMIN_USERNAME dans votre .env (par défaut : admin)
• Mot de passe : valeur de ADMIN_PASSWORD dans votre .env

Après connexion, accédez au tableau de bord d’administration :

http://VOTRE_SERVEUR:4000/admin

Vous devriez voir :

• Le nombre d’utilisateurs (1 — l’admin initial)
• Le nombre de dépôts (0)
• L’état des services CI

Sécurité : changez immédiatement le mot de passe admin via /admin/users ou le profil utilisateur si vous avez utilisé un mot de passe faible dans .env. Ensuite, vous pouvez supprimer ou commenter ADMIN_PASSWORD dans .env — gitrust ne recrée le compte admin que si la table users est vide.

Checkpoint O4 : vous êtes connecté à /admin et le tableau de bord s’affiche sans erreur.

Récapitulatif

• ✓ O1 accompli en lisant les logs de démarrage qui confirment les migrations et la création du compte admin
• ✓ O2 accompli en vérifiant l’existence et le fingerprint SHA256 de la clé SSH hôte Ed25519
• ✓ O3 accompli en testant HTTP (:4000 → 302), SSH (:2222 → fingerprint) et PostgreSQL (:5432 → 18 tables)
• ✓ O4 accompli en se connectant à /admin avec les identifiants ADMIN_* du .env

Et si ça ne marche pas

Prochaine étape

→ 04 — Mise en production : reverse-proxy TLS, SMTP, sauvegarde

Ou, si vous voulez configurer les fonctionnalités avancées maintenant :

• Configurer SMTP
• Configurer OAuth
• Sauvegarder l’instance

Mise en production sur une machine Linux avec HTTPS Let’s Encrypt

Contexte

Procédure de référence pour déployer une instance gitrust sur une machine Linux à IP fixe, avec patte externe routée et HTTPS via Let’s Encrypt. Reproductible et testée en conditions réelles.

Adaptez les valeurs suivantes à votre environnement :

Les trois services gitrust

PostgreSQL = dépendance, conteneur Docker bind loopback 127.0.0.1:5432.

Topologie réseau

Internet
    |
    v
<your-server-ip> (patte externe)
    |
    +-- :22   Nginx stream  --> 127.0.0.1:2222 (gitrust SSH)
    +-- :80   Nginx HTTP    --> 301 HTTPS (sauf /.well-known/acme-challenge)
    +-- :443  Nginx HTTPS   --> 127.0.0.1:4000 (gitrust HTTP)
    +-- :2022 sshd système  (accès admin, déplacé depuis :22)

    Loopback uniquement :
    +-- 127.0.0.1:4000  gitrust web
    +-- 127.0.0.1:2222  gitrust SSH
    +-- 127.0.0.1:5432  postgres docker

Risque critique — ordre d’exécution

Le déplacement de sshd système de :22 vers :2022 doit être fait avant la configuration nginx stream, et doit être validé depuis une deuxième session SSH avant fermeture de la première. Sinon : lockout total (besoin d’accès console physique).

Pré-requis

Poste de build (machine locale avec le code source)

rustup show && command -v rsync envsubst npx
# Installer si besoin : sudo apt install rsync gettext-base

Cible <your-server-ip>

• Debian/Ubuntu récent
• Accès SSH avec sudo
• Docker + plugin compose (docker compose version)
• Snap ou apt pour certbot + plugin nginx
• DNS <your-domain> → IP publique de la patte externe (vérifier dig +short <your-domain>)
• Module stream Nginx disponible (paquet libnginx-mod-stream sur Debian)

Phase 0 — Générer .env.production (poste de build, une seule fois)

JWT=$(openssl rand -hex 64)
ADMIN_PWD=$(openssl rand -base64 24)
PG_PWD=$(openssl rand -base64 24)

cat > .env.production <<EOF
# ---- Base de données ----
DATABASE_URL=postgres://gitrust:${PG_PWD}@127.0.0.1:5432/gitrust

# ---- Serveur HTTP (derrière Nginx HTTPS) ----
SERVER_HOST=127.0.0.1
SERVER_PORT=4000

# ---- Serveur SSH (derrière nginx stream :22) ----
SSH_PORT=2222
SSH_LISTEN_ADDR=127.0.0.1
SSH_PUBLIC_HOST=<your-domain>
SSH_HOST_KEY_PATH=/opt/gitrust/data/ssh_host_ed25519_key

# ---- Chemins (réécrits par deploy.sh) ----
GIT_REPOS_BASE_PATH=/opt/gitrust/data/repos
STATIC_FILES_PATH=/opt/gitrust/static

# ---- Sécurité — HTTPS actif ----
JWT_SECRET=${JWT}
JWT_EXPIRATION_MINUTES=15
REFRESH_TOKEN_EXPIRATION_DAYS=7
COOKIE_SECURE=true            # HTTPS via Nginx
COOKIE_SAME_SITE=Lax
APP_DEBUG=false
RUST_LOG=info

# ---- Admin initial ----
ADMIN_USERNAME=admin
ADMIN_EMAIL=<acme-email>
ADMIN_PASSWORD=${ADMIN_PWD}

# ---- Inscription & UI ----
ALLOW_REGISTRATION=false
APP_NAME=Gitrust
DEFAULT_LOCALE=fr

# ---- Email ----
EMAIL_VALIDATION_REQUIRED=false
EMAIL_BASE_URL=https://<your-domain>

# ---- CI/CD Dagger (worker 3) ----
CI_ENABLED=true
CI_MAX_CONCURRENT=4
CI_DEFAULT_TIMEOUT=3600
CI_WORKSPACE_PATH=/tmp/gitrust-ci
CI_REMOTE_HOST=localhost

# ---- Worker import ----
IMPORT_MAX_CONCURRENT=2
IMPORT_TIMEOUT_SECS=1800
DB_WORKER_POOL_SIZE=4
EOF

chmod 600 .env.production
echo "ADMIN_PASSWORD = ${ADMIN_PWD}"
echo "POSTGRES_PASSWORD = ${PG_PWD}"

Critique : noter ADMIN_PASSWORD et POSTGRES_PASSWORD dans un gestionnaire de mots de passe.

Phase 1 — Préparer la cible : déplacer sshd système sur :2022

À faire en gardant deux sessions SSH simultanées.

1.pre. Diagnostic de l’état initial

1.pre.1 — Trouver le port SSH ouvert depuis le poste de build

# Depuis votre poste (sans être connecté) :
for p in 22 2022 2222 2200 22022; do
  timeout 3 bash -c "echo >/dev/tcp/<your-server-ip>/$p" 2>/dev/null \
    && echo "Port $p : OUVERT" \
    || echo "Port $p : fermé/filtré"
done

1.pre.2 — Se connecter sur le port détecté

# Cas le plus probable : sshd est sur :22 par défaut
ssh <admin-user>@<your-server-ip>

1.pre.3 — Une fois connecté, vérifier l’état sshd actuel

# Sur quel(s) port(s) sshd écoute-t-il ?
sudo ss -tlnp | grep sshd

# Contenu de la config
sudo grep -riE '^[[:space:]]*Port[[:space:]]+[0-9]+' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/ 2>/dev/null

# Statut du service
sudo systemctl status ssh --no-pager

1a. Session 1 : modifier la config sshd

ssh <admin-user>@<your-server-ip>

# Éditer /etc/ssh/sshd_config
sudo tee /etc/ssh/sshd_config.d/99-gitrust.conf <<'EOF'
Port 2022
EOF

# Vérifier la syntaxe
sudo sshd -t

# Si OK, reload (ne déconnecte pas la session courante)
sudo systemctl reload ssh
sudo ss -tlnp | grep -E ':22\b|:2022\b'
# Attendu : sshd écoute sur 22 ET 2022

1b. Session 2 : valider le nouveau port

Depuis le poste de build, dans un autre terminal :

ssh -p 2022 <admin-user>@<your-server-ip> 'echo "OK port 2022"'
# Doit afficher : OK port 2022

1c. (Plus tard, après Phase 5) Fermer le port 22 du sshd système

Une fois nginx stream :22 actif et testé :

ssh -p 2022 <admin-user>@<your-server-ip>
sudo sed -i 's/^Port 22$/# Port 22 (déplacé vers 2022, :22 utilisé par nginx stream)/' /etc/ssh/sshd_config
sudo systemctl restart ssh

1d. Firewall

ssh -p 2022 <admin-user>@<your-server-ip> bash <<'EOF'
sudo ufw allow 80/tcp comment 'HTTP ACME + redirect'
sudo ufw allow 443/tcp comment 'HTTPS Gitrust'
sudo ufw allow 22/tcp comment 'SSH Git via nginx stream'
sudo ufw allow 2022/tcp comment 'SSH admin système'
sudo ufw status numbered
EOF

Mettre à jour ~/.ssh/config côté poste dev :

Host gitrust-host
    HostName <your-server-ip>
    User <admin-user>
    Port 2022

Le reste du plan utilise ssh gitrust-host.

Phase 2 — PostgreSQL (Docker, loopback)

scp -P 2022 database/docker-compose.yml <admin-user>@<your-server-ip>:/tmp/pg-compose.yml

ssh gitrust-host bash <<EOF
sudo mkdir -p /opt/gitrust/database
sudo mv /tmp/pg-compose.yml /opt/gitrust/database/docker-compose.yml
echo 'POSTGRES_PASSWORD=${PG_PWD}' | sudo tee /opt/gitrust/database/.env >/dev/null
sudo chmod 600 /opt/gitrust/database/.env
cd /opt/gitrust/database && sudo docker compose up -d
sudo docker compose ps
EOF

Remplacer ${PG_PWD} par la valeur réelle. Vérifier que le port n’est pas exposé publiquement :

ssh gitrust-host 'sudo ss -tlnp | grep 5432'
# Attendu : 127.0.0.1:5432 — PAS 0.0.0.0

Phase 3 — Build + déploiement gitrust via deploy.sh

3a. Préparer deployment/deploy.conf

cp deployment/deploy.conf.example deployment/deploy.conf
# Éditer DEPLOY_TARGET=gitrust-host, DEPLOY_REMOTE_PATH=/opt/gitrust, DEPLOY_FQDN_INITIAL=<your-domain>
$EDITOR deployment/deploy.conf
chmod 600 deployment/deploy.conf

3b. Validation du build seul (optionnel)

BUILD_ONLY=1 ./deployment/deploy.sh

3c. Déploiement

# Sans argument : utilise DEPLOY_TARGET du deploy.conf (gitrust-host via ~/.ssh/config, port 2022)
./deployment/deploy.sh

Ce que fait deploy.sh : cargo build --release, tailwindcss --minify, adapte gitrust.service + .env, rsync, crée user gitrust, installe systemd, restart.

À la fin : gitrust écoute sur 127.0.0.1:4000 (HTTP) et 127.0.0.1:2222 (SSH).

ssh gitrust-host 'sudo systemctl status gitrust --no-pager && sudo ss -tlnp | grep -E "4000|2222"'
# Attendu : 127.0.0.1:4000 et 127.0.0.1:2222 (PAS 0.0.0.0)

Phase 4 — Nginx HTTP + Let’s Encrypt

4a. Installer nginx + certbot

ssh gitrust-host bash <<'EOF'
sudo apt update
sudo apt install -y nginx libnginx-mod-stream certbot python3-certbot-nginx
sudo systemctl enable --now nginx
EOF

4b. Déployer la conf Nginx

scp -P 2022 deployment/nginx-gitrust.conf <admin-user>@<your-server-ip>:/tmp/gitrust-nginx.conf

ssh gitrust-host bash <<EOF
sudo sed -i 's/gitrust.nuage.ebii/<your-domain>/g' /tmp/gitrust-nginx.conf
sudo mv /tmp/gitrust-nginx.conf /etc/nginx/sites-available/gitrust
sudo ln -sf /etc/nginx/sites-available/gitrust /etc/nginx/sites-enabled/gitrust
sudo rm -f /etc/nginx/sites-enabled/default
sudo mkdir -p /var/www/html/.well-known/acme-challenge
sudo nginx -t && sudo systemctl reload nginx
EOF

4c. Émettre le certificat Let’s Encrypt

ssh gitrust-host 'sudo certbot --nginx \
    -d <your-domain> \
    --email <acme-email> \
    --agree-tos \
    --no-eff-email \
    --redirect'

4d. Vérifier le renouvellement automatique

ssh gitrust-host 'sudo systemctl list-timers | grep certbot'
ssh gitrust-host 'sudo certbot renew --dry-run'

4e. Test HTTPS

curl -I https://<your-domain>/
# Attendu : HTTP/2 200 (ou 302 vers /login)

# Vérifier HSTS
curl -sI https://<your-domain>/ | grep -i strict-transport

Phase 5 — Exposer SSH Git sur :22 via Nginx stream

5a. Ajouter le bloc stream

ssh gitrust-host bash <<'EOF'
sudo nginx -V 2>&1 | grep -o with-stream

sudo tee -a /etc/nginx/nginx.conf <<'NGINX'

# --- Gitrust SSH (proxy :22 -> :2222) -----------------------------------------
stream {
    upstream gitrust_ssh {
        server 127.0.0.1:2222;
    }
    server {
        listen 22;
        listen [::]:22;
        proxy_pass gitrust_ssh;
        proxy_timeout 1h;
        proxy_connect_timeout 30s;
        error_log /var/log/nginx/gitrust-ssh.log;
    }
}
NGINX

sudo nginx -t && sudo systemctl restart nginx
sudo ss -tlnp | grep -E ':22\b|:2222\b'
# Attendu : nginx :22, gitrust :2222 (loopback)
EOF

5b. Désactiver sshd système sur :22 (Phase 1c)

ssh -p 2022 <admin-user>@<your-server-ip> bash <<'EOF'
sudo sed -i 's/^Port 22$/# Port 22 déplacé/' /etc/ssh/sshd_config 2>/dev/null || true
sudo systemctl restart ssh
sudo ss -tlnp | grep -E ':22\b|:2022\b'
# Attendu : nginx :22, sshd :2022 — plus de sshd:22
EOF

5c. Test clone Git

# Dans l'UI gitrust : Settings -> SSH keys -> coller ~/.ssh/id_ed25519.pub
# Créer un repo test admin/test-deploy via UI

git clone git@<your-domain>:admin/test-deploy.git /tmp/test-deploy
cd /tmp/test-deploy
echo "# test" > README.md
git -c user.email=<acme-email> -c user.name=admin add . && \
  git -c user.email=<acme-email> -c user.name=admin commit -m "test deploy" && \
  git push origin main

Phase 6 — Vérifications globales

# Service systemd
ssh gitrust-host 'sudo systemctl status gitrust --no-pager'

# Logs (recherche d'erreurs)
ssh gitrust-host 'sudo journalctl -u gitrust -n 100 --no-pager | grep -iE "error|warn|fail"'

# Ports d'écoute (vue d'ensemble)
ssh gitrust-host 'sudo ss -tlnp'
# Attendu :
#   :22    nginx
#   :80    nginx
#   :443   nginx
#   :2022  sshd système
#   127.0.0.1:2222  gitrust
#   127.0.0.1:4000  gitrust
#   127.0.0.1:5432  docker-proxy

# Renouvellement TLS automatique
ssh gitrust-host 'sudo systemctl status certbot.timer --no-pager'

# Test E2E
curl -I https://<your-domain>/login
ssh -T git@<your-domain> || true   # Banner SSH russh attendu

Phase 7 — Durcissement : Fail2ban

Voir administration_manual/how-to/durcir-avec-fail2ban.md pour la configuration complète.

7a. Installation

ssh gitrust-host bash <<'EOF'
sudo apt install -y fail2ban
sudo systemctl enable --now fail2ban
EOF

7b. Configuration minimale rapide

ssh gitrust-host sudo tee /etc/fail2ban/jail.local <<'EOF'
[DEFAULT]
backend  = systemd
bantime  = 1h
findtime = 10m
maxretry = 5
ignoreip = 127.0.0.1/8 ::1
banaction          = ufw
banaction_allports = ufw

[sshd]
enabled  = true
port     = 2022
filter   = sshd
backend  = %(sshd_backend)s
logpath  = %(sshd_log)s
maxretry = 3

[nginx-http-auth]
enabled  = true
port     = http,https
filter   = nginx-http-auth
logpath  = /var/log/nginx/gitrust.error.log

[gitrust-login]
enabled  = true
port     = http,https
filter   = gitrust-login
logpath  = /var/log/nginx/gitrust.access.log
maxretry = 5

[gitrust-ssh]
enabled      = true
port         = 22,2222
filter       = gitrust-ssh
backend      = systemd
journalmatch = _SYSTEMD_UNIT=gitrust.service
maxretry     = 5

[recidive]
enabled   = true
logpath   = /var/log/fail2ban.log
banaction = %(banaction_allports)s
bantime   = 1w
findtime  = 1d
maxretry  = 3
EOF

Créer les filtres gitrust-login et gitrust-ssh, puis :

ssh gitrust-host 'sudo systemctl restart fail2ban && sudo fail2ban-client status'

Phase 8 — Mise à jour vers un nouveau domaine (quand DNS prêt)

8a. Ajouter le SAN au certificat existant

ssh gitrust-host 'sudo certbot --nginx --expand \
    -d <your-domain> \
    -d <new-domain> \
    --email <acme-email> \
    --agree-tos --no-eff-email'

8b. Mettre à jour la conf Nginx

ssh gitrust-host bash <<EOF
sudo sed -i 's/server_name <your-domain>;/server_name <your-domain> <new-domain>;/g' /etc/nginx/sites-available/gitrust
sudo nginx -t && sudo systemctl reload nginx
EOF

8c. Mettre à jour .env.production et redéployer

sed -i 's|SSH_PUBLIC_HOST=.*|SSH_PUBLIC_HOST=<new-domain>|' .env.production
sed -i 's|EMAIL_BASE_URL=.*|EMAIL_BASE_URL=https://<new-domain>|' .env.production
./deployment/deploy.sh gitrust-host

Phase 9 — Mises à jour ultérieures

git pull
SKIP_ENV=1 SKIP_DB=1 ./deployment/deploy.sh

Dépannage

Récapitulatif des ports

Guides pratiques — Manuel d’administration

Les guides pratiques répondent à une question précise : « Comment faire X ? » Chaque guide est une recette orientée tâche, utilisable indépendamment, sans contexte pédagogique. Vous êtes supposé avoir déjà une instance gitrust opérationnelle.

Prérequis : parcours tutoriel complété (tutoriels 01-03 minimum). Si vous démarrez, commencez par les tutoriels.

Exploitation quotidienne

Configuration des services

Maintenance et sécurité

Dépannage

Runners CI distants

Trouver rapidement la bonne page

• Vous cherchez la valeur d’une variable d’environnement → Référence des variables
• Vous voulez comprendre pourquoi quelque chose fonctionne ainsi → Explanations
• Vous commencez depuis zéro → Tutoriels

Sauvegarder et restaurer une instance gitrust

À qui s’adresse cette page

Administrateurs qui souhaitent mettre en place une sauvegarde fiable et tester la restauration. Pour comprendre la stratégie 3-2-1 adaptée à gitrust, consultez Stratégie de sauvegarde.

Ce qu’il faut sauvegarder

Gitrust repose sur trois sources de vérité distinctes :

La clé SSH hôte est immuable après le premier démarrage. Si vous la perdez, tous vos utilisateurs devront supprimer leur entrée known_hosts et re-vérifier le fingerprint.

Sauvegarder

Sauvegarde PostgreSQL (pg_dump)

BACKUP_DIR="/var/backups/gitrust"
DATE=$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"

pg_dump \
  -h localhost \
  -U gitrust \
  --format=custom \
  --file="${BACKUP_DIR}/pg-${DATE}.dump" \
  gitrust

echo "Dump : ${BACKUP_DIR}/pg-${DATE}.dump"
# Purger les sauvegardes de plus de 30 jours
find "$BACKUP_DIR" -name "pg-*.dump" -mtime +30 -delete

Le format --format=custom est compressé et restaurable avec pg_restore. Le fichier contient la structure ET les données.

Sauvegarde des dépôts bare (rsync)

REPOS_SRC="/opt/gitrust/data/repos"
REPOS_DST="/var/backups/gitrust/repos"

rsync \
  --archive \
  --delete \
  --hard-links \
  --checksum \
  "${REPOS_SRC}/" "${REPOS_DST}/"

Les dépôts bare Git sont consistants en lecture même pendant un git push actif : Git garantit l’atomicité au niveau du pack.

Sauvegarde de la clé SSH hôte et du .env

BACKUP_DIR="/var/backups/gitrust"
DATE=$(date +%Y%m%d-%H%M%S)

tar czf "${BACKUP_DIR}/config-${DATE}.tar.gz" \
  /opt/gitrust/data/ssh_host_ed25519_key \
  /opt/gitrust/data/ssh_host_ed25519_key.pub \
  /opt/gitrust/.env

chmod 600 "${BACKUP_DIR}/config-${DATE}.tar.gz"

Script complet backup.sh

#!/usr/bin/env bash
# /opt/gitrust/scripts/backup.sh
set -euo pipefail

BACKUP_DIR="${BACKUP_DIR:-/var/backups/gitrust}"
DATE=$(date +%Y%m%d-%H%M%S)
PG_USER="gitrust"
PG_DB="gitrust"
REPOS_SRC="/opt/gitrust/data/repos"
SSH_KEY="/opt/gitrust/data/ssh_host_ed25519_key"
ENV_FILE="/opt/gitrust/.env"

mkdir -p "$BACKUP_DIR"

echo "[1/3] Dump PostgreSQL..."
pg_dump -U "$PG_USER" --format=custom \
  --file="${BACKUP_DIR}/pg-${DATE}.dump" "$PG_DB"

echo "[2/3] Rsync dépôts bare..."
mkdir -p "${BACKUP_DIR}/repos"
rsync --archive --delete --checksum \
  "${REPOS_SRC}/" "${BACKUP_DIR}/repos/"

echo "[3/3] Archive config sensible..."
tar czf "${BACKUP_DIR}/config-${DATE}.tar.gz" \
  "$SSH_KEY" "${SSH_KEY}.pub" "$ENV_FILE"
chmod 600 "${BACKUP_DIR}/config-${DATE}.tar.gz"

echo "Sauvegarde terminée dans $BACKUP_DIR"
find "$BACKUP_DIR" -name "pg-*.dump" -mtime +30 -delete
find "$BACKUP_DIR" -name "config-*.tar.gz" -mtime +90 -delete

Planifier via cron :

# Sauvegarder chaque nuit à 2h00
0 2 * * * /opt/gitrust/scripts/backup.sh >> /var/log/gitrust-backup.log 2>&1

Restaurer

Avant toute restauration

# 1. Arrêter gitrust
sudo systemctl stop gitrust   # ou : docker compose stop gitrust

# 2. Vérifier les fichiers de sauvegarde disponibles
ls -lh /var/backups/gitrust/pg-*.dump | tail -5
ls -lh /var/backups/gitrust/config-*.tar.gz | tail -3
du -sh /var/backups/gitrust/repos/

Restaurer la base PostgreSQL

DUMP="/var/backups/gitrust/pg-20260417-020000.dump"

sudo -u postgres psql -c "DROP DATABASE IF EXISTS gitrust;"
sudo -u postgres psql -c "CREATE DATABASE gitrust OWNER gitrust;"

pg_restore \
  -h localhost \
  -U gitrust \
  --dbname=gitrust \
  --verbose \
  "$DUMP"

Vérification :

psql "postgres://gitrust:MOT_DE_PASSE@localhost:5432/gitrust" \
  -c "SELECT COUNT(*) FROM users; SELECT COUNT(*) FROM repositories;"

Restaurer les dépôts bare

REPOS_SRC="/var/backups/gitrust/repos"
REPOS_DST="/opt/gitrust/data/repos"

rsync --archive --delete "${REPOS_SRC}/" "${REPOS_DST}/"
sudo chown -R gitrust:gitrust "${REPOS_DST}"

Restaurer la clé SSH hôte et le .env

ARCHIVE="/var/backups/gitrust/config-20260417-020000.tar.gz"

sudo tar xzf "$ARCHIVE" -C /
sudo chown gitrust:gitrust /opt/gitrust/data/ssh_host_ed25519_key*
sudo chmod 600 /opt/gitrust/data/ssh_host_ed25519_key
sudo chmod 644 /opt/gitrust/data/ssh_host_ed25519_key.pub
sudo chmod 600 /opt/gitrust/.env

Redémarrer et vérifier

sudo systemctl start gitrust
sleep 3
curl -s -o /dev/null -w "%{http_code}" http://localhost:4000/
# Attendu : 302

Tester la restauration (drill trimestriel)

Une sauvegarde non testée n’est pas une sauvegarde. Testez sur une VM distincte :

# Sur une VM de test vierge — restaurer, puis vérifier :
git clone ssh://git@VM_TEST:2222/admin/un-depot-connu.git /tmp/drill-test
ls /tmp/drill-test/
# Les fichiers doivent correspondre à l'état au moment de la sauvegarde

Pour aller plus loin

• Stratégie de sauvegarde — comprendre le 3-2-1 adapté à gitrust
• Variables d’environnement : GIT_REPOS_BASE_PATH, SSH_HOST_KEY_PATH

Mettre à jour gitrust

À qui s’adresse cette page

Administrateurs qui souhaitent appliquer une nouvelle version de gitrust sur une instance en production, en limitant les risques.

Principe général

Les migrations de base de données sont appliquées automatiquement au démarrage par AppMigrator. Vous n’avez jamais à exécuter de commande SQL manuellement. Le binaire contient toujours les migrations cumulatives.

flowchart LR
    A[Sauvegarde] --> B[Arrêt service]
    B --> C[Déploiement<br/>nouveau binaire]
    C --> D[Démarrage]
    D --> E{Migrations<br/>auto ?}
    E -->|OK| F[Smoke test]
    E -->|Erreur| G[Rollback]
    F -->|OK| H[Terminé]
    F -->|Erreur| G

Checklist de mise à jour

1. Sauvegarder avant tout

# Sauvegarde complète avant toute modification
/opt/gitrust/scripts/backup.sh

Vérifiez que le dump PostgreSQL a été créé :

ls -lh /var/backups/gitrust/pg-$(date +%Y%m%d)*.dump

Ne passez à l’étape 2 que si la sauvegarde est confirmée.

2. Arrêter le service

# Systemd
sudo systemctl stop gitrust

# Docker Compose
docker compose stop gitrust

Attendez la confirmation :

sudo systemctl is-active gitrust
# Attendu : inactive

3. Déployer le nouveau binaire

Option A — via deploy.sh (recommandé si vous compilez localement) :

# Sur la machine de développement, depuis la racine du dépôt gitrust
./deployment/deploy.sh user@VOTRE_SERVEUR /opt/gitrust

Le script compile en release, synchronise le binaire, les assets statiques et le service systemd, puis redémarre automatiquement.

Option B — manuellement :

# Compiler le nouveau binaire
cargo build --release

# Compiler le CSS si les templates ont changé
npx tailwindcss -i static/css/input.css -o static/css/style.css --minify

# Transférer
rsync -avz target/release/gitrust  user@VOTRE_SERVEUR:/opt/gitrust/gitrust
rsync -avz static/                 user@VOTRE_SERVEUR:/opt/gitrust/static/

# Sur le serveur
sudo chown gitrust:gitrust /opt/gitrust/gitrust
sudo chmod 750 /opt/gitrust/gitrust

4. Vérifier les éventuels changements de .env

Consultez le CHANGELOG de la nouvelle version pour identifier les nouvelles variables d’environnement. Ajoutez-les à /opt/gitrust/.env si nécessaire, avec des valeurs appropriées.

# Comparer votre .env avec .env.example de la nouvelle version
diff /opt/gitrust/.env .env.example | grep "^>"

5. Démarrer le service

# Systemd
sudo systemctl start gitrust

# Docker Compose
docker compose up -d gitrust

6. Vérifier les migrations automatiques

sudo journalctl -u gitrust --since "2 minutes ago" --no-pager | grep -E "migrat|error|panic"

Sortie attendue si de nouvelles migrations ont été appliquées :

INFO gitrust_core::migrations: Applied migration m20260501_000014_add_webhooks
INFO gitrust_core::migrations: All migrations applied successfully

Sortie attendue si aucune nouvelle migration :

INFO gitrust_core::migrations: No pending migrations

Si vous voyez ERROR ou panic, consultez la section Rollback.

7. Smoke test

# HTTP
curl -s -o /dev/null -w "%{http_code}" http://localhost:4000/
# Attendu : 302

# SSH (fingerprint inchangé — comparer avec la valeur notée)
ssh-keyscan -p 2222 -H localhost 2>/dev/null | ssh-keygen -l -f -

Connectez-vous à l’interface /admin et vérifiez :

• La liste des utilisateurs est correcte
• Un dépôt existant est accessible
• La page /admin/settings s’affiche sans erreur

Rollback

Si le démarrage échoue ou si le smoke test révèle une régression :

1. Arrêter le service

sudo systemctl stop gitrust

2. Restaurer le binaire précédent

Si vous avez conservé l’ancien binaire (bonne pratique : le renommer avant la mise à jour) :

sudo cp /opt/gitrust/gitrust.backup /opt/gitrust/gitrust
sudo chown gitrust:gitrust /opt/gitrust/gitrust

3. Restaurer la base de données si des migrations ont été appliquées

# Identifier la dernière sauvegarde pré-mise-à-jour
DUMP=$(ls -t /var/backups/gitrust/pg-*.dump | head -1)
echo "Restauration depuis : $DUMP"

sudo -u postgres psql -c "DROP DATABASE IF EXISTS gitrust;"
sudo -u postgres psql -c "CREATE DATABASE gitrust OWNER gitrust;"

pg_restore -h localhost -U gitrust --dbname=gitrust "$DUMP"

4. Redémarrer avec l’ancienne version

sudo systemctl start gitrust

Attention : si des nouvelles migrations ont créé ou modifié des tables, le rollback de la base est indispensable avant de démarrer l’ancienne version. Un binaire ancien sur une base migratée peut produire des erreurs imprévisibles.

Conseils

• Conservez toujours le binaire précédent pendant 24 h avant de le supprimer (mv gitrust gitrust.backup).
• Planifiez les mises à jour en dehors des heures de pointe (le service est arrêté pendant l’opération).
• Les migrations sont idempotentes : redémarrer deux fois de suite avec la même version est sans risque.

Pour aller plus loin

• Sauvegarder et restaurer
• Variables d’environnement

Configurer l’envoi d’e-mails (SMTP)

À qui s’adresse cette page

Administrateurs qui souhaitent activer l’envoi d’e-mails (validation de compte, réinitialisation de mot de passe, notifications). Sans configuration SMTP, gitrust démarre normalement mais toutes les fonctionnalités e-mail sont désactivées.

Variables concernées

Toutes ces variables se placent dans /opt/gitrust/.env (ou dans l’EnvironmentFile de votre service systemd / docker-compose.yml). Un redémarrage du service est nécessaire après modification.

Important : Ne jamais activer SMTP_ACCEPT_INVALID_CERTS=true en production — cela ouvre la voie à des attaques MITM sur tous les e-mails sortants.

Recettes par prestataire

Gmail (compte personnel ou Google Workspace)

Google exige un mot de passe applicatif (pas votre mot de passe Google). Générez-le sur myaccount.google.com/apppasswords en activant au préalable la validation en deux étapes.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=votre.adresse@gmail.com
SMTP_PASSWORD=xxxx_xxxx_xxxx_xxxx   # mot de passe applicatif (16 caractères)
SMTP_FROM=votre.adresse@gmail.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=true
EMAIL_BASE_URL=https://VOTRE_DOMAINE

Limite : Gmail impose un quota de 500 e-mails/jour pour les comptes personnels. Pour les volumes importants, utilisez un service dédié (SendGrid, Brevo, etc.).

OVH / Infomaniak / Gandi

Ces hébergeurs utilisent STARTTLS sur le port 587 ou SMTPS sur le port 465.

# OVH (SSL/TLS natif sur 465)
SMTP_HOST=ssl0.ovh.net
SMTP_PORT=465
SMTP_USER=noreply@VOTRE_DOMAINE.com
SMTP_PASSWORD=MOT_DE_PASSE_EMAIL
SMTP_FROM=noreply@VOTRE_DOMAINE.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=true
SMTP_USE_STARTTLS=false
EMAIL_BASE_URL=https://VOTRE_DOMAINE

# Gandi (STARTTLS sur 587)
SMTP_HOST=mail.gandi.net
SMTP_PORT=587
SMTP_USER=noreply@VOTRE_DOMAINE.com
SMTP_PASSWORD=MOT_DE_PASSE_EMAIL
SMTP_FROM=noreply@VOTRE_DOMAINE.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=true
EMAIL_BASE_URL=https://VOTRE_DOMAINE

Postfix local (instance interne sans authentification)

Pour les déploiements sur réseau interne où Postfix est installé sur le même serveur :

SMTP_HOST=127.0.0.1
SMTP_PORT=25
# Pas de SMTP_USER ni SMTP_PASSWORD si Postfix accepte sans auth sur loopback
SMTP_FROM=noreply@VOTRE_DOMAINE.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=false
EMAIL_BASE_URL=https://VOTRE_DOMAINE

Vérifiez que Postfix accepte les connexions depuis 127.0.0.1 :

# Dans /etc/postfix/main.cf
mynetworks = 127.0.0.0/8

Mailpit / Mailhog (développement local)

SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM=dev@localhost
SMTP_FROM_NAME=Gitrust-Dev
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=false
SMTP_ACCEPT_INVALID_CERTS=false
EMAIL_BASE_URL=http://localhost:4000
EMAIL_VALIDATION_REQUIRED=false

Démarrez Mailpit : docker run -p 1025:1025 -p 8025:8025 axllent/mailpit
Interface web : http://localhost:8025

Tester la configuration

Après avoir modifié le .env et redémarré gitrust, testez via le panel admin :

1. Connectez-vous à /admin
2. Accédez à /admin/email
3. Saisissez une adresse de test et cliquez Envoyer un e-mail de test

En cas d’erreur, consultez les logs :

sudo journalctl -u gitrust -n 50 --no-pager | grep -i "smtp\|email\|mail"

Erreurs courantes :

Pour aller plus loin

• Variables d’environnement — section Email
• Auditer l’instance — vérifier les bounces et la file d’envoi

Configurer l’authentification OAuth (Google, GitHub, Discord, Microsoft)

À qui s’adresse cette page

Administrateurs qui souhaitent permettre à leurs utilisateurs de se connecter via un fournisseur OAuth externe plutôt que (ou en plus de) le couple identifiant/mot de passe local.

Principe

OAuth est le seul sous-système hybride de gitrust : la configuration peut venir soit de la base de données (via /admin/settings), soit du fichier .env en fallback. La priorité est toujours à la base de données.

flowchart LR
    A[OAuthConfig::load au démarrage] --> B{Valeur en DB ?}
    B -->|Oui| C[Utiliser valeur DB]
    B -->|Non| D[Fallback .env]
    D --> E[Valeur codée en dur si absent]
    C --> F[OAuthConfig en mémoire]
    E --> F
    F --> G[Arc — non rechargé à chaud]

Conséquence : toute modification de la configuration OAuth (via l’UI ou via .env) nécessite un redémarrage pour être prise en compte.

Méthode recommandée : via l’interface /admin/settings

C’est la méthode la plus simple. Les secrets sont chiffrés en base (AES-256-GCM).

1. Connectez-vous à /admin/settings
2. Activez le toggle OAuth / SSO activé
3. Renseignez l’URL de base des callbacks (ex. https://gitrust.votre-domaine.com)
4. Pour chaque fournisseur souhaité, activez le toggle et renseignez Client ID et Client Secret
5. Cliquez Enregistrer
6. Redémarrez le service : sudo systemctl restart gitrust

Méthode alternative : via les variables .env

Utile pour le provisionnement automatisé (Ansible, cloud-init) ou pour définir les valeurs au premier démarrage.

# Activation globale
OAUTH_ENABLED=true
OAUTH_REDIRECT_BASE_URL=https://gitrust.votre-domaine.com

# Clé de chiffrement des secrets OAuth en base (AES-256-GCM)
# Générer avec : openssl rand -hex 32
OAUTH_ENCRYPTION_KEY=REMPLACER_PAR_32_BYTES_HEX

Ces variables ne s’appliquent qu’en l’absence de valeur en base de données.

Configurer Google OAuth

1. Créer les identifiants dans Google Cloud Console

1. Ouvrez console.cloud.google.com → APIs & Services → Credentials
2. Cliquez Create Credentials → OAuth 2.0 Client ID
3. Type : Web application
4. Ajoutez l’URI de redirection autorisée :

   https://gitrust.votre-domaine.com/api/v1/auth/oauth/google/callback
   

5. Notez le Client ID et le Client Secret

2. Configurer dans gitrust

Via .env :

OAUTH_GOOGLE_ENABLED=true
OAUTH_GOOGLE_CLIENT_ID=123456789-xxxxxxxxxxxx.apps.googleusercontent.com
OAUTH_GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx

Via /admin/settings : activez « Google » et renseignez les mêmes valeurs.

Scopes utilisés : openid, email, profile (read-only, pas d’accès au compte Google).

Configurer GitHub OAuth

1. Créer l’application OAuth sur GitHub

1. Ouvrez github.com/settings/developers → OAuth Apps → New OAuth App
2. Authorization callback URL :

   https://gitrust.votre-domaine.com/api/v1/auth/oauth/github/callback
   

3. Notez le Client ID et générez un Client Secret

2. Configurer dans gitrust

OAUTH_GITHUB_ENABLED=true
OAUTH_GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
OAUTH_GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes utilisés : read:user, user:email.

Configurer Discord OAuth

1. Créer l’application sur Discord Developer Portal

1. Ouvrez discord.com/developers/applications → New Application
2. Onglet OAuth2 → Redirects → ajoutez :

   https://gitrust.votre-domaine.com/api/v1/auth/oauth/discord/callback
   

3. Notez le Client ID et le Client Secret

2. Configurer dans gitrust

OAUTH_DISCORD_ENABLED=true
OAUTH_DISCORD_CLIENT_ID=123456789012345678
OAUTH_DISCORD_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Configurer Microsoft / Azure AD

1. Créer l’application dans Azure

1. Ouvrez portal.azure.com → Azure Active Directory → App registrations → New registration
2. Redirect URI (Web) :

   https://gitrust.votre-domaine.com/api/v1/auth/oauth/microsoft/callback
   

3. Notez le Application (client) ID et créez un Client Secret dans Certificates & Secrets

2. Configurer dans gitrust

OAUTH_MICROSOFT_ENABLED=true
OAUTH_MICROSOFT_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
OAUTH_MICROSOFT_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# "common" = comptes personnels et professionnels
# Remplacer par le GUID du tenant pour restreindre à votre organisation
OAUTH_MICROSOFT_TENANT=common

Comportement lors de la connexion OAuth

Ces comportements sont configurables dans /admin/settings (paramètres oauth_auto_register et oauth_link_existing_account).

Vérification après activation

# Redémarrer le service
sudo systemctl restart gitrust

# Vérifier les logs de démarrage
sudo journalctl -u gitrust -n 30 --no-pager | grep -i oauth

Ouvrez une fenêtre de navigation privée et accédez à /login : les boutons OAuth activés doivent apparaître sous le formulaire classique.

Pour aller plus loin

• Variables d’environnement — section OAuth
• Paramètres dynamiques /admin/settings

Configurer le runner CI distant

Guide d’usage du script qui provisionne une machine distante pour exécuter les pipelines CI/CD de gitrust via SSH + rsync + Dagger.

1. Rôle du script

deployment/setup-remote-ci.sh (disponible dans le dépôt source gitrust) prépare un serveur de build distant utilisé par le worker CI de gitrust. Il automatise 6 étapes :

1. Vérifie la connectivité SSH vers le runner
2. Installe Docker (curl https://get.docker.com | sh) s’il est absent
3. Installe Dagger CLI (curl https://dl.dagger.io/dagger/install.sh | sh) s’il est absent
4. Crée le répertoire de travail distant (CI_REMOTE_PATH)
5. Synchronise le module deployment/ci-engine/ (mode CI Easy) via rsync -az --delete
6. Smoke test : affiche docker --version et dagger version

Le script est idempotent : rejoue sans dommage, skip ce qui existe déjà.

2. Quand l’utiliser

3. Architecture cible

+---------------------+        SSH + rsync        +-----------------------+
|  Gitrust (web+SSH)  |---------------------------|  CI Runner (distant)  |
|  <your-server-ip>   |  CI_REMOTE_HOST/USER/KEY  |  <ci-runner-ip>       |
|                     |                           |                       |
|  Worker CI Tokio    |   push .gitrust-ci.yml    |  /opt/gitrust-ci/     |
|  (dans gitrust.bin) |   + code source checkout  |   ├── ci-engine/      |
|                     |                           |   └── workspaces/     |
|                     |   dagger call ...         |                       |
|                     |                           |  Docker + Dagger CLI  |
+---------------------+                           +-----------------------+

Le worker CI de gitrust (tâche Tokio dans le binaire principal) ne fait pas tourner Docker localement — il délègue au runner via SSH. Cela permet d’isoler les workloads CPU/RAM gourmands (builds Rust, Node, Docker) du process web de gitrust.

4. Pré-requis

Sur la machine d’exécution (là où on lance le script)

Sur le runner distant

5. Variables d’environnement attendues (le .env)

Le script source un fichier .env dont le chemin est passé en argument, ou par défaut ../.env (relatif au script, donc <racine_projet>/.env).

Tableau des variables

Ces variables sont les mêmes que celles lues par gitrust au runtime. Centraliser dans .env évite les divergences entre le provisionnement et le runtime.

Exemple minimal de .env (runner dédié)

# --- CI runner distant ---
CI_REMOTE_HOST=<ci-runner-ip>
CI_REMOTE_USER=ci-runner
CI_REMOTE_SSH_PORT=22
CI_REMOTE_PATH=/opt/gitrust-ci
CI_REMOTE_SSH_KEY=/home/gitrust/.ssh/ci_runner_ed25519

Exemple .env complet coexistant avec config gitrust

DATABASE_URL=postgres://...
JWT_SECRET=...
# ... (voir .env.example pour le reste)

# --- CI/CD (lu par gitrust ET par setup-remote-ci.sh) ---
CI_ENABLED=true
CI_MAX_CONCURRENT=4
CI_REMOTE_HOST=ci-runner.internal
CI_REMOTE_USER=ci-runner
CI_REMOTE_PATH=/opt/gitrust-ci
CI_REMOTE_SSH_KEY=/opt/gitrust/data/ci_runner_key

Cas « runner local » (pas besoin du script)

CI_REMOTE_HOST=localhost
# Les autres CI_REMOTE_* sont ignorés

Dans ce cas, installer Docker et Dagger directement sur la machine gitrust, copier deployment/ci-engine/ vers CI_ENGINE_PATH (défaut /opt/gitrust/ci-engine) et passer à la suite. Ne pas exécuter setup-remote-ci.sh avec CI_REMOTE_HOST=localhost.

6. Usage

Depuis la racine du projet (par défaut)

cd /chemin/vers/gitrust

# .env a la racine (défaut) :
./deployment/setup-remote-ci.sh

Avec un .env explicite

./deployment/setup-remote-ci.sh /chemin/vers/mon.env
# Utile si vous avez .env.production, .env.staging, etc.
./deployment/setup-remote-ci.sh .env.production

Sortie attendue

==> Configuration :
    Serveur  : ci-runner@<ci-runner-ip>
    Port SSH : 22
    Chemin   : /opt/gitrust-ci

==> [1/6] Vérification de la connectivité SSH...
SSH OK
    OK
==> [2/6] Vérification de Docker...
    Docker déjà installé
==> [3/6] Vérification de Dagger CLI...
    Installation de Dagger CLI...
    Dagger installé
==> [4/6] Création du répertoire distant...
    /opt/gitrust-ci créé
==> [5/6] Synchronisation du ci-engine...
sending incremental file list
ci-engine/
ci-engine/profiles/
...
    ci-engine synchronisé vers /opt/gitrust-ci/ci-engine/
==> [6/6] Smoke test...
    Versions distantes :
Docker version 28.0.1, build abcd123
dagger v0.19.2 (linux/amd64)

==> Setup terminé. Le serveur ci-runner@<ci-runner-ip> est prêt pour l'exécution CI.
    Pensez à configurer CI_EXECUTION_MODE=remote dans votre .env

7. Ce qui se retrouve sur le runner

Après exécution réussie :

/opt/gitrust-ci/                    <- CI_REMOTE_PATH
└── ci-engine/                      <- synchronisé depuis deployment/ci-engine/
    ├── README.md
    └── profiles/                   <- templates par stack (Python, Node, Rust, ...)

Plus, installés globalement :

• /usr/bin/docker (ou équivalent) + socket /var/run/docker.sock
• /usr/local/bin/dagger

Les workspaces de pipelines (checkouts temporaires) sont créés par le worker CI de gitrust au moment de l’exécution sous CI_WORKSPACE_PATH (défaut /tmp/gitrust-ci) — pas par ce script.

8. Vérifications post-setup

Depuis la machine gitrust

# Source le .env
set -a; source .env.production; set +a

# 1. SSH direct (doit passer sans prompt)
ssh -p ${CI_REMOTE_SSH_PORT:-22} \
    ${CI_REMOTE_SSH_KEY:+-i $CI_REMOTE_SSH_KEY} \
    $CI_REMOTE_USER@$CI_REMOTE_HOST 'docker info && dagger version'

# 2. Rsync round-trip (lecture/écriture sur CI_REMOTE_PATH)
echo "test" | ssh $CI_REMOTE_USER@$CI_REMOTE_HOST \
    "cat > $CI_REMOTE_PATH/.gitrust-test && cat $CI_REMOTE_PATH/.gitrust-test && rm $CI_REMOTE_PATH/.gitrust-test"
# Attendu : "test"

Pipeline de test via gitrust

Pousser un dépôt avec un .gitrust-ci.yml minimal :

# .gitrust-ci.yml
version: 1
pipeline:
  - name: smoke
    image: alpine:3
    run: echo "CI runner OK"

Puis dans l’UI gitrust : onglet Pipelines → la pipeline doit passer au statut success.

9. Mise à jour après modification du ci-engine/

Le ci-engine/ synchronisé n’est pas « live-linké » : rejouer le script après modification côté source.

# Modifier deployment/ci-engine/profiles/*.py ou similaire
./deployment/setup-remote-ci.sh
# Les étapes 2-3 sont skip (déjà installés), seule l'étape 5 refait le rsync

rsync -az --delete supprime les fichiers côté runner qui n’existent plus localement — garantit la cohérence.

10. Dépannage

11. Sécurité

• Le runner CI exécute du code arbitraire venant des dépôts hébergés. Ne jamais le colocaliser avec des secrets sensibles (PG prod, clés de prod).
• Isoler réseau : bloquer l’accès sortant du runner vers le LAN privé (seul l’accès Internet pour docker pull est nécessaire).
• Limiter sudo NOPASSWD au strict minimum sur le runner (idéalement : juste pour les commandes docker et apt).
• Rotation régulière de la clé SSH CI_REMOTE_SSH_KEY. La révoquer dans ~/.ssh/authorized_keys côté runner en cas de suspicion.
• Le runner ne doit pas pouvoir se connecter en SSH à la machine gitrust (unidirectionnel).

Intégrer la CI et Dependency-Track

Ce document explique comment activer et configurer les deux fonctionnalités de qualité/sécurité de gitrust :

1. La CI intégrée (Dagger) qui exécute les builds/tests/lints à chaque push.
2. Le dependency tracker (Syft + Dependency-Track) qui scanne les composants du code à chaque push et détecte les vulnérabilités connues.

Ces deux systèmes sont indépendants : on peut activer l’un sans l’autre.

1. Architecture générale

flowchart TB
  subgraph Client
    Dev[Développeur]
  end
  subgraph Gitrust[Instance Gitrust]
    HTTP[:4000 HTTP/Git]
    SSH[:2222 SSH/Git]
    Worker[CiWorker<br/>tokio task]
    Sbom[SbomService<br/>tokio spawn]
    DB[(PostgreSQL)]
  end
  subgraph Builder[Serveur de build]
    Docker[Docker/Podman]
    Dagger[Dagger CLI]
    CiEngine[/opt/gitrust-ci/ci-engine/]
  end
  subgraph Security[Stack sécurité optionnelle]
    Syft[syft]
    Dtrack[Dependency-Track]
  end

  Dev -->|git push| HTTP
  Dev -->|git push| SSH
  HTTP --> Worker
  SSH --> Worker
  HTTP --> Sbom
  SSH --> Sbom
  Worker -->|SSH + rsync| Builder
  Builder -->|logs streamés| Worker
  Worker --> DB
  Sbom -->|scan workspace| Syft
  Sbom -->|PUT BOM| Dtrack
  Dtrack -->|findings| Sbom
  Sbom --> DB

Trois composants fonctionnent en parallèle :

• CiWorker : tâche Tokio qui consomme des CiTask depuis un channel mpsc, limitée par un Semaphore à CI_MAX_CONCURRENT pipelines simultanés.
• SbomService : exécuté dans un tokio::spawn après chaque push, totalement découplé du CI.
• Serveur de build : machine distante (ou localhost) qui exécute Docker + Dagger. Gitrust y envoie le workspace par rsync et lance Dagger par SSH.

2. Mettre en place la CI

2.1 Pré-requis serveur de build

Le serveur de build peut être la même machine que Gitrust (CI_REMOTE_HOST=localhost) ou une machine dédiée. Il doit disposer de :

Installation automatique recommandée :

# Depuis la machine Gitrust (l'utilisateur doit pouvoir SSH vers le builder)
./deployment/setup-remote-ci.sh .env

Le script exécute :

1. Vérification de la connectivité SSH
2. Installation de Docker si absent
3. Installation de Dagger CLI si absent
4. Création du répertoire de travail distant
5. Synchronisation du ci-engine
6. Smoke test (versions)

2.2 Configuration Gitrust (fichier .env)

Ajouter au .env de Gitrust :

# Activer globalement le CI
CI_ENABLED=true

# Chemin du ci-engine sur le serveur de build
CI_ENGINE_PATH=/opt/gitrust-ci/ci-engine

# Limite de parallélisme
CI_MAX_CONCURRENT=4
CI_DEFAULT_TIMEOUT=3600
CI_WORKSPACE_PATH=/tmp/gitrust-ci

# Serveur de build (mettre localhost pour "même machine")
CI_REMOTE_HOST=builder.example.com
CI_REMOTE_USER=ci-runner
CI_REMOTE_PATH=/opt/gitrust-ci
CI_REMOTE_SSH_PORT=22
# CI_REMOTE_SSH_KEY=/home/gitrust/.ssh/id_ed25519   # si pas ssh-agent

Redémarrer Gitrust : systemctl restart gitrust (ou cargo run --release).

2.3 Activer la CI sur un dépôt

Dans l’interface web : aller sur le dépôt → Settings → CI.

• Cocher CI enabled (requis — par défaut false)
• Cocher Trigger on push (active l’exécution à chaque push)
• Optionnel : Auto-cancel (annule les pipelines en cours quand un nouveau démarre)
• Optionnel : Allowed branches (ex. main,develop — vide = toutes)

2.4 Choisir le mode : Easy ou Power

flowchart LR
  Push[Commit<br/>poussé] --> Tree{Arbre du<br/>commit contient ?}
  Tree -->|.dagger/| Power[Mode Power<br/>dagger call -m .dagger/ ci]
  Tree -->|.gitrust-ci.yml| Easy[Mode Easy<br/>dagger call -m ci-engine test-pr]
  Tree -->|rien| None[Pas de pipeline]
  Power --> Run[Exécution<br/>distante SSH]
  Easy --> Run

Mode Easy (recommandé pour commencer)

Créer .gitrust-ci.yml à la racine du dépôt :

# Raccourci : charge un profil pré-configuré (rust | python | node)
language: rust

build:
  command: "cargo build --release"

checks:
  lint: "cargo clippy -- -D warnings"
  format: "cargo fmt -- --check"

tests:
  command: "cargo test --release"

Les profils disponibles se trouvent dans deployment/ci-engine/profiles/ (rust.yaml, python.yaml, node.yaml) dans le dépôt source.

Mode Power

Pour les utilisateurs avancés, créer un module Dagger complet dans .dagger/ :

.dagger/
├── dagger.json
├── src/
│   └── main.py         # ou Go/TypeScript

La fonction ci du module est appelée directement :

dagger call -m .dagger/ ci

Avantage : accès au Daggerverse, composition, tests de pipeline. Voir la documentation Dagger.

2.5 Suivi d’un pipeline

Après un git push, une entrée apparaît dans l’onglet CI du dépôt :

stateDiagram-v2
  [*] --> Pending: create_pipeline
  Pending --> Running: worker picks CiTask
  Running --> Success: exit 0
  Running --> Failure: exit != 0
  Running --> Cancelled: timeout / auto_cancel / manuel
  Success --> [*]
  Failure --> [*]
  Cancelled --> [*]

Les logs stdout/stderr sont streamés ligne par ligne dans la table ci_logs et visibles en direct dans l’UI. En cas d’échec, une notification est envoyée au propriétaire du dépôt.

3. Mettre en place le Dependency Tracker

Cette partie est totalement indépendante de la CI. Elle scanne le code poussé et produit un SBOM CycloneDX, puis (optionnellement) l’envoie à Dependency-Track pour une analyse de vulnérabilités.

3.1 Installer Syft

Sur la machine Gitrust (le scan se fait localement, pas sur le builder) :

# Installation officielle
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh \
  | sh -s -- -b /usr/local/bin

# Vérification
syft --version

Dans .env :

CI_SBOM_ENABLED=true
CI_SYFT_BIN=/usr/local/bin/syft   # optionnel, défaut: syft dans PATH

À ce stade : à chaque push, un SBOM CycloneDX est généré et stocké (sans upload externe). Visible dans l’onglet Security du dépôt : nombre de composants, sha256 du BOM.

3.2 Déployer Dependency-Track

Dependency-Track est une application Java qui stocke les SBOM et corrèle avec les bases CVE/OSV/NVD. Déploiement Docker recommandé :

mkdir -p /opt/dtrack && cd /opt/dtrack
curl -L -o docker-compose.yml \
  https://dependencytrack.org/docker-compose.yml
docker compose up -d

L’API est disponible sur http://localhost:8081 et l’UI sur http://localhost:8080. Login initial : admin / admin (à changer immédiatement).

3.3 Créer une clé API

Dans Dependency-Track → Administration → Access Management → Teams :

1. Créer (ou réutiliser) une équipe gitrust.
2. Lui attribuer les permissions :
   • BOM_UPLOAD
   • PROJECT_CREATION_UPLOAD
   • VIEW_PORTFOLIO
   • VIEW_VULNERABILITY
3. Générer une API key et la copier.

3.4 Configurer Gitrust

Ajouter au .env :

CI_DTRACK_ENABLED=true
CI_DTRACK_URL=http://localhost:8081
CI_DTRACK_API_KEY=odt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Redémarrer Gitrust. À chaque push :

sequenceDiagram
  participant Push as post-receive
  participant Sbom as SbomService
  participant Git as git archive
  participant Syft
  participant Dtrack as Dependency-Track
  participant DB as sbom_reports

  Push->>Sbom: process_push(sha, ref)
  Sbom->>DB: upsert status=pending
  Sbom->>Git: archive sha | tar -x tmpdir
  Sbom->>Syft: scan dir:tmpdir -o cyclonedx-json
  Syft-->>Sbom: BOM bytes
  Sbom->>DB: update sha256
  Sbom->>Dtrack: PUT /api/v1/bom (base64)
  Dtrack-->>Sbom: token
  loop max 30s
    Sbom->>Dtrack: GET /api/v1/bom/token/{token}
    Dtrack-->>Sbom: processing ?
  end
  Sbom->>Dtrack: GET /api/v1/finding/project/{uuid}
  Dtrack-->>Sbom: findings[]
  Sbom->>DB: update status=success<br/>+ critical/high/medium/low

3.5 Lire les résultats

Onglet Security du dépôt → encart SBOM :

• Nombre de composants détectés
• Compteurs par sévérité : Critical / High / Medium / Low
• Lien direct vers le projet dans Dependency-Track (si l’UUID est résolu)
• Hash sha256 du BOM (traçabilité)

Si Dependency-Track met plus de 30s à analyser, le status reste processing — un sweeper ultérieur ira rechercher les findings.

4. Débogage

Problèmes CI courants

Problèmes SBOM courants

Logs utiles

# Logs Gitrust (systemd)
journalctl -u gitrust -f | grep -E "CI|SBOM|sbom|pipeline"

# Vérifier un pipeline en DB
psql $DATABASE_URL -c "SELECT id, status, commit_sha, created_at FROM ci_pipelines ORDER BY created_at DESC LIMIT 10;"

# Vérifier un SBOM
psql $DATABASE_URL -c "SELECT commit_sha, status, components_count, critical_count, high_count FROM sbom_reports ORDER BY created_at DESC LIMIT 10;"

5. Checklist récapitulative

CI :

• Docker + Dagger installés sur le serveur de build (setup-remote-ci.sh)
• CI_ENABLED=true et CI_REMOTE_* dans .env
• Gitrust redémarré
• CI activée dans Settings → CI pour chaque dépôt
• Fichier .gitrust-ci.yml (Easy) ou .dagger/ (Power) commité
• Push → pipeline visible dans l’onglet CI

Dependency Tracker :

• Syft installé sur la machine Gitrust
• CI_SBOM_ENABLED=true dans .env
• (Optionnel) Dependency-Track déployé + API key créée avec les 4 permissions
• (Optionnel) CI_DTRACK_ENABLED=true, CI_DTRACK_URL, CI_DTRACK_API_KEY dans .env
• Gitrust redémarré
• Push → SBOM visible dans l’onglet Security

Configurer ssh-guard (durcissement SSH)

À qui s’adresse cette page

Administrateurs qui déploient ou ajustent la couche ssh-guard de gitrust selon leur topologie réseau (Internet direct, derrière nginx stream, derrière HAProxy, ou réseau privé).

Avant de commencer : si vous voulez d’abord comprendre ce que fait ssh-guard et ses compromis, lisez ssh-guard : détection d’attaques SSH. La référence des variables est dans Variables d’environnement — SSH_GUARD_*.

1. Choisir le profil de déploiement

Le profil pré-configure les défauts cohérents avec votre topologie. Une variable unique pilote tout le reste : SSH_GUARD_PROFILE.

Le défaut au démarrage si SSH_GUARD_PROFILE n’est pas défini est custom, qui équivaut au profil direct côté détecteurs mais avec PROXY protocol désactivé.

2. Recette : profil direct (Internet direct)

Cas typique : VPS, pas de reverse-proxy SSH devant gitrust. Le port :2222 est ouvert sur Internet et peer_addr() est l’IP réelle du client.

2.1 .env minimal

Copiez template/env/ssh-guard-direct.env dans votre /opt/gitrust/.env ou ajoutez :

SSH_GUARD_ENABLED=true
SSH_GUARD_DRY_RUN=false
SSH_GUARD_PROFILE=direct

# Stockage hybride (RAM chaude + write-through PostgreSQL)
SSH_GUARD_STORE_BACKEND=hybrid

# Logs JSON dans journald + fichier dédié pour fail2ban
SSH_GUARD_LOG_FORMAT=json
SSH_GUARD_LOG_TARGET=both
SSH_GUARD_LOG_FILE=/var/log/gitrust-ssh-guard.json

Les seuils par défaut s’appliquent : brute-force 5/5min, énumération 10/5min, scan de clés 10/5min, flood 10/s burst 20, ban 1 h.

2.2 Redémarrage et vérification

sudo systemctl restart gitrust

# Le module annonce sa configuration au démarrage
sudo journalctl -u gitrust --since "1 min ago" | grep "SSH guard runtime assembly"
# Attendu : profile=direct enabled=true dry_run=false store=Hybrid

# Logrotate sur le fichier dédié
sudo tee /etc/logrotate.d/gitrust-ssh-guard <<'EOF'
/var/log/gitrust-ssh-guard.json {
    daily
    rotate 14
    missingok
    notifempty
    compress
    delaycompress
    copytruncate
}
EOF

3. Recette : profil nginx (derrière nginx stream)

Cas typique : nginx termine TLS sur :443, fait du SSH stream sur :22 → 127.0.0.1:2222 avec PROXY protocol v2.

3.1 nginx (rappel — voir aussi Durcir avec Fail2ban)

# /etc/nginx/nginx.conf (bloc stream)
stream {
    upstream gitrust_ssh {
        server 127.0.0.1:2222;
    }

    server {
        listen 22;
        proxy_pass         gitrust_ssh;
        proxy_protocol     on;       # IMPORTANT — sinon ssh-guard rejettera
        proxy_timeout      30m;      # git push de gros pack peut être long
    }
}

3.2 .env côté gitrust

Copiez template/env/ssh-guard-nginx.env ou :

SSH_GUARD_ENABLED=true
SSH_GUARD_PROFILE=nginx

# Le profil nginx pose déjà :
#   SSH_GUARD_PROXY_PROTOCOL=v2
#   SSH_GUARD_PROXY_PROTOCOL_STRICT=true
#   SSH_GUARD_TRUSTED_PROXIES=127.0.0.1/32,::1/128
# (override individuel possible)

SSH_GUARD_LOG_FORMAT=json
SSH_GUARD_LOG_TARGET=both
SSH_GUARD_LOG_FILE=/var/log/gitrust-ssh-guard.json

Côté binding gitrust :

SSH_LISTEN_ADDR=127.0.0.1
SSH_PORT=2222

3.3 Vérification que la vraie IP est bien extraite

Faites un git ls-remote ssh://git@VOTRE_FQDN/owner/repo.git depuis une IP externe connue, puis :

sudo journalctl -u gitrust --since "1 min ago" | grep '"event":"connection_accepted"' | tail -1
# Attendu : "ip":"<VOTRE IP EXTERNE>"   et NON "ip":"127.0.0.1"

Si vous voyez 127.0.0.1, c’est que le PROXY protocol n’est pas correctement transmis : vérifiez proxy_protocol on; dans nginx.

4. Recette : profil haproxy

Le profil pose SSH_GUARD_PROXY_PROTOCOL=any (auto-détection v1 ou v2) avec strict=true, mais n’a pas de trusted_proxies par défaut (HAProxy est presque toujours sur une IP distincte). À fournir explicitement :

SSH_GUARD_ENABLED=true
SSH_GUARD_PROFILE=haproxy
SSH_GUARD_TRUSTED_PROXIES=10.0.0.5/32   # IP de l'haproxy

SSH_GUARD_LOG_FORMAT=json
SSH_GUARD_LOG_TARGET=both
SSH_GUARD_LOG_FILE=/var/log/gitrust-ssh-guard.json

Si SSH_GUARD_TRUSTED_PROXIES est vide, gitrust refuse de démarrer avec l’erreur :

SSH_GUARD_TRUSTED_PROXIES required when SSH_GUARD_PROXY_PROTOCOL is enabled

C’est volontaire : sans cette protection, n’importe qui pourrait forger un en-tête PROXY pour usurper une IP cliente.

5. Recette : profil private (réseau interne)

Détecteurs désactivés (seuils u32::MAX), événements toujours émis pour audit, store en mémoire (rapide, perdu au restart).

SSH_GUARD_ENABLED=true
SSH_GUARD_PROFILE=private

# Tous les détecteurs sont désactivés par le preset.
# Les événements connection_accepted / auth_failed / auth_succeeded
# restent émis pour audit.

SSH_GUARD_LOG_FORMAT=json
SSH_GUARD_LOG_TARGET=stderr   # journald uniquement, pas de fichier

6. Mode dry-run : observer avant de bloquer

Idéal pour valider un nouveau seuil ou laisser fail2ban faire le ban réel :

SSH_GUARD_DRY_RUN=true

Effets :

• Les détecteurs continuent à corréler.
• Un événement ip_banned est émis pour chaque déclenchement (signal pour fail2ban / Loki).
• Aucun ban n’est persisté côté ssh-guard. Le BanManager reste no-op.

C’est le mode recommandé pendant les premiers jours après un changement de seuil agressif. Surveillez :

sudo journalctl -u gitrust --since "24 hours ago" --no-pager \
  | grep '"event":"ip_banned"' \
  | jq -r '.ip + " " + .reason' \
  | sort | uniq -c | sort -rn

7. Ajuster les seuils

7.1 Variables disponibles

# Brute-force : nombre d'échecs auth depuis une IP dans la fenêtre
SSH_GUARD_BRUTE_FORCE_THRESHOLD=5         # défaut 5
SSH_GUARD_BRUTE_FORCE_WINDOW_SECS=300     # défaut 300 (5 min)

# Énumération : nombre d'usernames distincts essayés depuis une IP
SSH_GUARD_USER_ENUM_THRESHOLD=10
SSH_GUARD_USER_ENUM_WINDOW_SECS=300

# Scan de clés : nombre de fingerprints distincts essayés depuis une IP
SSH_GUARD_KEY_SCAN_THRESHOLD=10
SSH_GUARD_KEY_SCAN_WINDOW_SECS=300

# Flood TCP : cap dur de connexions par seconde par IP
SSH_GUARD_CONN_FLOOD_PER_SEC=10
SSH_GUARD_CONN_FLOOD_BURST=20

# Durée d'un ban auto. 0 = permanent.
SSH_GUARD_AUTO_BAN_DURATION_SECS=3600     # défaut 3600 (1 h)

7.2 Profils suggérés

Désactiver complètement un détecteur : mettre son seuil à 4294967295 (u32::MAX). Le préfixe private le fait déjà pour les quatre.

8. Allowlist d’un partenaire CI

Une IP allowlistée bypasse les détecteurs et le flood-limit, mais reste auditée. Les ACL se gèrent via la table ssh_guard_acl (admin UI ou SQL direct).

-- Allow le runner CI de l'équipe build (CIDR /32)
INSERT INTO ssh_guard_acl (id, kind, ip_cidr, reason, created_by, created_at, updated_at)
VALUES (
  gen_random_uuid(),
  'allow',
  '198.51.100.42/32',
  'Runner CI équipe build (ticket OPS-1234)',
  '<UUID admin>',
  NOW(), NOW()
);

Vérifier : depuis cette IP, déclencher 50 tentatives ratées en 1 minute, puis vérifier qu’aucun ip_banned n’a été émis :

sudo journalctl -u gitrust --since "5 min ago" --no-pager \
  | grep '"ip":"198.51.100.42"' \
  | jq -r '.event' | sort | uniq -c
# Attendu : auth_failed: 50, brute_force_detected: 0, ip_banned: 0

9. Bannir manuellement un CIDR abusif

Pour un AS qui scanne en masse, posez un ban permanent :

-- Denylist permanente d'un CIDR
INSERT INTO ssh_guard_bans (id, ip_cidr, reason, banned_at, expires_at, auto_banned)
VALUES (
  gen_random_uuid(),
  '198.51.100.0/24',
  'admin_deny_list',
  NOW(),
  NULL,         -- NULL = permanent
  false
);

expires_at = NULL rend le ban permanent. Pour un TTL fini : NOW() + INTERVAL '7 days'.

10. Troubleshooting

10.1 Tous les ip valent 127.0.0.1

Vous êtes en profil direct mais nginx fait du stream devant gitrust. Passez en nginx et activez proxy_protocol on; dans nginx.

10.2 « SSH_GUARD_TRUSTED_PROXIES required »

Vous avez activé le profil haproxy (ou SSH_GUARD_PROXY_PROTOCOL=v1|v2|any) sans déclarer de proxies de confiance. Ajoutez SSH_GUARD_TRUSTED_PROXIES=<CIDR> et redémarrez.

10.3 Faux positifs sur un développeur avec 8 clés SSH

L’agent SSH du dev présente toutes ses clés successivement. Si la 9e est la bonne, le détecteur de scan de clés pourrait s’activer (seuil 10 par défaut). Solutions, par ordre de préférence :

1. Côté dev : forcer une clé spécifique avec IdentitiesOnly yes dans ~/.ssh/config.
2. Côté admin : monter le seuil à 15 (SSH_GUARD_KEY_SCAN_THRESHOLD=15).

10.4 Lever un ban auto sans attendre l’expiration

UPDATE ssh_guard_bans
SET unbanned_at = NOW(), unbanned_by = '<UUID admin>'
WHERE id = '<UUID du ban>';

ssh-guard émet un ip_unbanned au prochain cycle d’effective_status.

10.5 Désactiver temporairement ssh-guard

# .env
SSH_GUARD_ENABLED=false
sudo systemctl restart gitrust

ssh-guard devient un pass-through complet : aucune détection, aucun ban, le listener délègue directement à russh. À éviter sauf urgence.

11. Pour aller plus loin

• Variables d’environnement — SSH_GUARD_*
• Événements ssh-guard (JSON)
• ssh-guard : détection d’attaques SSH
• Durcir avec Fail2ban — chaîner ssh-guard et fail2ban
• Dépanner SSH — diagnostic général SSH
• Régler le rate limiting — distinction rate-limit HTTP vs TCP

Durcir l’instance avec Fail2ban

Évolution importante : depuis l’introduction de la crate gitrust-ssh-guard, le jail [gitrust-ssh] ne lit plus les logs russh via journalctl mais consomme directement le flux JSON stable émis par ssh-guard dans /var/log/gitrust-ssh-guard.json. Cela rend le jail bien plus fiable (format garanti stable, pas de regex fragile sur les messages de russh). Activez SSH_GUARD_LOG_TARGET=both dans .env — voir Configurer ssh-guard.

Configuration complète pour protéger un déploiement gitrust exposant :

• sshd système sur :2022 (admin)
• Nginx en reverse proxy HTTPS :443 + redirect :80 + stream :22 → :2222
• Gitrust (web 127.0.0.1:4000, SSH russh 127.0.0.1:2222)
• Dagger CI runner (local, pas d’exposition réseau directe)
• Dependency-Track API :8081 + UI :8080 (si exposés)
• PostgreSQL 127.0.0.1:5432 (défensif au cas où le bind fuit)

1. Installation

sudo apt install -y fail2ban
sudo systemctl enable --now fail2ban
fail2ban-client --version

Vérifier que ufw est actif (fournit banaction = ufw dans la config) :

sudo ufw status

2. Fichier principal /etc/fail2ban/jail.local

À placer via :

sudo tee /etc/fail2ban/jail.local <<'EOF'
[Le contenu ci-dessous]
EOF

# =============================================================================
# Défauts globaux
# =============================================================================
[DEFAULT]
backend  = systemd
bantime  = 1h
findtime = 10m
maxretry = 5

# LAN privé et loopback jamais bannis
ignoreip = 127.0.0.1/8 ::1 192.168.1.0/24

# UFW
banaction          = ufw
banaction_allports = ufw

# Notifications (optionnel — nécessite un relay SMTP local)
# destemail = contact@gitrust.eu
# sender    = fail2ban@votre-serveur.example.com
# action    = %(action_mwl)s

# =============================================================================
# 1) sshd admin système — port 2022
# =============================================================================
[sshd]
enabled  = true
port     = 2022
filter   = sshd
backend  = %(sshd_backend)s
logpath  = %(sshd_log)s
maxretry = 3
findtime = 10m
bantime  = 1h

# =============================================================================
# 2) Nginx — 401/403 auth basic (si un jour activé sur /admin, /metrics, etc.)
# =============================================================================
[nginx-http-auth]
enabled  = true
port     = http,https
filter   = nginx-http-auth
logpath  = /var/log/nginx/gitrust.error.log
maxretry = 5

# =============================================================================
# 3) Nginx — scanners d'URL (wp-admin, .env, phpmyadmin, config.php, etc.)
# =============================================================================
[nginx-botsearch]
enabled  = true
port     = http,https
filter   = nginx-botsearch
logpath  = /var/log/nginx/gitrust.access.log
maxretry = 2
findtime = 10m
bantime  = 24h

# =============================================================================
# 4) Nginx — bad user-agents (scanners agressifs, masscan, nikto, etc.)
# =============================================================================
[nginx-badbots]
enabled  = true
port     = http,https
filter   = nginx-badbots
logpath  = /var/log/nginx/gitrust.access.log
maxretry = 2
bantime  = 24h

# =============================================================================
# 5) Nginx — dépassement limit_req (voir section 4 — zones HTTPS)
# =============================================================================
[nginx-limit-req]
enabled  = true
port     = http,https
filter   = nginx-limit-req
logpath  = /var/log/nginx/gitrust.error.log
maxretry = 10
findtime = 5m
bantime  = 1h

# =============================================================================
# 6) Gitrust — brute force login (formulaire + API JWT)
# =============================================================================
[gitrust-login]
enabled  = true
port     = http,https
filter   = gitrust-login
logpath  = /var/log/nginx/gitrust.access.log
maxretry = 5
findtime = 10m
bantime  = 1h

# =============================================================================
# 7) Gitrust — abus API (tokens personnels leaked, scrapers)
# =============================================================================
[gitrust-api-abuse]
enabled  = true
port     = http,https
filter   = gitrust-api-abuse
logpath  = /var/log/nginx/gitrust.access.log
maxretry = 30
findtime = 1m
bantime  = 2h

# =============================================================================
# 8) Gitrust SSH — consomme les événements JSON stables de ssh-guard
# =============================================================================
# IMPORTANT : ce jail consomme le flux JSON émis par la crate gitrust-ssh-guard
# (champs stables documentés dans ../reference/ssh-guard-evenements.md).
# Le ban est déclenché soit sur le "signal fort" ip_banned (ssh-guard a déjà
# détecté la brute-force, fail2ban relaye au firewall) — un seul ip_banned
# suffit (maxretry=1) — soit sur le brut auth_failed avec le seuil habituel.
#
# Prérequis dans /opt/gitrust/.env :
#   SSH_GUARD_LOG_TARGET=both
#   SSH_GUARD_LOG_FILE=/var/log/gitrust-ssh-guard.json
[gitrust-ssh]
enabled  = true
port     = 22,2222
filter   = gitrust-ssh
logpath  = /var/log/gitrust-ssh-guard.json
maxretry = 1            # ssh-guard a déjà corrélé : 1 ip_banned = 1 ban firewall
findtime = 10m
bantime  = 1h

# =============================================================================
# 9) Gitrust import worker — tokens invalides sur clone de dépôts externes
# =============================================================================
[gitrust-import]
enabled      = true
port         = http,https
filter       = gitrust-import
backend      = systemd
journalmatch = _SYSTEMD_UNIT=gitrust.service
maxretry     = 3
findtime     = 5m
bantime      = 30m

# =============================================================================
# 10) Dependency-Track UI — brute force login (port 8080)
# =============================================================================
# Activer UNIQUEMENT si DTrack est exposé publiquement.
# Si DTrack est sur réseau privé/loopback, laisser enabled=false.
[dtrack-login]
enabled  = false
port     = 8080,http,https
filter   = dtrack-login
logpath  = /var/log/nginx/dtrack.access.log
maxretry = 5
findtime = 10m
bantime  = 2h

# =============================================================================
# 11) Dependency-Track API — abus clé API (port 8081)
# =============================================================================
[dtrack-api]
enabled  = false
port     = 8081,http,https
filter   = dtrack-api
logpath  = /var/log/nginx/dtrack.access.log
maxretry = 10
findtime = 5m
bantime  = 1h

# =============================================================================
# 12) PostgreSQL — tentatives de connexion invalides (défensif)
# =============================================================================
# PG doit binder 127.0.0.1 uniquement. Ce jail protège si la config fuit.
[postgresql]
enabled      = true
port         = 5432
filter       = postgresql
backend      = systemd
journalmatch = _SYSTEMD_UNIT=postgresql.service + _SYSTEMD_UNIT=docker.service
maxretry     = 5
findtime     = 10m
bantime      = 1h

# =============================================================================
# 13) Récidive — ban long pour IPs bannies 3x en 24h, tous jails confondus
# =============================================================================
[recidive]
enabled   = true
logpath   = /var/log/fail2ban.log
banaction = %(banaction_allports)s
bantime   = 1w
findtime  = 1d
maxretry  = 3

3. Filtres personnalisés

À placer dans /etc/fail2ban/filter.d/ (un fichier par jail custom).

3.1 gitrust-login.conf

sudo tee /etc/fail2ban/filter.d/gitrust-login.conf <<'EOF'
[Definition]
# POST sur /login ou endpoints JWT avec code 4xx (401/403/422/429)
failregex = ^<HOST> .* "POST /(login|api/v1/auth/login|api/v1/auth/refresh|api/v1/auth/2fa)[^"]*" (401|403|422|429) .*$
ignoreregex =
EOF

3.2 gitrust-api-abuse.conf

sudo tee /etc/fail2ban/filter.d/gitrust-api-abuse.conf <<'EOF'
[Definition]
# Abus API : 401/403 répétés sur /api/v1/* (hors auth déjà couvert par gitrust-login)
failregex = ^<HOST> .* "(GET|POST|PUT|DELETE|PATCH) /api/v1/(?!auth/)[^"]*" (401|403) .*$
ignoreregex =
EOF

3.3 gitrust-ssh.conf (consomme le JSON ssh-guard)

Le filtre matche les événements JSON stables produits par gitrust-ssh-guard. Voir Événements ssh-guard (JSON) pour le schéma complet.

Le « signal fort » ip_banned est privilégié : ssh-guard a déjà corrélé brute-force / énumération / scan de clés, et fail2ban n’a plus qu’à appliquer le ban au niveau firewall (UFW/iptables) pour les autres ports si désiré.

sudo tee /etc/fail2ban/filter.d/gitrust-ssh.conf <<'EOF'
[Definition]
# Filtre les événements stables émis par gitrust-ssh-guard dans
# /var/log/gitrust-ssh-guard.json. Format : une ligne JSON par événement.
#
# Capture <HOST> depuis le champ "ip" du JSON pour les variants pertinents.
#
# Tester :
#   sudo fail2ban-regex /var/log/gitrust-ssh-guard.json \
#                       /etc/fail2ban/filter.d/gitrust-ssh.conf

failregex = ^.*"event":"ip_banned".*"ip":"<HOST>".*$
            ^.*"event":"brute_force_detected".*"ip":"<HOST>".*$
            ^.*"event":"user_enumeration_detected".*"ip":"<HOST>".*$
            ^.*"event":"key_scanning_detected".*"ip":"<HOST>".*$
            ^.*"event":"connection_dropped".*"ip":"<HOST>".*"reason":"untrusted_proxy".*$
            ^.*"event":"connection_dropped".*"ip":"<HOST>".*"reason":"proxy_header_invalid".*$

ignoreregex =

# Date au format ISO 8601 UTC produit par ssh-guard
datepattern = "ts":"%%Y-%%m-%%dT%%H:%%M:%%S
EOF

Variante « brute uniquement » — si vous préférez que fail2ban corrèle lui-même à partir des auth_failed sans dépendre du verdict ssh-guard, remplacez le bloc ci-dessus par failregex = ^.*"event":"auth_failed".*"ip":"<HOST>".*$ et passez maxretry = 5 dans le jail. Les deux approches sont valides ; la première est plus rapide à réagir, la seconde est plus indépendante.

3.4 gitrust-import.conf

sudo tee /etc/fail2ban/filter.d/gitrust-import.conf <<'EOF'
[Definition]
# Import worker : tokens OAuth/GitHub invalides sur clone de dépôts externes
failregex = ^.*import.*authentication failed.*from <HOST>.*$
            ^.*import.*invalid (token|credentials).*from <HOST>.*$
            ^.*import.*clone failed.*401.*from <HOST>.*$
ignoreregex =
EOF

3.5 dtrack-login.conf (si DTrack exposé)

sudo tee /etc/fail2ban/filter.d/dtrack-login.conf <<'EOF'
[Definition]
# Dependency-Track : brute force du POST /api/v1/user/login
failregex = ^<HOST> .* "POST /api/v1/user/login[^"]*" (401|403) .*$
            ^<HOST> .* "POST /api/v1/user/forceChangePassword[^"]*" (401|403) .*$
ignoreregex =
EOF

3.6 dtrack-api.conf (si DTrack exposé)

sudo tee /etc/fail2ban/filter.d/dtrack-api.conf <<'EOF'
[Definition]
# Dependency-Track API : abus de clé API ou requêtes non authentifiées
failregex = ^<HOST> .* "[^"]+ /api/v1/[^"]*" 401 .*$
            ^<HOST> .* "[^"]+ /api/v1/[^"]*" 403 .*$
ignoreregex =
EOF

3.7 postgresql.conf (créer si absent)

if [ ! -f /etc/fail2ban/filter.d/postgresql.conf ]; then
sudo tee /etc/fail2ban/filter.d/postgresql.conf <<'EOF'
[Definition]
failregex = ^.*authentication failed for user.*host=<HOST>.*$
            ^.*FATAL:.*password authentication failed.*<HOST>.*$
            ^.*no pg_hba\.conf entry for host "<HOST>".*$
ignoreregex =
EOF
fi

3.8 nginx-limit-req.conf (créer si absent sur votre distro)

if [ ! -f /etc/fail2ban/filter.d/nginx-limit-req.conf ]; then
sudo tee /etc/fail2ban/filter.d/nginx-limit-req.conf <<'EOF'
[Definition]
failregex = ^.*limiting requests, excess: .* by zone .*, client: <HOST>.*$
ignoreregex =
EOF
fi

3.9 nginx-badbots.conf — OBLIGATOIRE (pas fourni par Debian/Ubuntu)

Le paquet fail2ban Debian/Ubuntu fournit apache-badbots.conf mais PAS nginx-badbots.conf. Sans ce filter, fail2ban-client reload affiche :

Found no accessible config files for 'filter.d/nginx-badbots' under /etc/fail2ban

Le filter ci-dessous réutilise la liste de bad user-agents de apache-badbots avec un failregex adapté au format combined de nginx :

sudo tee /etc/fail2ban/filter.d/nginx-badbots.conf <<'EOF'
[Definition]
badbotscustom = EmailCollector|WebEMailExtrac|TrackBack/1\.02|sogou music spider
badbots = Atomic_Email_Hunter/4\.0|atSpider/1\.0|autoemailspider|bwh3_user_agent|China Local Browse 2\.6|ContactBot/0\.2|ContentSmartz|DataCha0s/2\.0|DBrowse 1\.4b|DBrowse 1\.4d|Demo Bot DOT 16b|Demo Bot Z 16b|DSurf15a 01|DSurf15a 71|DSurf15a 81|DSurf15a VA|EBrowse 1\.4b|Educate Search VxB|EmailSiphon|EmailSpider|EmailWolf 1\.00|ExtractorPro|Franklin Locator 1\.8|Full Web Bot 0416B|Guestbook Auto Submitter|ISC Systems iRc Search 2\.1|LMQueueBot/0\.2|LWP\:\:Simple/5\.803|Microsoft URL Control - 6\.00\.8xxx|Missigua Locator 1\.9|Mozilla/4\.0 efp@gmx\.net|Nsauditor/1\.x|PBrowse 1\.4b|PEval 1\.4b|Poirot|psycheclone|sogou spider|sohu agent|VadixBot|WebVulnCrawl\.unknown/1\.0 libwww-perl/5\.803|Wells Search II|WEP Search 00

failregex = ^<HOST> -.*"(GET|POST|HEAD).*HTTP.*"(?:%(badbots)s|%(badbotscustom)s)"$
ignoreregex =

datepattern = ^[^\[]*\[({DATE})
              {^LN-BEG}
EOF

Alternative : si vous ne voulez pas maintenir la liste, simplement désactiver le jail (enabled = false dans le [nginx-badbots]) — la combinaison nginx-botsearch + nginx-limit-req + gitrust-api-abuse couvre déjà l’essentiel.

4. Rate limiting côté Nginx (requis par nginx-limit-req)

4.1 Déclarer les zones globales

sudo tee /etc/nginx/conf.d/gitrust-limit.conf <<'EOF'
# Zones de rate limiting gitrust
limit_req_zone $binary_remote_addr zone=gitrust_login:10m rate=1r/s;
limit_req_zone $binary_remote_addr zone=gitrust_api:10m   rate=10r/s;
limit_req_zone $binary_remote_addr zone=gitrust_git:10m   rate=30r/s;
EOF

4.2 Ajouter les location dans /etc/nginx/sites-available/gitrust

Dans le bloc server { listen 443 ssl; ... }, avant location / finale :

# Protection brute force login (1 req/s par IP, burst 5)
location ~ ^/(login|api/v1/auth/) {
    limit_req zone=gitrust_login burst=5 nodelay;
    proxy_pass http://gitrust_backend;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# Protection API (10 req/s par IP, burst 20)
location ^~ /api/v1/ {
    limit_req zone=gitrust_api burst=20 nodelay;
    proxy_pass http://gitrust_backend;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# Protection Git smart HTTP (30 req/s — clone/push légitime peut être verbeux)
location ~ ^/[^/]+/[^/]+\.git/ {
    limit_req zone=gitrust_git burst=50 nodelay;
    proxy_pass http://gitrust_backend;
    proxy_http_version 1.1;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_request_buffering off;
    client_max_body_size 2G;
}

4.3 Reload

sudo nginx -t && sudo systemctl reload nginx

5. Démarrage et validation

sudo systemctl restart fail2ban

# Liste des jails actifs
sudo fail2ban-client status
# Attendu :
#   sshd, nginx-http-auth, nginx-botsearch, nginx-badbots, nginx-limit-req,
#   gitrust-login, gitrust-api-abuse, gitrust-ssh, gitrust-import,
#   postgresql, recidive
#   (+ dtrack-login, dtrack-api si activées)

# Stats par jail
sudo fail2ban-client status gitrust-login
sudo fail2ban-client status sshd

Valider chaque filtre custom

# 1. gitrust-login contre l'access log nginx
sudo fail2ban-regex /var/log/nginx/gitrust.access.log \
                    /etc/fail2ban/filter.d/gitrust-login.conf

# 2. gitrust-api-abuse
sudo fail2ban-regex /var/log/nginx/gitrust.access.log \
                    /etc/fail2ban/filter.d/gitrust-api-abuse.conf

# 3. gitrust-ssh contre le flux JSON ssh-guard
sudo fail2ban-regex /var/log/gitrust-ssh-guard.json \
                    /etc/fail2ban/filter.d/gitrust-ssh.conf
# Si /var/log/gitrust-ssh-guard.json n'existe pas, vérifiez SSH_GUARD_LOG_TARGET
# et SSH_GUARD_LOG_FILE dans /opt/gitrust/.env (voir how-to/configurer-ssh-guard.md).

# 4. postgresql
journalctl -u docker --no-pager -n 5000 | grep -i postgres > /tmp/pg.log
sudo fail2ban-regex /tmp/pg.log \
                    /etc/fail2ban/filter.d/postgresql.conf

0 failregex found = regex à ajuster après observation des logs réels de chaque service.

Test de bannissement

# Depuis un host HORS LAN (sinon ignoreip s'applique)
for i in $(seq 1 10); do
  curl -sk -o /dev/null -w "%{http_code}\n" \
    -X POST https://<votre-domaine>/login \
    -d 'username=admin&password=wrong'
done

# Vérifier le ban
ssh gitrust-host 'sudo fail2ban-client status gitrust-login'
# Currently banned : 1 — Banned IP list : <IP test>

# Débannir manuellement
ssh gitrust-host 'sudo fail2ban-client unban <IP>'

6. Monitoring

# Logs fail2ban temps réel
sudo tail -f /var/log/fail2ban.log

# Toutes les IPs bannies, tous jails confondus
sudo fail2ban-client banned

# Stats détaillées d'un jail
sudo fail2ban-client status gitrust-ssh
#    Currently failed : 2
#    Total failed     : 47
#    Currently banned : 1
#    Total banned     : 12
#    Banned IP list   : 203.0.113.42

sudo grep "Ban " /var/log/fail2ban.log | tail -20

7. Matrice récapitulative

Ordre de déclenchement typique : brute force → jail spécifique (ban 1h) → si récidive 3x → recidive (ban 1 semaine, tous ports).

8. Notes spécifiques à la stack gitrust

8.1 Dagger (CI)

Dagger s’exécute localement sur la machine gitrust (ou un runner distant — voir administration_manual/how-to/configurer-ci-runner-remote.md). Aucun port réseau ouvert → pas de jail dédié.

8.2 Dependency-Track

Si DTrack est déployé sur le même serveur et exposé, activer les jails 10 et 11 en mettant enabled = true et en pointant logpath vers les logs nginx du vhost DTrack.

Si DTrack est interne (VPN, réseau privé), laisser enabled = false — le firewall suffit.

Config DTrack recommandée :

• Bind sur 127.0.0.1 via dtrack.url.base=http://127.0.0.1:8080

8.3 PostgreSQL

Le jail postgresql est défensif. PG doit rester bindé sur 127.0.0.1:5432 via Docker. Vérifier :

sudo ss -tlnp | grep 5432
# Attendu : 127.0.0.1:5432 — PAS 0.0.0.0:5432

8.4 Notifications

Pour recevoir un mail à chaque ban :

1. Installer un relay SMTP local : sudo apt install msmtp-mta
2. Configurer /etc/msmtprc avec un compte SMTP
3. Décommenter dans [DEFAULT] :

   destemail = contact@gitrust.eu
   sender    = fail2ban@votre-serveur.example.com
   action    = %(action_mwl)s
   

4. sudo systemctl restart fail2ban

9. Limites et évolutions

• IPv6 : toutes les regex utilisent <HOST> qui matche IPv4 ET IPv6. Vérifier que UFW est configuré pour v6 également.
• CDN/Cloudflare devant : si un CDN est ajouté, $remote_addr côté Nginx sera l’IP du CDN — il faut récupérer la vraie IP via X-Forwarded-For et propager au logging Nginx. Changer failregex en conséquence. Sinon les jails banniront le CDN.
• Docker/Podman : si gitrust passe en conteneur, les logs de gitrust.service deviennent docker.service ou podman.service → mettre à jour journalmatch dans le jail 9 (gitrust-import). Le jail 8 (gitrust-ssh) n’est pas affecté car il consomme le fichier JSON ssh-guard, à condition que ce fichier soit monté côté hôte.
• GeoIP : pour bloquer des pays entiers en amont, ajouter geo $blocked_country dans Nginx (module ngx_http_geoip2_module) — complémentaire à fail2ban.

Régler le rate limiting

À qui s’adresse cette page

Administrateurs qui souhaitent ajuster les limites de débit pour protéger l’instance contre les attaques par force brute et les abus d’API, tout en évitant de bloquer les utilisateurs légitimes.

Variables disponibles

Ces variables se définissent dans /opt/gitrust/.env. Un redémarrage est nécessaire après modification. 0 désactive la limite (déconseillé en production).

Les limites s’appliquent par adresse IP. Si gitrust est derrière un reverse-proxy, assurez-vous que le vrai IP du client est transmis (en-tête X-Forwarded-For ou X-Real-IP).

Profils de configuration recommandés

Petite équipe (≤ 5 personnes, réseau de confiance)

Toutes les personnes travaillent depuis un réseau connu. On peut se permettre des limites légèrement plus souples pour éviter les faux positifs lors des scripts d’intégration.

RATE_LIMIT_LOGIN_PER_MINUTE=10
RATE_LIMIT_REFRESH_PER_MINUTE=20
RATE_LIMIT_GENERAL_PER_MINUTE=200

Équipe moyenne (6-20 personnes, instance interne)

Configuration par défaut, adaptée à la cible principale de gitrust.

RATE_LIMIT_LOGIN_PER_MINUTE=5
RATE_LIMIT_REFRESH_PER_MINUTE=10
RATE_LIMIT_GENERAL_PER_MINUTE=100

Instance publique ou exposée sur Internet (50+ utilisateurs)

Limites plus strictes sur le login pour contrer les attaques par dictionnaire. La limite générale peut être augmentée si vos utilisateurs utilisent intensivement l’API.

RATE_LIMIT_LOGIN_PER_MINUTE=3
RATE_LIMIT_REFRESH_PER_MINUTE=10
RATE_LIMIT_GENERAL_PER_MINUTE=150

CI/CD avec beaucoup d’appels API

Si vos pipelines CI font de nombreuses requêtes API (création de statuts, commentaires, webhooks), augmentez uniquement RATE_LIMIT_GENERAL_PER_MINUTE depuis les IPs des runners :

RATE_LIMIT_GENERAL_PER_MINUTE=300

Ou configurez Nginx pour whitelister les IPs des runners CI avant le rate limiting de gitrust.

Surveiller les réponses 429

Quand une limite est dépassée, gitrust retourne HTTP 429 Too Many Requests. Ces réponses apparaissent dans les logs avec le niveau WARN.

# Surveiller les 429 en temps réel
sudo journalctl -u gitrust -f | grep "429\|rate_limit\|too many"

# Compter les 429 sur les 24 dernières heures
sudo journalctl -u gitrust --since "24 hours ago" --no-pager \
  | grep -c "429\|rate_limit"

Si vous utilisez Nginx comme reverse-proxy, vous pouvez aussi consulter les logs Nginx :

grep " 429 " /var/log/nginx/gitrust-access.log | awk '{print $1}' | sort | uniq -c | sort -rn | head -20

Cela vous donne les IPs les plus souvent bloquées, utile pour distinguer une vraie attaque d’un utilisateur légitime avec un script trop agressif.

Gitrust derrière un reverse-proxy

Si gitrust écoute sur 127.0.0.1:4000 derrière Nginx, le rate limiting de gitrust voit l’IP 127.0.0.1 pour toutes les requêtes, ce qui rend la protection inefficace.

Configurez Nginx pour transmettre le vrai IP :

# Dans le bloc location de gitrust
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Et dans /opt/gitrust/.env, indiquez que gitrust est derrière un proxy de confiance :

# Ajouter si le reverse-proxy est sur 127.0.0.1
SERVER_HOST=127.0.0.1

Gitrust utilise alors X-Real-IP pour identifier l’IP cliente réelle dans ses mécanismes de rate limiting.

Rate-limit TCP par IP (ssh-guard)

Les variables RATE_LIMIT_* ci-dessus s’appliquent à la couche HTTP (login, API, refresh JWT). Pour le port SSH (:2222 par défaut), un mécanisme distinct est fourni par la crate gitrust-ssh-guard : un cap dur de connexions TCP/seconde par IP, indépendant de tout traitement applicatif.

Différences avec le rate-limit HTTP :

• Pas de réponse 429 : la connexion TCP est droppée immédiatement au listener (avant tout handshake SSH).
• Pas de ban persistant en DB : un scan de port n’engendre aucune écriture.
• Budgets indépendants par IP via token bucket GCRA (algorithme leaky bucket sans biais).
• Une IP allowlistée dans ssh_guard_acl bypasse complètement ce cap.

Pour la recette complète (profils par topologie, dry-run, allowlist CI), voir Configurer ssh-guard. Pour le détail des événements émis (connection_flood_detected, connection_dropped avec reason=flood_limit), voir Événements ssh-guard (JSON).

Fail2ban comme couche complémentaire

Le rate limiting de gitrust agit requête par requête. Fail2ban analyse les logs et peut bannir les IPs pour une durée configurable après plusieurs 429.

Voir Durcir avec Fail2ban pour la configuration complète.

Pour aller plus loin

• Variables d’environnement — section Rate Limiting
• Variables d’environnement — section SSH_GUARD_*
• Configurer ssh-guard
• ssh-guard : détection d’attaques SSH
• Durcir avec Fail2ban
• Conformité ANSSI PA-074 — protection contre les attaques par force brute

Forcer le 2FA sur toute l’instance

À qui s’adresse cette page

Administrateurs qui souhaitent obliger tous les utilisateurs à configurer l’authentification à deux facteurs (TOTP) avant d’accéder à l’instance.

Activer le 2FA obligatoire

Le paramètre totp_force_enabled est un paramètre dynamique stocké en base de données. Il prend effet immédiatement, sans redémarrage du service.

1. Connectez-vous à l’interface d’administration : /admin
2. Accédez à /admin/settings
3. Trouvez le paramètre totp_force_enabled
4. Activez le toggle et cliquez Enregistrer

Comportement après activation

Dès que totp_force_enabled=true est enregistré :

• Tout utilisateur sans 2FA configuré est redirigé vers la page de configuration TOTP à sa prochaine connexion. Il ne peut pas accéder à l’application tant que la configuration n’est pas complète.
• Les utilisateurs qui ont déjà configuré le 2FA ne sont pas affectés.
• Les administrateurs sont soumis à la même règle — vérifiez que votre propre compte a le 2FA actif avant d’activer ce paramètre.

Conseil : prévenez vos utilisateurs avant d’activer ce paramètre. Un e-mail ou une annonce interne évite les appels au support pour des connexions bloquées.

Vérifier que le 2FA est actif sur votre compte

Avant d’activer totp_force_enabled, confirmez que votre compte admin a bien le 2FA configuré :

1. Cliquez sur votre avatar → Paramètres du profil
2. Section Sécurité → vérifiez que Authentification à deux facteurs affiche « Actif »

Si ce n’est pas le cas, configurez le 2FA sur votre compte avant d’activer le paramètre global.

Révoquer le 2FA d’un utilisateur spécifique

Si un utilisateur a perdu accès à son application TOTP (téléphone perdu, application réinstallée) :

1. Accédez à /admin/users
2. Ouvrez la fiche de l’utilisateur concerné
3. Cliquez Révoquer le 2FA
4. L’utilisateur sera invité à reconfigurer le TOTP à sa prochaine connexion

Désactiver le 2FA obligatoire

1. Accédez à /admin/settings
2. Désactivez le toggle totp_force_enabled
3. Cliquez Enregistrer

Les utilisateurs peuvent à nouveau se connecter sans 2FA. Les configurations TOTP existantes sont conservées.

Pour aller plus loin

• Gérer les utilisateurs — révoquer le 2FA individuellement
• Paramètres dynamiques — totp_force_enabled
• Conformité ANSSI PA-074 — authentification multi-facteurs

Dépanner les problèmes SSH (clés, ports, fingerprints)

À qui s’adresse cette page

Administrateurs confrontés à des erreurs lors de l’authentification SSH ou des opérations git clone/git push via SSH sur gitrust.

Architecture SSH de gitrust

Gitrust intègre son propre serveur SSH via la bibliothèque Russh — ce n’est pas le démon sshd du système. Il écoute par défaut sur le port 2222. Depuis l’introduction de la crate gitrust-ssh-guard, toute connexion TCP passe d’abord par un sas (SecureListener) qui peut la dropper avant le handshake SSH (ban, flood, en-tête PROXY invalide). Voir Configurer ssh-guard et ssh-guard : détection d’attaques SSH.

sequenceDiagram
    participant U as Client git (utilisateur)
    participant G as ssh-guard (SecureListener)
    participant R as Serveur gitrust (Russh :2222)
    participant DB as PostgreSQL

    U->>G: Connexion TCP (port 2222)
    G->>G: ACL / ban / flood
    alt Drop
        G-->>U: Connexion fermée
    else Accept
        G->>R: TcpStream + ClientIdentity
        R->>U: Présente clé hôte Ed25519
        U->>U: Vérifie fingerprint (known_hosts)
        U->>R: Envoie clé publique SSH
        R->>DB: Cherche fingerprint dans ssh_keys
        DB-->>R: Trouvé (user_id)
        R->>G: AuthTracker.record_auth_attempt
        R-->>U: Authentifié
        U->>R: git-upload-pack / git-receive-pack
    end

Erreur 1 : Connection refused sur le port 2222

ssh: connect to host SERVEUR port 2222: Connection refused

Diagnostic :

# Depuis le serveur : vérifier que gitrust écoute
ss -tlnp | grep 2222
# Attendu : LISTEN 0 ... *:2222 ... gitrust

# Depuis l'extérieur
nc -zv SERVEUR 2222

Causes et corrections :

Erreur 2 : WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING A MITM ATTACK!

Cause : la clé SSH hôte du serveur a changé (migration vers un nouveau serveur, régénération de la clé, restauration depuis une sauvegarde différente).

Vérifier le nouveau fingerprint :

# Sur le serveur
sudo -u gitrust ssh-keygen -l -f /opt/gitrust/data/ssh_host_ed25519_key.pub
# Exemple : SHA256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX gitrust-host-key (ED25519)

Si ce fingerprint correspond à un changement légitime (migration, etc.), demandez aux utilisateurs de supprimer l’ancienne entrée de leur known_hosts :

# Sur la machine du client git
ssh-keygen -R "[SERVEUR]:2222"
# Puis re-cloner ou accepter le nouveau fingerprint

Si vous ne reconnaissez pas ce changement, il peut indiquer une compromission. Investiguez avant de continuer.

Erreur 3 : Permission denied (publickey)

git@SERVEUR: Permission denied (publickey).
fatal: Could not read from remote repository.

Diagnostic pas à pas :

# 1. Tester la connexion avec verbosité maximale
ssh -vvv -p 2222 git@SERVEUR

# 2. Vérifier quelle clé est proposée par le client
# Dans la sortie -vvv, chercher :
# debug1: Offering public key: /home/user/.ssh/id_ed25519 ED25519 SHA256:...
# debug1: Authentications that can continue: publickey

# 3. Obtenir le fingerprint de votre clé locale
ssh-keygen -l -f ~/.ssh/id_ed25519.pub
# SHA256:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYY (ED25519)

Comparez ce fingerprint avec celui enregistré dans gitrust pour votre compte :

1. Connectez-vous à l’interface web gitrust
2. Accédez à Paramètres → Clés SSH
3. Vérifiez que le fingerprint correspond

Causes courantes :

Vérifier les permissions des fichiers de clés côté client :

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Erreur 4 : Could not resolve hostname

ssh: Could not resolve hostname SERVEUR: Name or service not known

Cause : le nom de domaine dans l’URL de clone ne correspond pas à SSH_PUBLIC_HOST ou n’est pas résolvable.

Vérifier la configuration :

# Dans .env
grep SSH_PUBLIC_HOST /opt/gitrust/.env
# Doit correspondre au FQDN ou à l'IP utilisé dans les URLs de clone

# Tester la résolution DNS
nslookup VOTRE_SSH_PUBLIC_HOST

Erreur 5 : Timeout ou connexion très lente

ssh: connect to host SERVEUR port 2222: Operation timed out

ou connexion qui s’établit mais met 30+ secondes.

Causes et corrections :

Erreur 6 : la connexion est droppée par ssh-guard

Symptôme côté client : la connexion TCP est acceptée puis fermée immédiatement, sans aucun message d’authentification SSH. Ce comportement est typique d’un drop ssh-guard (ban actif, flood, en-tête PROXY refusé).

Diagnostic :

# Si SSH_GUARD_LOG_TARGET=both ou file
sudo tail -100 /var/log/gitrust-ssh-guard.json \
  | jq 'select(.event=="connection_dropped")'

# Sinon (target=stderr) — passer par journald
sudo journalctl -u gitrust --since "5 min ago" --no-pager \
  | grep '"event":"connection_dropped"' | tail -10

Diagnostic ssh-guard rapide

Lire le flux d’événements en direct

# Dernier événement par IP (ssh-guard log target = stderr/journald)
sudo journalctl -u gitrust -f | grep '"event":"' | jq -c '.'

# Idem si SSH_GUARD_LOG_TARGET=file ou both
sudo tail -f /var/log/gitrust-ssh-guard.json | jq -c '.'

Mode dry-run pour reproduire un blocage sans persister

Si vous suspectez qu’un seuil est trop agressif, passez SSH_GUARD_DRY_RUN=true dans .env puis redémarrez. Les détecteurs continuent à émettre les ip_banned (signal pour fail2ban / observabilité) sans que ssh-guard pose réellement le ban. Vous pouvez observer le motif sur 24-48 h avant de décider.

Vérifier que la vraie IP est bien extraite (profils nginx/haproxy)

# Faire un git ls-remote depuis une IP externe connue, puis :
sudo journalctl -u gitrust --since "1 min ago" --no-pager \
  | grep '"event":"connection_accepted"' | tail -1 | jq .ip
# Doit retourner l'IP externe, PAS 127.0.0.1

Désactiver temporairement ssh-guard

# .env
SSH_GUARD_ENABLED=false
sudo systemctl restart gitrust

ssh-guard devient un pass-through complet (aucune détection, aucun ban). À utiliser seulement pour confirmer qu’un problème vient bien de la couche guard ; remettre true immédiatement après.

Pour le détail des événements, voir Événements ssh-guard (JSON).

Consulter les logs SSH

# Logs du service gitrust (contient les événements SSH)
sudo journalctl -u gitrust -f | grep -i "ssh\|auth\|key\|fingerprint"

# Filtrer les erreurs d'authentification
sudo journalctl -u gitrust --since "1 hour ago" --no-pager \
  | grep -i "auth.*failed\|permission denied\|invalid key"

Pour aller plus loin

• Variables d’environnement — section SSH
• Variables d’environnement — section SSH_GUARD_*
• Configurer ssh-guard
• Événements ssh-guard (JSON)
• Ports et services
• Gérer les utilisateurs : révoquer une clé SSH

Dépanner la CI intégrée (Dagger)

À qui s’adresse cette page