Schnellstart für GitLab Continuous Integration
Willkommen beim GitLab CI Schnellstart-Leitfaden, der durch den Prozess der Projekteinrichtung in GitLab und die Erstellung einer einfachen CI-Konfiguration im Code führt. Dieser Leitfaden ermöglicht den schnellen Einstieg in GitLab CI.
Die folgenden Aufgaben werden in diesem Schnellstart-Leitfaden beschrieben:
- Einrichtung eines neuen Projekts.
- Erstellung der ersten CI/CD-Konfiguration und Pipeline-Ausführung.
- Zugriff und Überprüfung der Ausführungsergebnisse.
- Einführung regelbasierter Bedingungen zur Bestimmung von Job-Ausführungen.
- Nutzung der Pipeline-Templates für nahtlose Integration vorteilhafter Konfigurationen.
Bevor Sie beginnen
Stellen Sie sicher, dass Sie ein GitLab-Konto haben. Falls nicht, hier registrieren.
Innerhalb eines Projekts werden verschiedene Komponenten wie Codebasis, CI-Konfiguration, Planung, Analysen und Teammitglieder(innen) verwaltet. In diesem Leitfaden wird ein neues Projekt mit leerer Vorlage erstellt, das nur eine Readme-Datei enthält.
- Neues Projekt durch Klicken auf das Plus-Symbol rechts in der oberen Leiste erstellen und Neues Projekt/Repository auswählen
- Leeres Projekt erstellen auswählen. Unter
Projektname
my-project eingeben. - Projekt erstellen klicken.
- Glückwunsch! Das erste Projekt wurde erfolgreich erstellt.
In GitLab wird die CI-Konfiguration im Code mit YAML-Syntax definiert. Diese Konfiguration spezifiziert Anweisungen für die Runner-Maschine bezüglich Job-Ausführung, Job-Reihenfolge, Job-Bedingungen und mehr. Zur Definition der CI-Konfiguration muss eine Datei namens .gitlab-ci.yml erstellt werden, die sich im Root des Repositorys befinden sollte. In diesem Leitfaden wird die Web IDE zur Erstellung und Bearbeitung dieser Datei verwendet.
Für den Zugriff auf die Web IDE einfach auf die Web IDE Schnelltaste im Projekt klicken. In der Web IDE zum Datei-Explorer auf der linken Seite navigieren. Rechtsklick im Datei-Explorer und die Option Neue Datei wählen. Die neu erstellte Datei .gitlab-ci.yml benennen.
Die Reihenfolge der Job-Ausführungen wird durch die in der Konfiguration definierten Stages bestimmt. In diesem Leitfaden werden drei Stages definiert: build, test und package, in genau dieser Reihenfolge. Den folgenden Code in die .gitlab-ci.yml Datei kopieren und einfügen:
stages:
- build
- test
- package
Stellen Sie sich ein Szenario vor, in dem die Aufgabe besteht, zwei Textdateien zu erstellen. Es ist von größter Wichtigkeit, dass die Verkettung dieser Dateien den Ausdruck "Hello world." enthält. Das Ziel ist es, diese Anforderung mit Pipeline-Jobs zu erstellen, testen und zu verpacken.
Ein Build-Job wird spezifiziert, der folgende Aufgaben erfüllt: Erstellung einer Textdatei mit dem Wort "Hello", Erstellung einer weiteren Textdatei mit dem Wort "World" und Generierung einer dritten Datei, die den kombinierten Inhalt der beiden Dateien speichert. Die dritte Datei wird als Artefakt gespeichert, sodass nachfolgende Jobs in Test- und Package-Stages darauf zugreifen können. Den bereitgestellten Code unter dem Stages-Block einfügen:
build-job:
stage: build
script:
- echo "Hello " | tr -d "\n" > file1.txt
- echo "world" > file2.txt
- cat file1.txt file2.txt > compiled.txt
artifacts:
paths:
- compiled.txt
Zur Validierung der Integrität des Builds wird ein Test-Job integriert. Dieser Job überprüft, ob die compiled.txt Datei tatsächlich den erwarteten Ausdruck "Hello world" enthält. Den folgenden Code unter dem Build-Job einfügen:
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world '
Nach erfolgreichem Abschluss des Tests ist das nächste Ziel die Generierung eines Pakets für den Code. Dazu wird ein Package-Job eingefügt. Es ist wichtig zu beachten, dass bei einem Testfehler die gesamte Pipeline als erfolglos betrachtet wird und nicht fortgesetzt wird. Den bereitgestellten Code unter dem Test-Job einfügen:
package:
stage: package
script: cat compiled.txt | gzip > packaged.gz
artifacts:
paths:
- packaged.gz
stages: # Liste der Stages für Jobs und deren Ausführungsreihenfolge
- build
- test
- package
build-job:
stage: build
script:
- echo "Hello " | tr -d "\n" > file1.txt
- echo "world" > file2.txt
- cat file1.txt file2.txt > compiled.txt
artifacts:
paths:
- compiled.txt
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world'
package:
stage: package
script: cat compiled.txt | gzip > packaged.gz
artifacts:
paths:
- packaged.gz
Hier ist ein Link zur Konfigurationsdatei in unserem Beispielprojekt.
Glückwunsch!! Die erste CI-Pipeline wurde erstellt.
Zur Aktivierung der Continuous Integration (CI) im Projekt muss die .gitlab-ci.yml Datei in das Repository gepusht werden. Sobald sich diese Datei im Root des Repositorys befindet, wird jeder Commit im Projekt automatisch eine CI-Pipeline initiieren. Die erste Pipeline beginnt sofort nach dem Push dieser Datei zum Server.
- Auf das Merge-Symbol links vom Datei-Explorer klicken.
- Eine Commit-Nachricht wie "Adding CI configuration." eingeben.
- Auf Commit & Push klicken.
- Bei der Aufforderung "Commit to a new branch?" "No, Use the current branch main" auswählen.
- Um zum Projekt zurückzukehren, auf die Schaltfläche Go to project unten links klicken.
Glückwunsch! Das Projekt ist nun erfolgreich konfiguriert, um automatisch eine CI-Pipeline für jeden Code-Commit zu initiieren.
Während die Pipeline läuft, kann der Status im CI/CD Tab überwacht werden. Diese Funktion ermöglicht die einfache Verfolgung des Fortschritts der Jobs, einschließlich ihres Ausführungsstatus (wie gestartet, bestanden, fehlgeschlagen usw.) sowie jeder von den Job-Skripten generierten Ausgabe.
- Zum GitLab-Projekt navigieren und das linke Menü finden.
- Im Menü auf CI/CD klicken, dann Pipelines klicken.
- Auf der Pipelines Seite die Pipeline-Schaltfläche in der Status Spalte finden. Darauf klicken, um den Pipeline-Graph zu öffnen.
- Nun können die Jobs und ihre jeweiligen Status im Pipeline-Graph beobachtet werden.
- Um einen spezifischen Job zu erkunden, darauf klicken, um die Job-Konsole zu öffnen. Diese Konsole zeigt alle auf der Runner-Maschine ausgeführten Schritte.
- Die Package-Job-Konsole öffnen, um die vom Runner verarbeiteten Schritte anzuzeigen.
- Der Package-Job generiert ein Artefakt, das durch Klicken auf die Download Schaltfläche rechts heruntergeladen werden kann.
- Durch Befolgen dieser Schritte kann der Pipeline-Status effektiv verfolgt, Job-Details inspiziert und relevante Artefakte oder Pakete aus der Pipeline-Ausführung abgerufen werden.
Glückwunsch zur erfolgreichen Ausführung der ersten Pipeline. Die Pipeline war erfolgreich! Die Ergebnisse wurden angezeigt und das Job-Artefakt heruntergeladen.
Der erwartete Wert im Test-Job wird geändert, der Test-Job wird fehlschlagen und die gesamte Pipeline wird fehlschlagen.
- Den Test Job bearbeiten, indem der Ausdruck "Hello World" zu "hello world" (mit Kleinbuchstaben) geändert wird.
- Die Code-Änderungen committen und zur Pipeline-Anzeige gehen, ähnlich wie in Schritt 4.
- Bei der Inspektion der Pipeline wird beobachtet, dass der Test-Job fehlgeschlagen ist. Zusätzlich startete der nachfolgende Package Job nicht und die Pipeline selbst schlug wie erwartet fehl.
In Schritt 5 wurde gesehen, dass Job-Fehler die gesamte Pipeline zum Scheitern brachten. Logik kann in die Pipeline eingeführt werden, die bestimmt, wann ein Job-Fehler die gesamte Pipeline zum Scheitern bringt:
- Bewertung der Bedingungen, unter denen ein Job-Fehler zu Pipeline-Fehlern führen soll. Beispielsweise kann Pipeline-Fehler erzwungen werden, wenn ein Job auf dem Main- oder Default-Branch fehlschlägt, während Job-Fehler auf anderen Branches die Pipeline fortsetzen lassen.
- Definition von Regeln, die das Fehlerverhalten steuern. Variablen wie $CI_COMMIT_BRANCH können genutzt werden, um den aktuellen Branch zu prüfen und darauf basierende Entscheidungen zu treffen.
- Angemessene Bedingungen setzen und spezifizieren, ob der Job als allow_failure: false oder allow_failure: true markiert werden soll.
- Rules/if-Bedingungen zum Test-Job hinzufügen.
- Das allow_failure Schlüsselwort auf true oder false basierend auf dem Branch setzen.
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world'
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
allow_failure: false
- if: $CI_COMMIT_BRANCH
allow_failure: true
Zur Optimierung der Pipeline-Konfigurationseinrichtung können die von GitLab bereitgestellten integrierten Pipeline-Templates genutzt werden. Diese Templates bieten vordefinierte Konfigurationen für häufige Anwendungsfälle wie Sicherheitsscans, AWS-Bereitstellungen usw.
Folgende Schritte zur Nutzung der integrierten Pipeline-Templates:
- Erkundung der verfügbaren Pipeline-Templates von GitLab für verschiedene Szenarien wie Erstellen, Testen, Bereitstellen und mehr. Diese Templates sind hier zu finden.
- Auswahl des Templates, das den Anforderungen entspricht.
- Integration des Templates in die Pipeline-Konfiguration durch Referenzierung in der .gitlab-ci.yml Datei. Dies kann typischerweise durch Import des Templates mit dem include Schlüsselwort und Spezifizierung des Pfads oder der URL zur Template-Datei erfolgen.
In diesem Leitfaden wird Code Quality Scan zur Konfiguration mit dem Code-Quality Template hinzugefügt.
Das Code Quality Template zur .gitlab-ci.yml durch Hinzufügen dieses Codes unter dem Stages-Block einbinden.
include:
- template: Jobs/Code-Quality.gitlab-ci.yml
Diese Änderung committen und pushen.
Es wird bemerkt, dass ein Code Quality Job zur Pipeline hinzugefügt wurde. Der Code Quality Scanner wird alle Code-Änderungen, die in dieses Repository committed werden, gründlich analysieren und wertvolles Feedback liefern, wobei Code-Quality-Probleme hervorgehoben werden, die Aufmerksamkeit und Verbesserung erfordern. Diese wertvollen Erkenntnisse ermöglichen die Verbesserung der Gesamtqualität der Codebasis und die Optimierung ihrer Leistung.
Das war's! Mit diesen Schritten sollte der Einstieg in GitLab CI möglich sein und die Build- und Testprozesse des Projekts automatisiert werden.