CI/CD-Pipeline-Diagramm: Vom Commit bis in die Produktion, Schritt für Schritt

Frag nach einem CI/CD-Diagramm, und du bekommst meist eine Reihe von Kästen: Build, Test, Deploy. Das ist nicht falsch, beantwortet aber fast keine der Fragen, die Leute an so ein Diagramm haben. Was genau wird deployt? Wer darf in die Produktion pushen? Wo sind die Freigaben? Wie rollen wir zurück, und woran erkennen wir, dass es nötig ist?

Dieser Guide zeigt, wie du ein CI/CD-Pipeline-Diagramm zeichnest, das diese Fragen beantwortet. Als Beispiel dient ein verbreitetes Setup: Pull Requests im GitHub-Stil, eine Container-Registry und GitOps-Deployments nach Kubernetes mit Argo CD. Die Regeln gelten für andere Tools genauso.

Was ein Pipeline-Diagramm zeigen sollte

• Trigger. Was jeden Teil startet: ein Pull Request, ein Merge in main, ein Tag, ein Zeitplan.
• Stages und ihre Reihenfolge. Lint, Test, Build, Scan, Deploy, Verifikation.
• Artefakte. Das, was zwischen den Stages weitergegeben wird, meist ein Container-Image. Zeig, wie es identifiziert wird: über ein Tag oder, besser, über einen Digest.
• Umgebungen. Wo das Artefakt läuft und in welcher Reihenfolge es dorthin gelangt.
• Gates. Manuelle Freigaben, Pflicht-Checks und Policies, die eine Änderung stoppen.
• Zugangsdaten. Welches System welche Umgebung ändern darf.
• Feedback. Wie Signale aus der Produktion ein fehlerhaftes Release stoppen oder zurückrollen.

Eine Reihe von Stages deckt die ersten beiden Punkte ab. Um den Rest geht es bei Incidents und Audits.

Das Beispiel: GitOps nach Kubernetes

1. Eine Entwicklerin öffnet einen Pull Request im App-Repository.
2. CI läuft bei jedem Push: Lint, Unit-Tests, Image bauen, Image scannen. Bei einem Merge in main pusht CI das Image in die Registry und hält seinen Digest fest.
3. Danach committet CI den neuen Image-Digest in das Staging-Overlay eines separaten Config-Repositorys.
4. Argo CD im Staging-Cluster bemerkt den Commit, holt die Konfiguration und synchronisiert den Cluster.
5. Für die Promotion öffnet jemand einen Pull Request, der die Referenz ins Produktions-Overlay kopiert. Ein Pflicht-Review ist das Freigabe-Gate.
6. Nach dem Merge synchronisiert Argo CD in der Produktion, und Argo Rollouts, ein separater Controller im Cluster, rollt die neue Version als Canary aus: zuerst für einen kleinen Teil des Traffics, dann für den gesamten.
7. Während des Canary-Releases führt Argo Rollouts eine Analyse auf Basis von Prometheus-Metriken aus. Schlägt die Analyse fehl, wird der Rollout abgebrochen und der Traffic zurück auf die stabile Version geleitet, und Alerts alarmieren die Rufbereitschaft.

Zwei Details in diesem Diagramm übersieht man leicht, dabei sind sie sehr wichtig. CI spricht nie mit einem Cluster, sondern pusht nur das Image in die Registry und committet nach Git. Und die Produktion ändert sich nur über einen reviewten Commit. Genau so rollst du auch zurück: Commit reverten, und Argo CD synchronisiert die vorherige Version.

Push oder Pull: Zeichne, wo die Zugangsdaten liegen

In einer Push-basierten Pipeline hat CI Zugangsdaten für den Cluster und führt den Deploy-Befehl selbst aus. In einem Pull-basierten GitOps-Setup holt ein Agent in jedem Cluster, etwa Argo CD oder Flux, den gewünschten Zustand aus Git und wendet ihn an. So braucht nichts außerhalb des Clusters Schreibzugriff darauf.

Beides ist legitim, und das Diagramm sollte die Entscheidung offensichtlich machen. Bei Push zeichnest du eine Kante von CI zu jedem Cluster und beschriftest sie mit den Zugangsdaten, die dabei verwendet werden. Bei Pull zeichnest du, wie das Config-Repository den Agenten in jedem Cluster versorgt, und keine Kante von CI zu irgendeinem Cluster. Reviewer sehen dann auf einen Blick, wie weit der Schaden eines geleakten CI-Secrets reichen würde.

Wenn CI Cloud-Zugriff braucht, etwa um Images zu pushen, notiere, wie CI an diesen Zugriff kommt. Kurzlebige Tokens über OpenID Connect machen auf einem Diagramm eine bessere Figur als ein langlebiger Schlüssel, der als Secret gespeichert ist.

Regeln für ein lesbares Pipeline-Diagramm

Mach das Artefakt sichtbar

