Integrazione GitHub Actions

Archyl fornisce due GitHub Actions ufficiali che integrano la governance architetturale direttamente nella tua pipeline CI/CD:

Prerequisiti

Prima di utilizzare le actions, hai bisogno di:

1. Una chiave API Archyl — Vai su Profile > API Keys e creane una con scope di scrittura
2. Un Project ID — Disponibile nell'URL o nella pagina impostazioni del progetto
3. Salva la chiave API come segreto GitHub: Settings > Secrets > Actions > ARCHYL_API_KEY
4. Opzionalmente salva l'ID del progetto come variabile: Settings > Variables > Actions > ARCHYL_PROJECT_ID

Action Conformance Check

Esegue le tue regole di conformita ad ogni pull request e segnala le violazioni come commenti PR e stati del commit.

Configurazione rapida

# .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 }}

Come funziona

1. L'action raccoglie tutti i file modificati nel PR
2. Il contenuto dei file viene recuperato allo SHA head
3. File + contenuti vengono inviati all'API Archyl per la valutazione
4. Tutte le regole di conformita abilitate vengono valutate sui file modificati
5. Viene pubblicato uno stato del commit (superato/fallito)
6. Viene pubblicato un commento PR con i dettagli delle violazioni
7. Il workflow fallisce se vengono trovate violazioni critiche o alte

Commento PR

Quando vengono trovate violazioni, Archyl pubblica un commento come questo:

Archyl Conformance Check — Failed

12 file analizzati — 3 violazione/i trovata/e.

Severita	Conteggio
Critical	1
High	2

Il commento viene aggiornato nei push successivi — non crea commenti duplicati.

Input

Output

Utilizzo degli output

Puoi usare gli output nei passaggi successivi:

- 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"  # Non fallire, gestire manualmente

- 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

Analizza i file modificati al push sul branch predefinito e crea scoperte in sospeso per mantenere il tuo modello C4 aggiornato.

Configurazione rapida

# .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  # Richiesto per git diff
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Come funziona

1. L'action calcola il diff git tra il commit precedente e quello attuale
2. Il contenuto dei file modificati viene recuperato allo SHA head
3. I file vengono inviati all'API Archyl per l'analisi AI
4. Solo i file sorgente vengono analizzati (file di test, codice generato, ecc. vengono saltati)
5. I nuovi elementi C4 vengono creati come scoperte in sospeso per la tua revisione
6. Gli elementi esistenti vengono automaticamente deduplicati — nessun duplicato
7. Viene pubblicato un riepilogo del passaggio con lo stato del job di scoperta

Input

Output

Note importanti

• fetch-depth: 2 e richiesto nel passaggio checkout affinche git possa calcolare il diff
• La scoperta crea elementi in sospeso — non appariranno nel tuo modello C4 finche non li approvi
• Solo i file sorgente vengono analizzati (.go, .ts, .py, .java, ecc.) — file di config, docs e asset vengono saltati
• L'action funziona sia con eventi push che pull_request

Workflow combinato

La configurazione consigliata usa entrambe le actions insieme — conformita sui PR, scoperta sui merge:

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

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

jobs:
  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 }}

  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 }}

Questo ti offre un ciclo completo di governance architetturale:

1. Uno sviluppatore apre un PR
2. Le regole di conformita validano le modifiche contro la tua architettura
3. Le violazioni vengono segnalate come commenti PR
4. Una volta approvato e unito, la scoperta incrementale aggiorna il modello C4
5. Il modello e sempre aggiornato per la prossima verifica PR

Archyl self-hosted

Se esegui Archyl on-premise, imposta l'input api-url alla tua istanza:

- 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"

Alternativa Webhook

Se preferisci i webhook alle GitHub Actions, puoi configurare webhook push/PR direttamente nelle impostazioni del progetto. Vedi Webhooks per i dettagli.

L'approccio webhook:

• Non richiede configurazione GitHub Action
• Usa il token OAuth del proprietario del progetto per l'accesso API
• Supporta GitHub e GitLab
• Si esegue sull'infrastruttura di Archyl (nessun minuto GitHub Action utilizzato)

L'approccio GitHub Action:

• Usa la tua chiave API (piu esplicito)
• Si esegue sull'infrastruttura di GitHub
• Piu facile da personalizzare (aggiungere condizioni, filtrare percorsi, combinare con altri passaggi)
• Funziona con qualsiasi provider Git che supporta GitHub Actions