GitHub Compliance : Automatisez la conformité de vos repositories

Gérer des dizaines, voire des centaines de repositories GitHub peut rapidement devenir un cauchemar, surtout quand il s'agit de maintenir une cohérence dans les configurations de sécurité et les bonnes pratiques. C'est pour répondre à ce défi que j'ai développé GitHub Compliance, un CLI open-source qui automatise la vérification et l'application des politiques de conformité sur vos repositories.

Le problème : la jungle des configurations

Dans une organisation GitHub typique, on se retrouve rapidement avec :

• Des protections de branches incohérentes
• Des configurations de sécurité variables selon les équipes
• Des méthodes de merge différentes pour chaque projet
• Des permissions d'équipe mal configurées
• Des repositories archivés mais toujours accessibles

Maintenir manuellement la cohérence de toutes ces configurations est chronophage et source d'erreurs. C'est là qu'intervient GitHub Compliance.

Une solution automatisée et flexible

GitHub Compliance est un outil en ligne de commande qui scanne automatiquement vos repositories et vérifie leur conformité selon des règles que vous définissez. Plus qu'un simple outil de reporting, il peut également corriger automatiquement les écarts détectés lorsque vous l'exécutez sans le mode --dry-run.

Les points de contrôle principaux

L'outil vérifie actuellement cinq aspects critiques :

1. Protection des branches : S'assure que vos branches principales sont protégées avec les bonnes règles
2. Analyse de sécurité : Vérifie l'activation de Dependabot, du secret scanning et des recommandations de code scanning
3. Méthodes de merge : Contrôle les stratégies de merge autorisées
4. Permissions des équipes : Valide les accès des équipes aux repositories et peut retirer les collaborateurs individuels
5. Gestion des archives : Identifie les repositories archivés nécessitant une attention

Configuration simple et puissante

La configuration se fait via un fichier YAML (par exemple .github/compliance.yml). Voici un exemple concret basé sur la configuration de référence :

version: 1

defaults:
  merge_methods:
    allow_merge_commit: false
    allow_squash_merge: true
    allow_rebase_merge: false

  branch_protection:
    patterns: ["main", "master", "release/*"]
    enforce_admins: true
    required_reviews:
      dismiss_stale_reviews: true
      required_approving_review_count: 2
      require_code_owner_reviews: true
      require_last_push_approval: false
    required_status_checks:
      auto_discover: true
      contexts: []
      strict: true
    restrictions:
      teams: ["admin-team"]
      users: []
    allow_force_pushes: false
    allow_deletions: false
    required_conversation_resolution: true
    lock_branch: false
    allow_fork_syncing: false

  security:
    secret_scanning: "enabled"
    secret_scanning_push_protection: "enabled"
    dependabot_alerts: true
    dependabot_updates: true
    code_scanning_recommended: true

  permissions:
    remove_individual_collaborators: true
    teams:
      - team: "admin-team"
        permission: "admin"
      - team: "developers"
        permission: "write"
      - team: "reviewers"
        permission: "triage"

  archived_repos:
    admin_team_only: true

Règles spécifiques par repository

Vous pouvez également définir des règles spécifiques pour certains repositories :

rules:
  - match:
      repositories: ["frontend-*"]
    apply:
      branch_protection:
        patterns: ["main", "staging"]
        required_reviews:
          required_approving_review_count: 1  # Moins de reviewers pour les projets frontend

  - match:
      repositories: ["backend-*", "*-api"]
    apply:
      security:
        code_scanning_recommended: true
        dependabot_updates: true

Installation et intégration CI/CD

L'exécution du CLI est simple. Une fois le package publié, vous pourrez l'installer globalement :

npm install -g @flemzord/github-compliance
github-compliance-cli --config .github/compliance.yml --token $GITHUB_TOKEN --dry-run

En attendant, vous pouvez le lancer directement depuis le repository en utilisant npm run cli ou npx :

