📄 SPÉCIFICATION CANONIQUE CONTRACTUELLE¶

PD-12 — Configuration GitLab Runner pour CI/CD

📌 Artefact produit
➡️ specifications/PD-12-spec.md

1. Objectif¶

Définir de manière formelle, complète et testable les exigences nécessaires à la mise en place d’un ou plusieurs GitLab Runner destinés à l’exécution des pipelines CI/CD du projet ProbatioVault, hébergés sur une infrastructure OVH, avec des executors Docker, un mécanisme de cache, et une gestion sécurisée des secrets.

Cette spécification constitue une référence contractuelle : toute implémentation devra s’y conformer strictement.

2. Périmètre / Hors périmètre¶

2.1 Périmètre¶

La présente spécification couvre exclusivement :

• l’enregistrement et la configuration de GitLab Runner ;
• l’exécution des jobs CI/CD via des executors Docker ;
• la gestion du cache de pipeline ;
• l’accès aux secrets nécessaires aux pipelines ;
• l’intégration du Runner avec l’infrastructure OVH ;
• les exigences de sécurité, d’isolation et de traçabilité associées.

2.2 Hors périmètre¶

Les éléments suivants sont explicitement hors périmètre :

• la définition des pipelines CI/CD eux-mêmes (.gitlab-ci.yml) ;
• la logique métier des jobs exécutés ;
• la configuration interne des images Docker utilisées par les jobs ;
• la gestion des permissions GitLab (groupes, projets, rôles) ;
• l’optimisation des performances CI/CD ;
• la supervision applicative du Runner (monitoring détaillé).

Tout besoin relevant de ces sujets devra faire l’objet d’une spécification distincte.

3. Définitions¶

4. Invariants (non négociables)¶

Les règles suivantes sont non négociables et doivent être respectées en toutes circonstances :

1. Le Runner ne doit jamais exposer de secrets en clair dans les logs.
2. Les jobs CI/CD doivent être exécutés dans un environnement isolé les uns des autres.
3. Aucun job ne doit pouvoir accéder aux données persistantes d’un autre job sans mécanisme explicitement prévu.
4. Toute exécution de job doit être traçable (identifiable par pipeline, job, commit).
5. Les secrets utilisés par les pipelines doivent être révocables sans redéploiement du Runner.
6. Le Runner ne doit exécuter que des jobs explicitement autorisés par GitLab.
7. Toute règle ci-dessus doit être vérifiable par test ou audit.

5. Flux nominaux¶

5.1 Enregistrement du Runner¶

1. Un Runner est enregistré auprès d’une instance GitLab.
2. Le Runner est associé à un périmètre défini (instance, groupe ou projet).
3. Le Runner devient disponible pour l’exécution de pipelines autorisés.

5.2 Exécution d’un pipeline¶

1. Un événement GitLab déclenche un pipeline CI/CD.
2. GitLab assigne un job au Runner compatible.
3. Le Runner instancie un environnement Docker dédié au job.
4. Le job s’exécute dans cet environnement isolé.
5. Les résultats du job sont remontés à GitLab.
6. L’environnement d’exécution est détruit à la fin du job.

5.3 Utilisation du cache¶

1. Un job déclare l’utilisation d’un cache.
2. Le Runner tente de restaurer le cache associé.
3. Le job s’exécute.
4. Le cache est mis à jour selon les règles définies.

5.4 Accès aux secrets¶

1. Un job nécessite un ou plusieurs secrets.
2. Les secrets sont injectés dans l’environnement d’exécution du job.
3. Les secrets sont utilisables uniquement pendant l’exécution du job.
4. Les secrets ne persistent pas après la fin du job.

5bis. Diagrammes¶

5bis.1 Diagramme d’états — Cycle de vie du Runner¶

Le Runner traverse plusieurs états depuis son enregistrement jusqu’à son éventuelle désinscription. Les invariants INV-6 (jobs explicitement autorisés) et INV-7 (vérifiabilité) s’appliquent à chaque transition.

stateDiagram-v2
    [*] --> Unregistered
    Unregistered --> Registered : Enregistrement auprès de GitLab (§5.1.1-2)
    Registered --> Available : Association périmètre validée (§5.1.3)
    Available --> Executing : Job assigné par GitLab (§5.2.2)
    Executing --> Available : Job terminé, environnement détruit (§5.2.6) [INV-2, INV-3]
    Executing --> Error : Échec exécution Docker / secret manquant
    Error --> Available : Erreur remontée à GitLab (§6) [INV-4]
    Available --> Unavailable : Runner indisponible (réseau, ressources)
    Unavailable --> Available : Reprise de service
    Available --> Unregistered : Désinscription
    Unavailable --> Unregistered : Désinscription forcée

    note right of Executing
        INV-1 : Secrets jamais en clair dans les logs
        INV-2 : Isolation inter-jobs
        INV-3 : Pas de données persistantes partagées
    end note

5bis.2 Diagramme de séquence — Exécution d’un pipeline avec secrets¶

