Release-Management

Das Release-Management verfolgt Deployments als erstklassige Objekte in Ihrem Architektur-Workspace. Jedes Release ist mit einem C4-Element verknüpft und gibt Ihren Diagrammen eine Live-Ansicht dessen, was tatsächlich läuft.

Grundkonzepte

Releases

Ein Release repräsentiert eine bestimmte Version, die in einer Umgebung deployed wurde. Jedes Release hat:

Umgebungen

Umgebungen repräsentieren Deployment-Ziele. Sie sind benutzerdefiniert und farbcodiert.

Gängige Konfigurationen:

• Development → Staging → Production
• Dev → QA → Pre-prod → Production

Erstellen Sie so viele Umgebungen, wie Ihr Workflow erfordert. Jedes Release wird mit seiner Zielumgebung getaggt.

Status-Lebenszyklus

Releases durchlaufen diese Status:

Release-Tracking Einrichten

1. Umgebungen Erstellen

1. Gehen Sie zu den Einstellungen Ihres Projekts
2. Öffnen Sie den Tab Releases
3. Unter Umgebungen, klicken Sie auf Umgebung Hinzufügen
4. Geben Sie einen Namen ein und wählen Sie eine Farbe
5. Ziehen Sie zum Neuordnen der Umgebungen nach Deployment-Stufe

2. Ein Standard-Verknüpfungsziel Konfigurieren

Legen Sie das System und optional einen Container fest, an den Releases standardmäßig angehängt werden:

1. Finden Sie im Releases-Tab der Einstellungen Standard-Verknüpfungsziel
2. Wählen Sie ein System aus dem Dropdown
3. Wählen Sie optional einen Container innerhalb dieses Systems
4. Dieses Ziel wird verwendet, wenn eingespeiste Releases kein Element angeben

3. Eine Integrationsmethode Wählen

Archyl unterstützt drei Wege zur automatischen Release-Ingestion.

Integrationsmethoden

GitHub Actions

Fügen Sie die offizielle Archyl GitHub Action zu Ihrem Deployment-Workflow hinzu.

Minimale Konfiguration:

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}

Vollständige Konfiguration:

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}
    environment: production
    system-id: <your-system-uuid>
    container-id: <your-container-uuid>
    changelog: "Bugfixes und Performance-Verbesserungen"
    status: deployed

Die Action sendet Version, Commit-SHA, Umgebung und Changelog bei jedem erfolgreichen Deploy an Archyl.

Webhooks

Konfigurieren Sie Webhook-Ingestion, um Release-Events von GitHub oder GitLab zu empfangen.

1. Aktivieren Sie im Releases-Tab der Einstellungen Webhooks
2. Kopieren Sie die angezeigte Webhook-URL
3. Fügen Sie in GitHub oder GitLab einen neuen Webhook hinzu, der auf diese URL zeigt
4. Wählen Sie den Event-Typ Release oder Tag push

Konfigurationsoptionen:

Wenn ein neues Release veröffentlicht oder ein passender Tag gepusht wird, erstellt Archyl automatisch einen Release-Eintrag.

REST-API

Für jedes CI/CD-Tool, das HTTP-Anfragen machen kann — Jenkins, CircleCI, Bitbucket Pipelines oder benutzerdefinierte Pipelines.

Endpoint: POST /api/v1/projects/:projectId/releases

Headers:

Authorization: Bearer <api-key>
Content-Type: application/json

Payload:

{
  "version": "v2.4.0",
  "status": "deployed",
  "changelog": "Zahlungs-Retry-Logik hinzugefügt",
  "environmentId": "<environment-uuid>",
  "systemId": "<system-uuid>",
  "containerId": "<container-uuid>",
  "sourceUrl": "https://github.com/org/repo/releases/tag/v2.4.0"
}

Der Einstellungs-Tab zeigt kopierbare Code-Snippets mit automatisch ausgefüllten API-Keys und Element-IDs.

Ansichten

Release-Timeline

Die Hauptansicht. Releases werden nach Monat gruppiert, in umgekehrter chronologischer Reihenfolge. Jeder Eintrag zeigt:

• Versions-Badge
• Status-Indikator
• Umgebungs-Tag (farbcodiert)
• Verknüpftes System oder Container
• Quelle (GitHub Action, Webhook, API, manuell)
• Relativer Zeitstempel

