Intégration GitHub Actions

Archyl fournit six GitHub Actions officielles qui intègrent la gouvernance architecturale directement dans votre pipeline CI/CD.

Toutes les actions sont publiées sous archyl-com/actions et versionnées avec @v1.

Prérequis

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

1. Une clé API Archyl — Allez dans Profil > Clés API et créez-en une avec le scope d'écriture
2. Un ID d'organisation — Disponible sur la page des paramètres de votre organisation
3. Un ID de projet — Disponible dans l'URL ou sur la page des paramètres de votre projet
4. Stockez ces valeurs comme secrets et variables GitHub :

Settings > Secrets > Actions:
  ARCHYL_API_KEY       # Your API key (secret)

Settings > Variables > Actions:
  ARCHYL_ORG_ID        # Organization UUID
  ARCHYL_PROJECT_ID    # Project UUID

Démarrage rapide

Le moyen le plus rapide de démarrer est d'utiliser les workflows réutilisables d'Archyl — un pour les PR, un pour les pushes sur la branche main :

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

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

jobs:
  # Conformance check + drift score on PRs (run in parallel)
  pr-checks:
    if: github.event_name == 'pull_request'
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

  # Generate context + sync + release on merge to main
  main-sync:
    if: github.event_name == 'push'
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      sync: true
      release: true
      release-environment: 'production'
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

Vous obtenez ainsi une boucle complète de gouvernance architecturale : les règles de conformité valident chaque PR, le score de dérive mesure l'écart entre votre code et le modèle, et au merge le modèle reste synchronisé automatiquement.

Actions individuelles

Conformance Check

Évalue vos règles de conformité sur les fichiers modifiés dans une pull request. Annote les violations directement dans le code et publie un commentaire de synthèse sur la PR.

- uses: archyl-com/actions/conformance-check@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Entrées

Sorties

Utiliser les sorties

- uses: archyl-com/actions/conformance-check@v1
  id: conformance
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    fail-on: none  # Don't fail, handle manually

- name: Custom handling
  if: steps.conformance.outputs.status == 'fail'
  run: |
    echo "Found ${{ steps.conformance.outputs.total-violations }} violations"
    echo "Errors: ${{ steps.conformance.outputs.errors }}"
    echo "Warnings: ${{ steps.conformance.outputs.warnings }}"

Drift Score

Calcule le score de dérive architecturale — le degré de correspondance entre votre codebase et votre modèle C4. Peut en option appliquer un seuil de qualité en faisant échouer le build si le score passe sous un seuil donné.

- uses: archyl-com/actions/drift-score@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    threshold: 70

Entrées

Sorties

Generate Context

Génère un fichier archyl.txt contenant votre contexte architectural, optimisé pour les agents IA et les LLM. Peut commiter automatiquement le fichier lorsqu'il change.

- uses: archyl-com/actions/generate-context@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    commit: 'true'

Entrées

Sorties

Auto CR

Crée automatiquement une demande de changement d'architecture dans Archyl lorsque du code est mergé sur main. Analyse le diff pour détecter les modifications qui touchent l'architecture et les suit pour relecture.

- uses: archyl-com/actions/auto-cr@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Entrées

Sorties

Release

Crée ou met à jour une release dans Archyl depuis votre pipeline CI. Suivez vos déploiements, associez-les à des environnements et à des éléments C4, et alimentez vos métriques DORA.

- uses: archyl-com/actions/release@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    status: deployed
    environment: production

Entrées

Sorties

Sync

Synchronise votre fichier DSL archyl.yaml avec Archyl. Déclarez votre architecture sous forme de code et poussez les modifications à chaque commit.

- uses: archyl-com/actions/sync@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Entrées

Sorties

Workflows réutilisables

Archyl fournit deux workflows réutilisables qui combinent plusieurs actions pour les scénarios courants.

archyl-pr.yml

Exécute la vérification de conformité et le score de dérive en parallèle sur chaque pull request.

