GitHub Actions Integration

Archyl bietet zwei offizielle GitHub Actions, die Architektur-Governance direkt in Ihre CI/CD-Pipeline integrieren:

Voraussetzungen

Bevor Sie die Actions nutzen, benoetigen Sie:

1. Einen Archyl API-Schluessel — Gehen Sie zu Profile > API Keys und erstellen Sie einen mit Schreibberechtigung
2. Eine Project ID — In der URL oder auf der Einstellungsseite Ihres Projekts zu finden
3. Speichern Sie den API-Schluessel als GitHub Secret: Settings > Secrets > Actions > ARCHYL_API_KEY
4. Optional speichern Sie die Projekt-ID als Variable: Settings > Variables > Actions > ARCHYL_PROJECT_ID

Conformance Check Action

Fuehrt Ihre Konformitaetsregeln bei jedem Pull Request aus und meldet Verletzungen als PR-Kommentare und Commit-Status-Checks.

Schnelleinrichtung

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

Funktionsweise

1. Die Action sammelt alle in der PR geaenderten Dateien
2. Dateiinhalte werden am Head-SHA abgerufen
3. Dateien + Inhalte werden zur Auswertung an die Archyl API gesendet
4. Alle aktivierten Konformitaetsregeln werden gegen die geaenderten Dateien ausgewertet
5. Ein Commit-Status wird gepostet (bestanden/fehlgeschlagen)
6. Ein PR-Kommentar mit Verletzungsdetails wird gepostet
7. Der Workflow schlaegt fehl, wenn kritische oder hohe Verletzungen gefunden werden

PR-Kommentar

Wenn Verletzungen gefunden werden, postet Archyl einen Kommentar wie diesen:

Archyl Conformance Check — Failed

12 Datei(en) analysiert — 3 Verletzung(en) gefunden.

Schweregrad	Anzahl
Critical	1
High	2

Der Kommentar wird bei nachfolgenden Pushes aktualisiert — er erstellt keine doppelten Kommentare.

Eingaben

Ausgaben

Ausgaben verwenden

Sie koennen die Ausgaben in nachfolgenden Schritten verwenden:

- 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"  # Nicht fehlschlagen, manuell behandeln

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

Incremental Discovery Action

Analysiert geaenderte Dateien bei Push auf den Default-Branch und erstellt ausstehende Entdeckungen, um Ihr C4-Modell aktuell zu halten.

Schnelleinrichtung

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

Funktionsweise

1. Die Action berechnet den Git-Diff zwischen dem vorherigen und dem aktuellen Commit
2. Geaenderte Dateiinhalte werden am Head-SHA abgerufen
3. Dateien werden zur KI-Analyse an die Archyl API gesendet
4. Nur Quelldateien werden analysiert (Testdateien, generierter Code etc. werden uebersprungen)
5. Neue C4-Elemente werden als ausstehende Entdeckungen fuer Ihre Ueberpruefung erstellt
6. Bestehende Elemente werden automatisch dedupliziert — keine Duplikate
7. Eine Schrittzusammenfassung mit dem Entdeckungsjob-Status wird gepostet

Eingaben

Ausgaben

Wichtige Hinweise

• fetch-depth: 2 ist im Checkout-Schritt erforderlich, damit git den Diff berechnen kann
• Die Entdeckung erstellt ausstehende Elemente — sie erscheinen erst in Ihrem C4-Modell, wenn Sie sie genehmigen
• Nur Quelldateien werden analysiert (.go, .ts, .py, .java etc.) — Konfigurationsdateien, Docs und Assets werden uebersprungen
• Die Action funktioniert mit push- und pull_request-Events

Kombinierter Workflow

Die empfohlene Einrichtung verwendet beide Actions zusammen — Konformitaet bei PRs, Entdeckung bei Merges:

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

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

jobs:
  # Konformitaetspruefungen bei jedem PR ausfuehren
  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 }}

  # Architekturmodell bei jedem Merge auf main synchronisieren
  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 }}

Dies gibt Ihnen eine vollstaendige Architektur-Governance-Schleife:

1. Ein Entwickler oeffnet einen PR
2. Konformitaetsregeln validieren die Aenderungen gegen Ihre Architektur
3. Verletzungen werden als PR-Kommentare gemeldet
4. Nach Genehmigung und Merge aktualisiert die inkrementelle Entdeckung das C4-Modell
5. Das Modell ist immer aktuell fuer die naechste PR-Pruefung

Self-Hosted Archyl

Wenn Sie Archyl on-premise betreiben, setzen Sie die api-url-Eingabe auf Ihre Instanz:

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

Webhook-Alternative

Wenn Sie Webhooks gegenueber GitHub Actions bevorzugen, koennen Sie Push/PR-Webhooks direkt in Ihren Projekteinstellungen konfigurieren. Siehe Webhooks fuer Details.

Der Webhook-Ansatz:

• Erfordert keine GitHub Action-Konfiguration
• Verwendet das OAuth-Token des Projektbesitzers fuer den API-Zugriff
• Unterstuetzt GitHub und GitLab
• Laeuft auf Archyls Infrastruktur (keine GitHub Action-Minuten verbraucht)

Der GitHub Action-Ansatz:

• Verwendet Ihren eigenen API-Schluessel (expliziter)
• Laeuft auf GitHubs Infrastruktur
• Einfacher anzupassen (Bedingungen hinzufuegen, Pfade filtern, mit anderen Schritten kombinieren)
• Funktioniert mit jedem Git-Anbieter, der GitHub Actions unterstuetzt