> ## Documentation Index
> Fetch the complete documentation index at: https://infra-docs.kaeyros.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruleset production-grade : protection des branches

> Le ruleset GitHub qui protège les branches production et staging : 2 approbations, CODEOWNERS, déploiement develop et méthodes de merge autorisées.

Le ruleset `production-grade` est la barrière de conformité qui protège les branches `production` et `staging` sur tous les dépôts applicatifs de l'organisation `kaeyros-analytics-org`. Cette page décrit ce que le ruleset impose, à qui il s'applique et comment le lire.

## Ce que le ruleset impose

> **Cible**
>
> Branches `refs/heads/production` et `refs/heads/staging`

> **Portée**
>
> Dépôt `kaeyros-analytics-org/sema` (à généraliser au reste)

> **Application**
>
> `enforcement: active`, s'applique à tous les collaborateurs

> **Contournement**
>
> OrganizationAdmin et un rôle de dépôt (id 5), mode `always`

## Les cinq règles

> **1. Suppression interdite (deletion)**
>
> Aucun utilisateur ne peut supprimer les branches `production` ou `staging`, même avec les droits d'écriture. Une suppression accidentelle depuis l'interface GitHub ou en ligne de commande est refusée.

> **2. Pas de force-push (non\_fast\_forward)**
>
> Toute mise à jour qui n'est pas un fast-forward est refusée. Autrement dit, aucun `git push --force` ni aucune réécriture d'historique n'est possible sur ces deux branches. L'historique est immuable.

> **3. Pull Request obligatoire (pull\_request)**
>
> Toute modification passe par une PR avec les paramètres suivants:
>
> | Paramètre | Valeur | Effet |
> | - | - | - |
> | `required_approving_review_count` | `2` | 2 approbations minimum |
> | `dismiss_stale_reviews_on_push` | `true` | Les revues sont invalidées à chaque nouveau commit |
> | `require_code_owner_review` | `true` | Un CODEOWNER doit avoir approuvé |
> | `require_last_push_approval` | `true` | Le dernier commit doit être approuvé après avoir été poussé |
> | `required_review_thread_resolution` | `true` | Toutes les conversations doivent être résolues |
> | `require_extra_approval_for_unattributed_changes` | `true` | Une approbation supplémentaire est requise pour les changements sans auteur identifiable |
> | `allowed_merge_methods` | `merge`, `squash`, `rebase` | Les trois méthodes sont autorisées |
>
> > [!NOTE]
> >
> > Le fichier `CODEOWNERS` du dépôt détermine qui doit approuver quelles zones. Sans CODEOWNER pour un chemin modifié, la PR ne peut pas être mergée.

> **4. Update (update)**
>
> La règle `update` verrouille la mise à jour de la référence: seule la voie de la Pull Request permet de faire avancer la branche. Un `git push` direct sur `production` ou `staging` est refusé.

> **5. Déploiement develop obligatoire (required\_deployments)**
>
> Toute PR vers `production` ou `staging` doit d'abord avoir déclenché un déploiement sur l'environnement `develop`. Concrètement, la CI doit avoir publié une image et validé le déploiement dev avant qu'un merge soit possible.
>
> > [!WARNING]
> >
> > Une PR qui n'a pas de déploiement `develop` réussi restera bloquée à l'étape de merge, quelles que soient les approbations obtenues.

## Le flux complet, protégé par le ruleset

```mermaid theme={null}
flowchart TB
    A[Branche de feature] --> B[PR vers develop]
    B --> C{Tests CI et lint}
    C -->|OK| D[Merge sur develop]
    D --> E[Déploiement environnement develop]
    E --> F[PR develop → staging]
    F --> G{Ruleset production-grade}
    G -->|2 approbations + CODEOWNER + déploiement develop OK| H[Merge staging]
    G -->|Une condition manque| X[PR bloquée]
    H --> I[Validation QA]
    I --> J[PR staging → production]
    J --> K{Ruleset production-grade}
    K -->|2 approbations + CODEOWNER + déploiement develop OK| L[Merge production]
    K -->|Une condition manque| X
    L --> M[Argo Rollouts, canary progressif]
```