jobs:
  archyl:
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70        # Fail if drift score drops below 70
      fail-on: error              # Fail on error-level conformance violations
      comment-on-pr: true         # Post PR comments with results
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

Toutes les entrées sont optionnelles sauf organization-id, project-id et api-key.

archyl-main.yml

Exécute generate-context, sync et release lors d'un push sur main. Chaque job peut être activé ou désactivé indépendamment.

jobs:
  archyl:
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      generate-context: true       # Generate and auto-commit archyl.txt
      context-format: markdown     # LLM-optimized format
      sync: true                   # Sync archyl.yaml to Archyl
      sync-file: archyl.yaml       # Path to your archyl.yaml
      release: true                # Create a release record
      release-status: deployed
      release-environment: production
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

Autres plateformes CI

GitLab CI

Archyl fournit un template CI à inclure pour GitLab. Il exécute la vérification de conformité et le score de dérive sur les merge requests, et génère le contexte lors des pushes sur la branche par défaut.

Configuration :

1. Ajoutez les variables CI/CD requises dans Settings > CI/CD > Variables :

   • ARCHYL_API_KEY (masquée, protégée)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Incluez le template dans votre .gitlab-ci.yml :

include:
  - remote: 'https://raw.githubusercontent.com/archyl-com/actions/main/ci-templates/gitlab/.archyl-ci.yml'

Cela ajoute trois jobs à votre pipeline :

• archyl:conformance — s'exécute sur les merge requests
• archyl:drift-score — s'exécute sur les merge requests
• archyl:generate-context — s'exécute lors des pushes sur la branche par défaut

Variables optionnelles : ARCHYL_API_URL, ARCHYL_DRIFT_THRESHOLD.

Bitbucket Pipelines

Copiez le template de pipelines Archyl dans votre bitbucket-pipelines.yml.

Configuration :

1. Ajoutez les variables de dépôt requises dans Settings > Repository variables :

   • ARCHYL_API_KEY (sécurisée)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Ajoutez les étapes du pipeline :

pipelines:
  pull-requests:
    '**':
      - step:
          name: "Archyl Conformance Check"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq git
            - # ... conformance check script
      - step:
          name: "Archyl Drift Score"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq
            - # ... drift score script

  branches:
    main:
      - step:
          name: "Archyl Generate Context"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq git
            - # ... generate context script

Le template complet est disponible sur archyl-com/actions/ci-templates/bitbucket/archyl-pipelines.yml.

Exemple combiné

Un workflow complet qui utilise les six actions ensemble :

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

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

jobs:
  # --- PR checks (parallel) ---

  conformance:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/conformance-check@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  drift:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          threshold: 70
          comment-on-pr: 'true'

  # --- Main branch (after merge) ---

  generate-context:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/generate-context@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          commit: 'true'

  sync:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  auto-cr:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: archyl-com/actions/auto-cr@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  release:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/release@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          status: deployed
          environment: production
          source-url: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}

Consulter les résultats

Les résultats de toutes les vérifications déclenchées par la CI apparaissent dans Archyl :

• Vérifications de conformité — visibles dans le tableau de bord de conformité (onglet Hub Agent > Tableau de bord). Cliquez sur une vérification pour voir ses violations regroupées par fichier.
• Scores de dérive — visibles dans la section Dérive de votre projet. Suivez l'évolution du score dans le temps.
• Demandes de changement — visibles dans la section Requêtes. Relisez les modifications d'architecture avant de les accepter.
• Releases — visibles dans la section Releases et sur la page Environnements. Alimentent vos métriques DORA.
• Résultats de synchronisation — reflétés immédiatement dans votre modèle C4.

Consultez Règles de conformité pour plus de détails sur le tableau de bord de conformité.

Archyl auto-hébergé

Si vous exécutez Archyl sur site, définissez l'entrée api-url de n'importe quelle action pour pointer vers votre instance :

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

La valeur par défaut est https://api.archyl.com pour toutes les actions.