Die neue Version Ihrer Unternehmenssoftware ist fertig. Doch kurz vor der Veröffentlichung meldet die CI/CD-Pipeline einen Fehler. Der Build bricht ab, ein Runner startet nicht oder das Deployment erreicht den Produktionsserver nicht. Das Entwicklungsteam sucht nach der Ursache, während ein wichtiges Update auf sich warten lässt. Wenn eine CI/CD-Pipeline fehlschlägt, sollte zuerst geklärt werden, an welcher Stelle der Prozess stoppt – und welche technische Ursache tatsächlich dahintersteht.
1. Woran erkennt man einen CI/CD-Pipeline-Fehler?
Eine CI/CD-Pipeline verbindet mehrere Schritte der Softwarebereitstellung. Je nach Projekt werden beispielsweise Quellcode geprüft, Anwendungen gebaut, automatisierte Tests durchgeführt und freigegebene Versionen in eine Zielumgebung übertragen.
Schlägt einer dieser Schritte fehl, wird der vorgesehene Ablauf unterbrochen. Das kann unterschiedliche Auswirkungen haben:
- Eine neue Softwareversion kann nicht veröffentlicht werden.
- Automatisierte Tests liefern keine verwertbaren Ergebnisse.
- Ein Build wird nicht abgeschlossen oder ein benötigtes Artefakt fehlt.
- Die Pipeline wartet auf einen verfügbaren Runner.
- Das Deployment wird wegen fehlender Berechtigungen abgelehnt.
- Die Anwendung erreicht die Zielumgebung, startet dort aber nicht wie erwartet.
Diese Situationen sehen im Arbeitsalltag ähnlich aus: Das Update kommt nicht an. Die Ursachen unterscheiden sich jedoch erheblich.
Deshalb sollte nicht sofort der gesamte Deployment-Prozess umgebaut werden. Zunächst muss der konkrete Fehler eingegrenzt werden.
2. Build, Runner oder Deployment: Wo liegt der Fehler?
Der erste wichtige Unterschied besteht zwischen einem Fehler im Anwendungscode und einem Problem in der technischen Umgebung, die den Release ausführt.
| Bereich | Mögliche Ursache | Was geprüft werden sollte |
|---|---|---|
| Build | Fehlende Abhängigkeit oder nicht unterstützte Softwareversion | Build-Protokoll, verwendete Laufzeit und Paketversionen |
| Automatisierte Tests | Fehlgeschlagener Test oder nicht verfügbare Testdaten | Testbericht und Unterschied zum letzten erfolgreichen Lauf |
| CI/CD-Runner | Runner nicht erreichbar oder Ausführungsumgebung fehlerhaft | Runner-Status, Zuordnung und relevante Systemprotokolle |
| Artefakte | Build-Ergebnis fehlt oder kann nicht abgerufen werden | Artefaktpfade, Abhängigkeiten, Verfügbarkeit und Zugriffsrechte |
| Deployment | Fehlender Zugriff oder falsche Zielkonfiguration | Berechtigungen, Zielumgebung und verwendete Konfiguration |
| Anwendung | Software startet nach der Bereitstellung nicht korrekt | Anwendungsprotokolle, Laufzeitumgebung und erforderliche Verbindungen |
Bei GitLab CI/CD stellt die offizielle Dokumentation zur Fehlersuche in CI/CD-Pipelines entsprechende Diagnosemöglichkeiten vor.
Ein fehlgeschlagenes Artefakt kann beispielsweise bedeuten, dass die erwartete Datei nicht erzeugt wurde, der Pfad nicht stimmt oder eine Abhängigkeit zwischen Jobs falsch konfiguriert ist. Solche Fehler müssen nicht im eigentlichen Anwendungscode liegen.
3. Was sollten Unternehmen zuerst prüfen?
Wenn ein Release blockiert ist, hilft eine kurze Bestandsaufnahme. Sie verhindert, dass mehrere Mitarbeiter gleichzeitig unterschiedliche Einstellungen verändern und damit neue Fehlerquellen schaffen.
- Betroffene Version feststellen: Welcher Commit oder welche Anwendungsversion sollte veröffentlicht werden?
- Fehlerhaften Schritt identifizieren: Stoppt der Prozess beim Build, Test, Runner oder Deployment?
- Letzten erfolgreichen Lauf vergleichen: Welche Änderungen gab es seitdem an Code, Konfiguration, Abhängigkeiten oder Infrastruktur?
- Protokolle sichern: Relevante Fehlermeldungen und Zeitpunkte dokumentieren, ohne Zugangsdaten oder Geheimnisse unnötig weiterzugeben.
- Zielumgebung kontrollieren: Prüfen, ob die vorgesehene Umgebung erreichbar ist und die benötigten Berechtigungen bestehen.
- Verantwortlichen bestimmen: Festlegen, wer Änderungen freigibt und den erneuten Release beurteilt.
Für die Diagnose ist besonders hilfreich, die erste aussagekräftige Fehlermeldung zu finden. Spätere Fehlermeldungen können lediglich Folgen eines früheren Problems sein.
Eine wiederholte Ausführung derselben Pipeline kann bei vorübergehenden Störungen sinnvoll sein. Sie ersetzt aber keine Ursachenanalyse. Bei Deployments oder anderen Schritten mit Auswirkungen auf produktive Daten sollte vor einem erneuten Start geklärt werden, welche Änderungen möglicherweise bereits erfolgt sind.
Die offizielle GitLab Runner-Dokumentation zur Fehlersuche beschreibt unter anderem Probleme beim Vorbereiten der Ausführungsumgebung und bei der Kommunikation des Runners.
4. Beispiel: Der Build ist erfolgreich, aber das Deployment scheitert
Angenommen, ein mittelständisches Unternehmen betreibt eine individuell entwickelte Anwendung zur Auftragsbearbeitung. Das Entwicklungsteam hat eine neue Funktion fertiggestellt. Build und automatisierte Tests laufen erfolgreich durch.
Der anschließende Deployment-Job schlägt jedoch fehl. In der Produktionsumgebung bleibt die bisherige Version aktiv.
Wo beginnt die Untersuchung?
Zuerst wird geprüft, ob das vorgesehene Build-Artefakt vorhanden ist und ob der Deployment-Job darauf zugreifen kann.
Danach wird kontrolliert, ob der Runner die Zielumgebung erreicht und die benötigten Berechtigungen besitzt.
In diesem angenommenen Fall zeigt sich, dass ein für das Deployment verwendeter Zugang nicht mehr gültig ist. Der Job kann deshalb keine neue Version bereitstellen.
Die Lösung besteht nicht darin, den Anwendungscode zu verändern. Der zuständige Administrator muss den benötigten Zugriff nach dem vereinbarten Berechtigungskonzept wiederherstellen.
Wann gilt die Störung als behoben?
Ein grüner Pipeline-Status ist ein wichtiger Hinweis, aber noch keine vollständige fachliche Abnahme.
Nach dem erneuten Deployment sollte das Team kontrollieren, ob tatsächlich die vorgesehene Version in der richtigen Umgebung läuft.
Bei der Auftragssoftware könnte ein benannter Mitarbeiter anschließend einen gekennzeichneten Testauftrag durchführen: Erfassung in der Anwendung, Verarbeitung und bestätigte Übernahme im angebundenen ERP-System.
Erst dann lässt sich beurteilen, ob nicht nur die Pipeline wieder funktioniert, sondern auch der betroffene Geschäftsprozess.
Dieses Vorgehen zeigt den Unterschied zwischen der Beseitigung einer technischen Fehlermeldung und der Wiederherstellung eines nutzbaren Software-Releases.
5. Wie lässt sich eine CI/CD-Pipeline gezielt reparieren?
Die passende Korrektur hängt von der tatsächlichen Ursache ab. Ein Runner-Problem benötigt andere Maßnahmen als eine fehlgeschlagene Anwendungsmigration oder eine falsche Build-Konfiguration.
Ein sinnvoller Reparaturauftrag beschreibt deshalb ein überprüfbares Ergebnis:
- Die Ursache des fehlgeschlagenen Pipeline-Schritts ist eingegrenzt.
- Die vereinbarte technische Korrektur wurde umgesetzt.
- Der betroffene Pipeline-Schritt wurde erneut geprüft.
- Die vorgesehene Softwareversion wurde in der vereinbarten Umgebung bereitgestellt.
- Die relevanten Anwendungsfunktionen wurden kontrolliert.
- Änderungen und verbleibende Einschränkungen sind dokumentiert.
Wie verhindert man denselben Fehler beim nächsten Release?
Nicht jeder Ausfall lässt sich dauerhaft vermeiden. Nach einer erfolgreichen Fehlerbehebung sollte aber geprüft werden, ob eine wiederkehrende Ursache vorliegt.
Beispielsweise können schlecht dokumentierte Berechtigungen, manuell veränderte Servereinstellungen oder nicht abgestimmte Softwareversionen wiederholt Probleme verursachen.
In solchen Fällen kann es sinnvoll sein, die Konfiguration nachvollziehbar zu verwalten, Berechtigungen zu überprüfen oder wiederkehrende Schritte zu standardisieren.
Wie Unternehmen den gesamten Release-Prozess unabhängig vom Wissen einer einzelnen Person organisieren, erläutert unser Beitrag Software-Release dokumentieren und Abhängigkeiten reduzieren.
6. Wann ist externe DevOps-Unterstützung sinnvoll?
Externe Hilfe kann sinnvoll sein, wenn die Pipeline über längere Zeit nicht mehr funktioniert, die ursprüngliche Einrichtung unzureichend dokumentiert ist oder das interne Team die Ursache nicht sicher eingrenzen kann.
Für eine erste Anfrage sind insbesondere diese Informationen hilfreich:
- Verwendetes CI/CD-System, beispielsweise GitLab CI oder Jenkins
- Betroffener Schritt und sichtbare Fehlermeldung
- Zeitpunkt des letzten erfolgreichen Releases
- Wichtige Änderungen seit dem letzten erfolgreichen Lauf
- Vorgesehene Zielumgebung und gewünschtes Ergebnis
Produktive Zugangsdaten, Tokens oder vertrauliche Konfigurationen sollten nicht ungeschützt mit einer ersten Anfrage versendet werden.
Kubertino unterstützt Unternehmen bei der Untersuchung fehlerhafter Builds, Runner-Probleme und fehlgeschlagener Deployments. Dabei werden bestehender Anwendungscode, CI/CD-Konfiguration und die betroffene Infrastruktur gemeinsam betrachtet.
Die Leistung DevOps-Outsourcing beschreibt, wie solche Aufgaben abgegrenzt, umgesetzt und mit einer nachvollziehbaren Übergabe abgeschlossen werden können.
7. Häufige Fragen zu CI/CD-Pipeline-Fehlern
Warum schlägt eine CI/CD-Pipeline plötzlich fehl?
Mögliche Ursachen sind Änderungen am Code, an Abhängigkeiten, Berechtigungen, Runnern oder Zielumgebungen. Auch eine zuvor funktionierende Pipeline kann betroffen sein, wenn sich eine benötigte externe Komponente verändert hat. Der Vergleich mit dem letzten erfolgreichen Lauf hilft bei der Eingrenzung.
Ist bei einem fehlgeschlagenen Deployment die Anwendung automatisch offline?
Nein. Je nach Deployment-Verfahren kann die bisherige Version weiterhin funktionieren. Es ist aber auch möglich, dass eine Änderung bereits teilweise ausgeführt wurde. Deshalb muss der tatsächliche Zustand der Zielumgebung geprüft werden.
Muss eine defekte CI/CD-Pipeline vollständig neu eingerichtet werden?
Nicht grundsätzlich. Häufig betrifft der Fehler einen bestimmten Job, eine Konfiguration oder eine externe Abhängigkeit. Ob eine gezielte Korrektur ausreicht oder größere Änderungen sinnvoll sind, zeigt die technische Untersuchung.
Was ist der Unterschied zwischen einem Runner-Fehler und einem Build-Fehler?
Ein Runner stellt die Ausführungsumgebung für einen CI/CD-Job bereit. Ein Runner-Problem kann verhindern, dass der Job überhaupt ordnungsgemäß startet. Ein Build-Fehler entsteht dagegen während der Erzeugung der Softwarebestandteile. Beide Fehlerarten benötigen unterschiedliche Prüfungen.
Welche Informationen benötigt ein DevOps-Dienstleister für die Fehlersuche?
Hilfreich sind das verwendete CI/CD-System, die betroffene Pipeline, der fehlgeschlagene Schritt, bereinigte Fehlermeldungen, der Zeitpunkt des letzten erfolgreichen Laufs und das gewünschte Ergebnis. Notwendige Zugänge werden erst für den abgestimmten Auftrag geklärt.