Beschrifte die Kante in die Registry mit dem Artefakt und der Angabe, wie es identifiziert wird: image shop-api, by digest. Tags lassen sich verschieben; ein Digest zeigt immer auf dasselbe Image. Wenn du zusätzlich eine SBOM oder eine Signatur erzeugst, zeig sie neben dem Image.

Zeichne Umgebungen als Rahmen

Jede Umgebung ist ein Rahmen, in dem ihr Deploy-Agent und ihr Cluster liegen. Die Reihenfolge der Rahmen zeigt den Promotion-Pfad, und alles, was einen Rahmen überspringt, fällt sofort auf.

Gib Gates einen eigenen Node

Eine Freigabe ist ein Schritt mit einer verantwortlichen Person, kein Label an einem Pfeil. Zeichne sie als Node zwischen den Umgebungen und schreib dazu, wer freigibt: approve: release manager oder 2 reviews required.

Schließ den Kreis

Eine Pipeline, die bei „Deploy“ endet, hat kein Feedback. Zeichne, was die Produktion überwacht und was es auslösen kann: ein Canary-Release stoppen, jemanden alarmieren, einen Rollback starten.

Lass Job-Details in der CI-Datei

Zwölf parallele Test-Jobs gehören in die CI-Konfiguration. Im Diagramm reicht ein Stage-Node mit einem kurzen Label (lint, test, build, scan).

Häufige Fehler

• Kein Artefakt. Kästen, verbunden durch Pfeile, die nichts Bestimmtes transportieren. Wer das Diagramm liest, sieht nicht, was von Umgebung zu Umgebung weitergereicht wird.
• Umgebungen als Stages. „Deploy Staging“ und „Deploy Prod“ als zwei Kästen in einer Reihe verschleiern, dass es verschiedene Orte mit verschiedenen Berechtigungen sind.
• Fehlender Rollback-Pfad. Wenn niemand im Diagramm darauf zeigen kann, wurde er wahrscheinlich nie getestet.
• Jeder Job als Node. Das Diagramm wird zum CI-Log.
• Tools statt Verantwortlichkeiten. Ein Kasten mit einem Produktnamen sagt weniger als build and scan image.

In Archboard nachbauen

1. Melde dich mit Google oder GitHub an und leg ein Diagramm an.
2. Füge aus dem DevOps-Pack Nodes vom Typ Code-Repository für das App- und das Config-Repository hinzu, dazu eine CI/CD-Pipeline für CI. Ergänze aus dem Docker-Pack eine Container-Registry.
3. Füge für jede Umgebung einen Rahmen aus dem Basis-Pack hinzu und setze einen Node Bereitstellung aus dem DevOps-Pack für Argo CD (in der Produktion auch für Argo Rollouts) sowie einen Kubernetes-Cluster aus dem Cloud-Pack hinein.
4. Füge für das Freigabe-Gate eine Raute aus dem Basis-Pack hinzu.
5. Füge aus dem DevOps-Pack die Nodes Metriken und Alarm hinzu und aus dem C4-Modell-Pack Nodes vom Typ Person für die Entwicklerin und die Rufbereitschaft.
6. Verbinde die Ports, beschrifte jede Kante mit dem, was darüber fließt, und mach die Feedback-Kante gestrichelt.

Das Beispiel nutzt 15 Diagramm-Nodes, das Limit des Free-Plans. Für eine Pipeline mit eingebauter Observability öffne /examples/cicd-observability; für die Cluster-Seite lies wie du ein Kubernetes-Architekturdiagramm zeichnest.

FAQ

Soll ich jeden CI-Job zeichnen? Nein. Fasse Jobs zu Stages zusammen und lass die Details in der CI-Datei. Zeichne einen Job nur dann separat, wenn er ein Gate ist, etwa ein Security-Scan, der das Release blockiert.

Wie zeige ich Feature Flags? Als eigenes System neben der Produktion, mit einer Kante zu den Services, die Flags lesen. Flags ändern das Verhalten ohne Deployment, deshalb verdienen sie eine eigene Linie im Diagramm.

Wo kommen Secrets im Diagramm hin? Zeig, welches System welche Zugangsdaten wofür hält, nicht die Secrets selbst. Notiere bei CI, ob kurzlebige OIDC-Tokens oder gespeicherte Schlüssel zum Einsatz kommen.

Brauche ich ein Diagramm pro Repository? Meist eines pro Delivery-Pfad. Wenn viele Services dieselbe Pipeline teilen, zeichne sie einmal und liste die Services in einer Notiz auf.

Wie halte ich das Diagramm aktuell? Reviewe es, wenn sich die Pipeline ändert, genauso wie du die CI-Datei reviewst. Verlinke das Live-Diagramm aus dem README des Repositorys, damit es nur eine Kopie gibt.

Kostenlos starten — ein Seat, keine Kreditkarte.