Integration GitHub Actions

Archyl fournit deux GitHub Actions officielles qui integrent la gouvernance architecturale directement dans votre pipeline CI/CD :

Prerequis

Avant d'utiliser les actions, vous avez besoin de :

1. Une cle API Archyl — Allez dans Profile > API Keys et creez-en une avec le scope d'ecriture
2. Un Project ID — Disponible dans l'URL ou la page des parametres de votre projet
3. Stockez la cle API comme secret GitHub : Settings > Secrets > Actions > ARCHYL_API_KEY
4. Optionnellement, stockez l'ID du projet comme variable : Settings > Variables > Actions > ARCHYL_PROJECT_ID

Action Conformance Check

Execute vos regles de conformite a chaque pull request et signale les violations sous forme de commentaires de PR et de statuts de commit.

Configuration rapide

# .github/workflows/archyl-conformance.yml
name: Architecture Conformance

on:
  pull_request:
    branches: [main]

jobs:
  conformance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl/archyl/.github/actions/conformance-check@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Fonctionnement

1. L'action collecte tous les fichiers modifies dans la PR
2. Le contenu des fichiers est recupere au SHA head
3. Les fichiers et leur contenu sont envoyes a l'API Archyl pour evaluation
4. Toutes les regles de conformite activees sont evaluees sur les fichiers modifies
5. Un statut de commit est publie (succes/echec)
6. Un commentaire de PR est publie avec les details des violations
7. Le workflow echoue si des violations critiques ou hautes sont trouvees

Commentaire de PR

Lorsque des violations sont trouvees, Archyl publie un commentaire comme celui-ci :

Archyl Conformance Check — Failed

12 fichier(s) analyses — 3 violation(s) trouvee(s).

Severite	Nombre
Critical	1
High	2

Le commentaire est mis a jour lors des pushes suivants — il ne cree pas de commentaires en double.

Entrees

Sorties

Utilisation des sorties

Vous pouvez utiliser les sorties dans les etapes suivantes :

- uses: archyl/archyl/.github/actions/conformance-check@main
  id: archyl
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    fail-on-violations: "false"  # Ne pas echouer, gerer manuellement

- name: Custom handling
  if: steps.archyl.outputs.passed == 'false'
  run: |
    echo "Found ${{ steps.archyl.outputs.violations }} violations"
    echo "Critical: ${{ steps.archyl.outputs.critical }}"
    echo "High: ${{ steps.archyl.outputs.high }}"

Action Incremental Discovery

Analyse les fichiers modifies lors d'un push sur la branche par defaut et cree des decouvertes en attente pour maintenir votre modele C4 a jour.

Configuration rapide

# .github/workflows/archyl-discovery.yml
name: Architecture Sync

on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Requis pour git diff
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Fonctionnement

1. L'action calcule le diff git entre le commit precedent et le commit actuel
2. Le contenu des fichiers modifies est recupere au SHA head
3. Les fichiers sont envoyes a l'API Archyl pour analyse IA
4. Seuls les fichiers source sont analyses (fichiers de test, code genere, etc. sont ignores)
5. Les nouveaux elements C4 sont crees comme decouvertes en attente pour votre revision
6. Les elements existants sont automatiquement dedupliques — pas de doublons
7. Un resume d'etape est publie avec le statut du job de decouverte

Entrees

Sorties

Notes importantes

• fetch-depth: 2 est requis dans l'etape checkout pour que git puisse calculer le diff
• La decouverte cree des elements en attente — ils n'apparaitront pas dans votre modele C4 avant approbation
• Seuls les fichiers source sont analyses (.go, .ts, .py, .java, etc.) — les fichiers de config, docs et assets sont ignores
• L'action fonctionne avec les evenements push et pull_request

Workflow combine

La configuration recommandee utilise les deux actions ensemble — conformite sur les PR, decouverte sur les merges :

# .github/workflows/archyl.yml
name: Archyl Architecture

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  # Executer les verifications de conformite sur chaque PR
  conformance:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl/archyl/.github/actions/conformance-check@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  # Synchroniser le modele d'architecture a chaque merge sur main
  discovery:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Cela vous donne une boucle complete de gouvernance architecturale :

1. Un developpeur ouvre une PR
2. Les regles de conformite valident les modifications contre votre architecture
3. Les violations sont signalees dans les commentaires de PR
4. Une fois approuvee et mergee, la decouverte incrementale met a jour le modele C4
5. Le modele est toujours a jour pour la prochaine verification de PR

Archyl auto-heberge

Si vous executez Archyl sur site, definissez l'entree api-url vers votre instance :

- uses: archyl/archyl/.github/actions/conformance-check@main
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    api-url: "https://archyl.internal.company.com/api/v1"

Alternative par Webhook

Si vous preferez les webhooks aux GitHub Actions, vous pouvez configurer des webhooks push/PR directement dans les parametres de votre projet. Consultez Webhooks pour plus de details.

L'approche webhook :

• Ne necessite aucune configuration de GitHub Action
• Utilise le token OAuth du proprietaire du projet pour l'acces API
• Supporte GitHub et GitLab
• S'execute sur l'infrastructure d'Archyl (pas de minutes GitHub Action utilisees)

L'approche GitHub Action :

• Utilise votre propre cle API (plus explicite)
• S'execute sur l'infrastructure de GitHub
• Plus facile a personnaliser (ajouter des conditions, filtrer des chemins, combiner avec d'autres etapes)
• Fonctionne avec tout fournisseur Git qui supporte les GitHub Actions