npm install
npm run cli -- --config .github/compliance.yml --token $GITHUB_TOKEN --dry-run
# ou
npx tsx src/cli.ts --config .github/compliance.yml --token $GITHUB_TOKEN --dry-run

Et pour l'intégrer dans GitHub Actions :

name: Compliance Check

on:
  schedule:
    - cron: '0 8 * * 1'
  workflow_dispatch:

jobs:
  compliance:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @flemzord/github-compliance
      - name: Run Compliance CLI
        run: github-compliance-cli --config .github/compliance.yml --token ${{ secrets.COMPLIANCE_TOKEN }} --dry-run

Les modes d'exécution

Le CLI supporte deux modes principaux :

• Mode reporting (--dry-run) : Génère un rapport détaillé sans modifier les repositories
• Mode correction (sans --dry-run) : Applique automatiquement les corrections nécessaires

Rapports détaillés et actionables

L'outil génère deux types de rapports :

Rapport JSON

Un rapport structuré pour l'intégration avec d'autres outils :

{
  "scan_date": "2025-09-15T10:00:00Z",
  "total_repositories": 45,
  "compliant_repositories": 38,
  "non_compliant_repositories": 7,
  "violations": [
    {
      "repository": "my-api",
      "rule": "branch_protection",
      "branch": "main",
      "expected": {
        "required_reviews": 2
      },
      "actual": {
        "required_reviews": 0
      },
      "severity": "high"
    }
  ]
}

Rapport Markdown

Un rapport lisible directement dans GitHub :

# Compliance Report - 2025-09-15

## Summary
- ✅ Compliant repositories: 38/45 (84%)
- ⚠️ Non-compliant repositories: 7

## Violations by Severity
- 🔴 High: 3
- 🟡 Medium: 8
- 🟢 Low: 2

## Detailed Violations
...

Cas d'usage concrets

1. Standardisation post-acquisition

Après l'acquisition d'une entreprise, utilisez le CLI pour aligner rapidement tous les nouveaux repositories sur vos standards.

2. Audit de sécurité régulier

Programmez des scans hebdomadaires pour détecter les dérives de configuration et maintenir un niveau de sécurité constant.

3. Onboarding de nouvelles équipes

Assurez-vous que les nouveaux projets respectent dès le départ vos conventions et politiques.

4. Conformité réglementaire

Documentez automatiquement le respect de vos politiques pour les audits de conformité.

Performance et limites

Le CLI est conçu pour être performant :

• Traitement parallèle des repositories
• Gestion intelligente des rate limits de l'API GitHub
• Cache des résultats pour éviter les appels inutiles
• Support jusqu'à 1000 repositories par scan

Sécurité et permissions

Le CLI nécessite un token GitHub avec les permissions suivantes :

• repo : Pour lire et modifier les configurations
• admin:org : Pour gérer les permissions d'équipe
• workflow : Pour créer des issues de non-conformité

Important : Utilisez toujours des secrets GitHub pour stocker votre token et limitez ses permissions au strict nécessaire.

Roadmap et contributions

Le projet est activement maintenu et de nouvelles fonctionnalités sont en développement :

• Publication du package npm et du binaire autonome
• Support des GitHub Apps pour une meilleure gestion des permissions
• Intégration avec Slack/Teams pour les notifications
• Dashboard web pour visualiser l'historique de conformité
• Support des règles custom via plugins

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une PR sur le repository GitHub.

Conclusion

GitHub Compliance transforme la gestion de la conformité de vos repositories d'une tâche manuelle fastidieuse en un processus automatisé et fiable. Que vous gériez une petite organisation ou des centaines de repositories, cet outil vous aide à maintenir des standards élevés de sécurité et de qualité.

L'automatisation de la conformité n'est pas qu'une question d'efficacité - c'est aussi un moyen de libérer vos équipes pour qu'elles se concentrent sur ce qui compte vraiment : créer de la valeur plutôt que de gérer des configurations.

Essayez-le dès aujourd'hui et rejoignez la communauté des utilisateurs qui ont déjà simplifié leur gestion GitHub !