Ce diagramme détaille l’interaction entre GitLab, le Runner, Docker et le gestionnaire de secrets lors de l’exécution d’un job (§5.2 + §5.4). Les invariants référencés garantissent l’isolation (INV-2, INV-3), la non-persistance des secrets (INV-1, INV-5) et la traçabilité (INV-4).

sequenceDiagram
    participant GL as GitLab
    participant RN as GitLab Runner
    participant DK as Docker (executor)
    participant SC as Secret Store (Vault)
    participant CA as Cache Storage

    GL->>RN: Assigner job (pipeline, commit, job_id) [INV-4]
    activate RN

    RN->>DK: Créer conteneur éphémère isolé [INV-2, INV-3]
    activate DK

    RN->>SC: Récupérer secrets pour le job [INV-5]
    SC-->>RN: Secrets (durée de vie = job)

    RN->>DK: Injecter secrets dans l’environnement [INV-1]

    RN->>CA: Restaurer cache (si déclaré, §5.3.2)
    CA-->>DK: Données de cache

    DK->>DK: Exécuter le job

    DK-->>RN: Résultat du job (succès / échec)

    RN->>CA: Mettre à jour cache (§5.3.4)

    RN->>DK: Détruire conteneur + purger secrets [INV-2, INV-3]
    deactivate DK
    Note over DK: Aucun secret ne persiste [INV-1, INV-5]

    RN-->>GL: Remonter statut + logs (secrets masqués) [INV-1, INV-4]
    deactivate RN

5bis.3 Diagramme de séquence — Révocation de secret¶

Ce diagramme illustre le comportement attendu lors de la révocation d’un secret (§5.4, scénario 3). L’invariant INV-5 (révocabilité sans redéploiement) est central.

sequenceDiagram
    participant OP as Opérateur
    participant SC as Secret Store (Vault)
    participant GL as GitLab
    participant RN as GitLab Runner
    participant DK as Docker (executor)

    OP->>SC: Révoquer secret [INV-5]
    SC-->>OP: Confirmation révocation

    Note over SC: Secret invalidé immédiatement

    GL->>RN: Nouveau pipeline déclenché
    activate RN
    RN->>DK: Créer conteneur éphémère
    activate DK
    RN->>SC: Récupérer secrets pour le job
    SC-->>RN: Erreur : secret révoqué

    RN->>DK: Détruire conteneur [INV-2]
    deactivate DK
    RN-->>GL: Job échoué — secret invalide [INV-4, INV-6]
    deactivate RN

    Note over GL: Statut d’échec explicite et traçable [INV-7]

6. Cas d’erreur¶

• Échec d’enregistrement du Runner auprès de GitLab.
• Job assigné à un Runner indisponible.
• Échec de création de l’environnement Docker.
• Cache indisponible ou corrompu.
• Secret manquant ou invalide.
• Tentative d’accès non autorisée à un secret.
• Échec de communication entre GitLab et le Runner.

Chaque cas d’erreur doit produire un retour explicite et traçable dans GitLab.

7. Critères d’acceptation (testables)¶

• Un pipeline simple peut être exécuté de bout en bout via le Runner.
• Deux jobs exécutés en parallèle ne partagent aucun état persistant.
• Un secret révoqué devient immédiatement inutilisable dans les pipelines.
• Aucun secret n’apparaît en clair dans les logs GitLab.
• Le cache est correctement restauré et mis à jour selon les règles définies.
• Un job échouant produit un statut d’échec explicite dans GitLab.

8. Scénarios de test (Given / When / Then)¶

Scénario 1 — Exécution nominale¶

Given un Runner enregistré et actif
When un pipeline CI/CD est déclenché
Then le job est exécuté avec succès et son statut est visible dans GitLab

Scénario 2 — Isolation des jobs¶

Given deux jobs exécutés en parallèle
When chacun écrit dans son environnement
Then aucun job ne peut lire ou modifier les données de l’autre

Scénario 3 — Révocation de secret¶

Given un secret valide utilisé par un pipeline
When le secret est révoqué
Then tout nouveau pipeline échoue explicitement lors de l’accès au secret

Scénario 4 — Erreur d’exécution Docker¶

Given un environnement Docker non disponible
When un job est assigné au Runner
Then le job échoue avec une erreur explicite et traçable

9. Hypothèses explicites¶

• Une instance GitLab fonctionnelle est disponible.
• Les ressources OVH sont accessibles et opérationnelles.
• Les pipelines CI/CD sont correctement définis en amont.
• Les utilisateurs GitLab disposent des droits nécessaires pour déclencher des pipelines.

10. Points à clarifier¶

Les éléments suivants nécessitent une clarification explicite avant implémentation :

1. Périmètre exact du Runner (instance, groupe ou projet).
2. Politique de durée de vie du cache CI.
3. Volume maximal de cache autorisé.
4. Politique de rotation des secrets.
5. Niveau de journalisation attendu pour le Runner.
6. Exigences spécifiques de conformité (ex. audit interne, normes).

Fin de la spécification canonique.