Integrazione GitHub Actions

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

Tutte le action sono pubblicate su archyl-com/actions e versionate con @v1.

Prerequisiti

Prima di usare le action ti servono:

1. Una chiave API Archyl -- Vai su Profilo > Chiavi API e creane una con scope di scrittura
2. Un ID organizzazione -- Si trova nella pagina delle impostazioni dell'organizzazione
3. Un ID progetto -- Si trova nell'URL o nella pagina delle impostazioni del progetto
4. Salva questi valori come secret e variabili di GitHub:

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

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

Avvio rapido

Il modo più veloce per iniziare sono i workflow riutilizzabili di Archyl: uno per le PR e uno per i push sul branch 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 }}

In questo modo ottieni un ciclo completo di governance architetturale: le regole di conformità validano ogni PR, il punteggio di drift misura quanto il codice corrisponde al modello e, al merge, il modello resta sincronizzato automaticamente.

Action singole

Conformance Check

Esegue le regole di conformità sui file modificati in una pull request. Annota le violazioni direttamente nel codice e pubblica un commento di riepilogo sulla 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 }}

Input

Output

Usare gli output

- 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

Calcola il punteggio di drift dell'architettura, cioè quanto il tuo codebase corrisponde al modello C4. Facoltativamente applica un quality gate facendo fallire la build se il punteggio scende sotto una soglia.

- 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

Input

Output

Generate Context

Genera un file archyl.txt con il contesto della tua architettura, ottimizzato per agenti IA e LLM. Può eseguire automaticamente il commit del file quando cambia.

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

Input

Output

Auto CR

Crea automaticamente una richiesta di modifica architetturale in Archyl quando il codice viene unito in main. Analizza il diff per rilevare le modifiche rilevanti per l'architettura e le traccia per la revisione.

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

Input

Output

Release

Crea o aggiorna una release in Archyl dalla tua pipeline CI. Traccia i deployment, associali ad ambienti ed elementi C4 e alimenta le tue metriche DORA.

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

Input

Output

Sync

Sincronizza il tuo file DSL archyl.yaml con Archyl. Dichiara la tua architettura come codice e invia le modifiche a ogni commit.

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

Input

Output

Workflow riutilizzabili

Archyl fornisce due workflow riutilizzabili che combinano più action per gli scenari più comuni.

archyl-pr.yml

Esegue in parallelo conformance check e drift score su ogni 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 }}

Tutti gli input sono facoltativi tranne organization-id, project-id e api-key.

archyl-main.yml

Esegue generate-context, sync e release al push su main. Ogni job può essere attivato o disattivato in modo indipendente.

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

Altre piattaforme CI

GitLab CI

Archyl fornisce un template CI includibile per GitLab. Esegue conformance check e drift score sulle merge request e genera il contesto ai push sul branch predefinito.

Configurazione:

1. Aggiungi le variabili CI/CD richieste in Settings > CI/CD > Variables:

   • ARCHYL_API_KEY (masked, protected)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Includi il template nel tuo .gitlab-ci.yml:

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

Questo aggiunge tre job alla tua pipeline:

• archyl:conformance -- eseguito sulle merge request
• archyl:drift-score -- eseguito sulle merge request
• archyl:generate-context -- eseguito ai push sul branch predefinito

Variabili facoltative: ARCHYL_API_URL, ARCHYL_DRIFT_THRESHOLD.

Bitbucket Pipelines

Copia il template delle pipeline di Archyl nel tuo bitbucket-pipelines.yml.

Configurazione:

1. Aggiungi le variabili di repository richieste in Settings > Repository variables:

   • ARCHYL_API_KEY (secured)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Aggiungi gli step della 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

Il template completo è disponibile su archyl-com/actions/ci-templates/bitbucket/archyl-pipelines.yml.

Esempio combinato

Un workflow completo che usa insieme tutte e sei le action:

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

Visualizzare i risultati

I risultati di tutti i controlli avviati dalla CI compaiono in Archyl:

• Controlli di conformità -- visibili nella dashboard di conformità (scheda Hub Agenti > Dashboard). Clicca su un controllo per vedere le violazioni raggruppate per file.
• Punteggi di drift -- visibili nella sezione Drift del progetto. Segui l'andamento del punteggio nel tempo.
• Richieste di modifica -- visibili nella sezione Richieste. Revisiona le modifiche all'architettura prima di accettarle.
• Release -- visibili nella sezione Release e nella pagina Ambienti. Alimentano le tue metriche DORA.
• Risultati della sincronizzazione -- applicati immediatamente al tuo modello C4.

Vedi Regole di conformità per maggiori dettagli sulla dashboard di conformità.

Archyl self-hosted

Se esegui Archyl on-premise, imposta l'input api-url di qualsiasi action in modo che punti alla tua istanza:

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

Il valore predefinito per tutte le action è https://api.archyl.com.