Klicken Sie auf ein Release, um sein Detailpanel mit vollständigem Changelog, Daten und einem Link zur Quelle zu öffnen.

Filterung:

• Nach Umgebung (z.B. nur Produktions-Deploys anzeigen)
• Nach Status (z.B. nur fehlgeschlagene Deployments anzeigen)
• Nach verknüpftem Element

Deployment-Matrix

Eine Rasteransicht für Teams, die mehrere Services über mehrere Umgebungen verwalten.

• Zeilen — Systeme und Container
• Spalten — Umgebungen
• Zellen — Letztes deployetes Release für diese Kombination

Die Matrix macht Umgebungsdrift auf einen Blick sichtbar. Wenn Staging- und Produktionsversionen divergieren, erkennen Sie es sofort.

Releases mit der Architektur Verknüpfen

Jedes Release kann mit einem System, einem Container oder beidem verknüpft werden.

Automatische Verknüpfung

Bei Verwendung von GitHub Actions oder Webhooks werden Releases mit dem in den Einstellungen konfigurierten Standardziel verknüpft. Sie können das Ziel pro Release überschreiben, indem Sie system-id und container-id angeben.

Manuelle Verknüpfung

Beim Erstellen eines Releases über die Benutzeroberfläche:

1. Klicken Sie auf Neues Release
2. Füllen Sie Version, Status und Changelog aus
3. Wählen Sie das Zielsystem und/oder den Container
4. Wählen Sie die Umgebung
5. Klicken Sie auf Erstellen

Anzeige im Diagramm

Klicken Sie mit der rechten Maustaste auf ein Element im C4-Diagramm, um sein Detailpanel zu öffnen. Verknüpfte Releases erscheinen im Abschnitt Releases neben Beziehungen, ADRs und API-Verträgen. Das Element zeigt seine neueste Release-Version und Umgebung.

Releases Manuell Erstellen

Nicht jedes Release kommt aus einer Pipeline. Um ein Release manuell zu erstellen:

1. Navigieren Sie zum Tab Releases
2. Klicken Sie auf Neues Release
3. Geben Sie die Version ein, wählen Sie Status und Umgebung
4. Schreiben Sie ein Changelog (Markdown unterstützt)
5. Verknüpfen Sie mit einem System und/oder Container
6. Klicken Sie auf Erstellen

Manuelle Releases haben ihre Quelle als Manuell in der Timeline markiert.

Best Practices

Verwenden Sie Semantische Versionierung

• Taggen Sie Releases mit Semver (z.B. v1.2.3)
• Fügen Sie Pre-Release-Identifikatoren für Nicht-Produktions-Releases hinzu (z.B. v2.0.0-rc.1)
• Halten Sie Versionsstrings über Umgebungen hinweg konsistent

Verfolgen Sie Alle Umgebungen

• Erstellen Sie Umgebungen für jede Deployment-Stufe
• Überspringen Sie Staging nicht — die Deployment-Matrix ist am nützlichsten, wenn sie die vollständige Pipeline zeigt
• Nutzen Sie die Matrix-Ansicht, um Umgebungsdrift früh zu erkennen

Automatisieren Sie die Ingestion

• Verwenden Sie GitHub Actions oder Webhooks anstelle manueller Eingabe
• Richten Sie die Integration einmal ein und jedes Deployment fließt automatisch ein
• Reservieren Sie manuelle Erstellung für Hotfixes oder außergewöhnliche Deployments

Schreiben Sie Changelogs

• Fügen Sie jedem Release ein aussagekräftiges Changelog bei
• Fassen Sie zusammen, was sich geändert hat und warum
• Verlinken Sie auf zugehörige Issues oder Pull Requests, wenn möglich

Verknüpfen Sie auf der Richtigen Ebene

• Verknüpfen Sie mit Systemen beim Deployment einer gesamten Anwendung
• Verknüpfen Sie mit Containern beim Deployment einzelner Services innerhalb eines Systems
• Seien Sie konsistent — wählen Sie eine Konvention und halten Sie sich daran

Nächste Schritte

• API-Verträge — Dokumentieren Sie Ihre API-Spezifikationen
• Architektur-Insights — Erkennen Sie architektonische Probleme
• Architektur-Änderungsanträge — Schlagen Sie Änderungen über einen Review-Workflow vor