GitHub Actions Integration

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

Alle Actions sind unter archyl-com/actions veröffentlicht und mit @v1 versioniert.

Voraussetzungen

Bevor Sie die Actions nutzen, benötigen Sie:

1. Einen Archyl-API-Schlüssel — Gehen Sie zu Profil > API-Schlüssel und erstellen Sie einen mit Schreibberechtigung
2. Eine Organisations-ID — Auf der Einstellungsseite Ihrer Organisation zu finden
3. Eine Projekt-ID — In der URL oder auf der Einstellungsseite Ihres Projekts zu finden
4. Speichern Sie diese als GitHub Secrets und Variablen:

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

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

Schnellstart

Am schnellsten starten Sie mit den wiederverwendbaren Workflows von Archyl — einer für PRs, einer für Pushes auf den main-Branch:

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

Damit erhalten Sie eine vollständige Architektur-Governance-Schleife: Konformitätsregeln validieren jeden PR, der Drift-Score misst, wie gut Ihr Code zum Modell passt, und nach dem Merge bleibt das Modell automatisch synchron.

Einzelne Actions

Conformance Check

Führt Ihre Konformitätsregeln gegen die in einem Pull Request geänderten Dateien aus. Verletzungen werden inline annotiert, und eine Zusammenfassung wird als PR-Kommentar gepostet.

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

Eingaben

Ausgaben

Ausgaben verwenden

- 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

Berechnet den Architektur-Drift-Score — also wie gut Ihre Codebasis mit Ihrem C4-Modell übereinstimmt. Optional wird ein Quality Gate durchgesetzt, indem der Build fehlschlägt, sobald der Score unter einen Schwellenwert fällt.

- 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

Eingaben

Ausgaben

Generate Context

Generiert eine archyl.txt-Datei mit Ihrem Architekturkontext, optimiert für KI-Agenten und LLMs. Die Datei kann automatisch committet werden, wenn sie sich ändert.

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

Eingaben

Ausgaben

Auto CR

Erstellt in Archyl automatisch einen Architektur-Änderungsantrag, wenn Code auf main gemergt wird. Die Action analysiert den Diff, erkennt architekturrelevante Änderungen und hält sie zur Prüfung fest.

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

Eingaben

Ausgaben

Release

Erstellt oder aktualisiert ein Release in Archyl direkt aus Ihrer CI-Pipeline. Verfolgen Sie Deployments, ordnen Sie sie Umgebungen und C4-Elementen zu und speisen Sie Ihre DORA-Metriken.

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

Eingaben

Ausgaben

Sync

Synchronisiert Ihre archyl.yaml-DSL-Datei mit Archyl. Deklarieren Sie Ihre Architektur als Code und übertragen Sie Änderungen bei jedem Commit.

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

Eingaben

Ausgaben

Wiederverwendbare Workflows

Archyl bietet zwei wiederverwendbare Workflows, die mehrere Actions für gängige Szenarien kombinieren.

archyl-pr.yml

Führt Conformance Check und Drift Score bei jedem Pull Request parallel aus.

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

Alle Eingaben außer organization-id, project-id und api-key sind optional.

archyl-main.yml

Führt generate-context, sync und release bei einem Push auf main aus. Jeder Job lässt sich unabhängig ein- und ausschalten.

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

Andere CI-Plattformen

GitLab CI

Archyl stellt ein einbindbares CI-Template für GitLab bereit. Es führt Conformance Check und Drift Score bei Merge Requests aus und generiert bei Pushes auf den Default-Branch den Kontext.

Einrichtung:

1. Fügen Sie die erforderlichen CI/CD-Variablen unter Settings > CI/CD > Variables hinzu:

   • ARCHYL_API_KEY (masked, protected)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Binden Sie das Template in Ihre .gitlab-ci.yml ein:

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

Dadurch werden Ihrer Pipeline drei Jobs hinzugefügt:

• archyl:conformance — läuft bei Merge Requests
• archyl:drift-score — läuft bei Merge Requests
• archyl:generate-context — läuft bei Pushes auf den Default-Branch

Optionale Variablen: ARCHYL_API_URL, ARCHYL_DRIFT_THRESHOLD.

Bitbucket Pipelines

Kopieren Sie das Archyl-Pipelines-Template in Ihre bitbucket-pipelines.yml.

Einrichtung:

1. Fügen Sie die erforderlichen Repository-Variablen unter Settings > Repository variables hinzu:

   • ARCHYL_API_KEY (secured)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Fügen Sie die Pipeline-Schritte hinzu:

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

Das vollständige Template finden Sie unter archyl-com/actions/ci-templates/bitbucket/archyl-pipelines.yml.

Kombiniertes Beispiel

Ein vollständiger Workflow, der alle sechs Actions zusammen verwendet:

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

Ergebnisse ansehen

Die Ergebnisse aller in der CI ausgelösten Prüfungen erscheinen in Archyl:

• Konformitätsprüfungen — sichtbar im Konformitäts-Dashboard (Tab Agent Hub > Dashboard). Klicken Sie auf eine Prüfung, um die Verletzungen nach Datei gruppiert zu sehen.
• Drift-Scores — sichtbar im Bereich Drift Ihres Projekts. Verfolgen Sie den Verlauf des Scores über die Zeit.
• Änderungsanträge — sichtbar im Bereich Anfragen. Prüfen Sie Architekturänderungen, bevor Sie sie übernehmen.
• Releases — sichtbar im Bereich Releases und auf der Seite Umgebungen. Speist Ihre DORA-Metriken.
• Sync-Ergebnisse — werden sofort in Ihrem C4-Modell sichtbar.

Weitere Details zum Konformitäts-Dashboard finden Sie unter Konformitätsregeln.

Self-Hosted Archyl

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

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

Der Standardwert ist für alle Actions https://api.archyl.com.