## Qui peut contourner

Deux acteurs sont autorisés à contourner le ruleset en mode `always`:

> **OrganizationAdmin**
>
> Les administrateurs de l'organisation `kaeyros-analytics-org`.

> **Rôle de dépôt id 5**
>
> Un rôle de dépôt custom défini par l'équipe. À documenter précisément.

> [!WARNING]
>
> Le contournement en mode `always` doit rester exceptionnel. Chaque contournement laisse une trace auditable dans les logs d'organisation. Documentez le motif dans le message de commit ou dans le ticket associé.

## Les erreurs les plus fréquentes

> **Ma PR est verte mais je ne peux pas la merger**
>
> Vérifiez dans l'ordre:
>
> * Avez-vous 2 approbations distinctes?
> * Un CODEOWNER a-t-il approuvé les chemins modifiés?
> * Le dernier commit est-il approuvé après avoir été poussé (`require_last_push_approval`)?
> * Toutes les conversations sont-elles résolues?
> * Y a-t-il un déploiement réussi sur `develop` pour cette référence?

> **J'ai poussé un commit et mes approbations ont disparu**
>
> C'est le comportement de `dismiss_stale_reviews_on_push`. Chaque nouveau push invalide les revues. Vos relecteurs doivent réapprouver après votre dernier commit.

> **Erreur : required deployment not found**
>
> La PR exige un déploiement réussi sur l'environnement `develop`. Vérifiez que le pipeline CI a bien publié l'image, que argocd-image-updater l'a détectée, et que ArgoCD a marqué le déploiement comme réussi.

> **Un changement sans auteur clair bloque le merge**
>
> Le paramètre `require_extra_approval_for_unattributed_changes` exige une approbation supplémentaire pour tout commit dont l'auteur ne peut pas être rattaché à un membre de l'organisation (typiquement, un commit fait par un compte non lié à GitHub). Faites approuver une fois de plus, ou réécrivez le commit avec l'auteur correct avant la protection.

## Manifeste GitHub complet

Le ruleset est versionné et applicable par API. Voici le manifeste tel qu'il existe aujourd'hui sur le dépôt `sema`:

```json production-grade.json expandable theme={null}
{
  "id": 5295986,
  "name": "production-grade",
  "target": "branch",
  "source_type": "Repository",
  "source": "kaeyros-analytics-org/sema",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "exclude": [],
      "include": [
        "refs/heads/production",
        "refs/heads/staging"
      ]
    }
  },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 2,
        "dismiss_stale_reviews_on_push": true,
        "required_reviewers": [],
        "require_code_owner_review": true,
        "dismissal_restriction": {
          "enabled": false,
          "allowed_actors": []
        },
        "require_last_push_approval": true,
        "required_review_thread_resolution": true,
        "require_extra_approval_for_unattributed_changes": true,
        "allowed_merge_methods": ["merge", "squash", "rebase"]
      }
    },
    { "type": "update" },
    {
      "type": "required_deployments",
      "parameters": {
        "required_deployment_environments": ["develop"]
      }
    }
  ],
  "bypass_actors": [
    { "actor_id": null, "actor_type": "OrganizationAdmin", "bypass_mode": "always" },
    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" }
  ]
}
```

## Généraliser le ruleset

> [!TIP]
>
> Ce ruleset est aujourd'hui déclaré sur le dépôt `sema`. Pour le généraliser aux autres dépôts applicatifs, exportez-le puis appliquez-le via l'API GitHub sur chaque dépôt cible, ou déclarez-le au niveau de l'organisation pour couvrir plusieurs dépôts avec une seule règle.

Contact pour toute question sur la protection des branches ou la conformité: [devops@kaeyros-analytics.com](mailto:devops@kaeyros-analytics.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.