Kapitel 4. Benachrichtigungen und Berichte
Diese Arbeit wurde mithilfe von KI übersetzt. Wir freuen uns über dein Feedback und deine Kommentare: translation-feedback@oreilly.com
Eine der Hauptanwendungen von Jenkins ist die Implementierung von Automatisierung. Neben der wiederholbaren Verarbeitung, die durch ein bestimmtes Ereignis ausgelöst wird, sind wir auch darauf angewiesen, dass wir automatisch benachrichtigt werden, wenn Prozesse abgeschlossen sind und welchen Status sie insgesamt haben. Außerdem erstellen viele Plugins und Schritte als Teil ihrer Verarbeitung nützliche Berichte.
Die Pipeline-DSL enthält Schritte, die bei Benachrichtigungen helfen. In diesem Kapitel schauen wir uns an, wie man Jenkins konfiguriert und Code implementiert, um einige gängige Benachrichtigungsmethoden und -dienste zu nutzen.
Als Erstes schauen wir uns einige der Arten von Benachrichtigungen an, die Jenkins senden kann - von einfachen und erweiterten E-Mails bis hin zu Diensten wie Slack und HipChat.
Dann werden wir uns damit beschäftigen, wie man Berichte, die durch die Pipeline-Verarbeitung erstellt wurden, an einem bequemeren Ort anzeigen kann.
Mit diesen Tools solltest du in der Lage sein, die Informationen, die du brauchst, von Jenkins zu bekommen und sie mit anderen Nutzern zu teilen.
Benachrichtigungen
In diesem Abschnitt befassen wir uns mit Benachrichtigungen, d. h. mit der Benachrichtigung von Nutzern über einen Status, ein Ereignis oder eine Information, auf die sie aufmerksam gemacht werden sollen. In den meisten Fällen geschieht dies in den "nachbearbeitenden" Teilen einer Pipeline. In einer skriptgesteuerten Pipeline bedeutet dies in der Regel die Verwendung eines try-catch-finally Konstrukts, wenn du immer eine Nachbearbeitung durchführen willst (wie in Kapitel 3 beschrieben). Für deklarative Pipelines gibt es den einfacheren post Abschnitt, den wir verwenden können.
Unabhängig davon, wo du Benachrichtigungen einsetzt, hast du mit Jenkins heute viel mehr Möglichkeiten als nur den traditionellen E-Mail-Weg. Viele der Optionen fallen in den Bereich des Instant Messaging und erlauben es dem Nutzer sogar, die Farbe der Nachrichten zu bestimmen. In diesem Kapitel werden wir uns einige dieser Optionen ansehen.
Traditionell war die E-Mail in Jenkins das wichtigste Mittel zur Benachrichtigung. Daher gibt es eine umfangreiche Unterstützung (und viele Optionen) für die Konfiguration von E-Mail-Benachrichtigungen in Jenkins. Die Optionen werden auf der Seite "System konfigurieren" im Bereich "Jenkins verwalten" verwaltet. Wir werden sie der Einfachheit halber aufschlüsseln.
Jenkins Standort
In kannst du neben der "netten" URL, die du in diesem Abschnitt festlegen kannst (siehe folgenden Hinweis), auch die E-Mail-Adresse des Systemadministrators angeben. Dies ist die "Absender"-Adresse, die die Benutzer in den E-Mails von Jenkins an die Projektverantwortlichen sehen werden. Wie in dem in Abbildung 4-1 gezeigten Hilfebildschirm beschrieben, kann dies eine einfache E-Mail-Adresse oder eine ausführlichere mit einem Namen für deine Jenkins-Instanz sein. In jedem Fall ist es ein Pflichtfeld.
Abbildung 4-1. Jenkins Standort Einstellungen
Jenkins URL
In das Feld Jenkins URL in diesem Abschnitt kannst du den benutzerfreundlichen Namen deines Jenkins-Systems eingeben. Jenkins kann die URL selbst nicht erkennen. Diese Angabe ist optional und du kannst sie z. B. als "localhost:8080" angeben. Dies ist jedoch die Jenkins-URL, die in den Links in den von Jenkins gesendeten E-Mails erscheinen wird. Du musst also eine klickbare URL angeben.
In den meisten Fällen ist die E-Mail-Adresse des Nutzers (die später konfiguriert wird) diejenige, die in den E-Mails angezeigt wird. In den meisten Fällen wirst du die Admin-Adresse nicht sehen, es sei denn, du schaust in die Kopfzeilen der E-Mail. Das folgende Beispiel zeigt, wie du in diese eintauchen kannst. Hier siehst du den Wert des Feldes "System Admin e-mail address" in der Kopfzeile X-Google-Original-From:
X-Received: by 10.55.93.197 with SMTP id r188mr35950021qkb.277.1502803051345; Tue, 15 Aug 2017 06:17:31 -0700 (PDT) Received: from diyvb2 (sas08001.nat.sas.com. [149.173.8.1]) by smtp.gmail.com with ESMTPSA id 131sm6301940qki.23.2017.08.15.06.17.30 for <bcl@nclasters.org > (version=TLS1 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 15 Aug 2017 06:17:30 -0700 (PDT) From: jenkins-demo@gmail.com X-Google-Original-From: jenkins-notifications@myserver.com Date: Tue, 15 Aug 2017 09:17:30 -0400 (EDT) Reply-To: no-reply@jenkins.foo To: bcl@nclasters.org Message-ID: <2007092803.5.1502803050373.JavaMail.jenkins@diyvb2> Subject: Test email #6 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit
Als Nächstes schauen wir uns die traditionellen Einstellungen für E-Mail-Benachrichtigungen in Jenkins an.
E-Mail-Benachrichtigung
Auf der globalen Konfigurationsseite gibt es noch einen Abschnitt für E-Mail-Benachrichtigungen, den du ausfüllst, um die grundlegende E-Mail-Funktionalität einzurichten. Diese Felder sollten so gut wie selbsterklärend sein, sofern du die Details für deine E-Mail-Konfiguration erfassen kannst. Beachte, dass es rechts eine Schaltfläche Erweitert gibt, auf die du klicken musst, um Zugang zu einigen Feldern zu erhalten.
Abbildung 4-2 zeigt diesen Bereich der Seite.
Abbildung 4-2. Einstellungen für E-Mail-Benachrichtigungen
Ein paar Anmerkungen:
-
Wenn dieses Feld leer bleibt, wird standardmäßig der SMTP-Server auf localhost verwendet.
-
Wenn du SSL verwendest, wird der Port standardmäßig auf 465 gesetzt, ansonsten auf 25.
-
Das Feld "Reply-To Address" ist optional, kann aber praktisch sein, wenn du eine Adresse angeben musst.
-
Der wohl wichtigste Teil dieses Abschnitts ist die Möglichkeit, deine E-Mail-Konfiguration zu testen, indem du eine Test-E-Mail versendest (die letzten Felder am Ende). Das ist sehr empfehlenswert. Wenn dieser Test fehlschlägt, siehst du in der Regel eine Java-Fehlermeldung, wie in Abbildung 4-3 dargestellt. Das liegt in der Regel an einem falschen Benutzernamen oder Passwort oder an einer falschen Adresse für den E-Mail-Empfänger.
Abbildung 4-3. Traceback für das fehlgeschlagene Senden einer Test-E-Mail
Mit diesem Hintergrund wollen wir sehen, wie wir das in einem Pipeline-Skript verwenden können.
Versenden von E-Mails in Pipelines
Das folgende Code-Listing zeigt ein Beispiel für die Verwendung des Basisschritts mail in einer Scripted Pipeline. Wie in anderen Kapiteln des Buches erläutert, ist der try-catch-finally Block die wichtigste Methode in einer Scripted Pipeline, um sicherzustellen, dass die Nachbearbeitung unabhängig von Erfolg oder Misserfolg immer durchgeführt wird:
node('worker_node1'){try{...}currentBuild.result='SUCCESS'}catch(err){currentBuild.result='FAILURE'}finally{to:'bcl@nclasters.org',subject:"Status of pipeline: ${currentBuild.fullDisplayName}",body:"${env.BUILD_URL} has result ${currentBuild.result}"}}
Build-Ergebnisse einstellen
Du hast vielleicht bemerkt, dass wir in dieser Auflistung ausdrücklich den Wert currentBuild.result gesetzt haben. Der Grund dafür ist, dass du dich nicht darauf verlassen kannst, dass die Pipelineschritte das Bauergebnis explizit setzen, und wenn das Bauergebnis nicht gesetzt ist, zeigen die E-Mails den Status null an.
Auf ähnliche Weise kann der Pipeline mail Schritt in einer deklarativen Pipeline verwendet werden. Hier ist ein einfaches Beispiel:
pipeline{agentanystages{...}post{always{to:'bcl@nclasters.org',subject:"Status of pipeline: ${currentBuild.fullDisplayName}",body:"${env.BUILD_URL} has result ${currentBuild.result}"}}}
post Abschnitt einer deklarativen Pipeline
Beachte, dass, wie in Kapitel 7 beschrieben, der Abschnitt post eine separate Verarbeitung für Build-Status wie Erfolg, Misserfolg usw. unterstützt. In diesem Fall verwenden wir einfach die always Klausel für eine allgemeine Demonstration.
Diese Pipelines produzieren eine E-Mail wie die folgende, wenn ein Fehler auftritt:
---------------------------- Original Message ---------------------------- Subject: Status of pipeline: pipeline2 #1 From: jenkins-demo@gmail.com Date: Tue, August 15, 2017 9:33 pm To: bcl@nclasters.org -------------------------------------------------------------------------- http://jenkins1.demo.org/job/pipeline2/1/ has result FAILURE
Wenn es einen erfolgreichen Build gibt, wird dieser genauso aussehen, außer dass FAILURE durch SUCCESS ersetzt wird.
Die integrierte Funktionalität deckt zwar die grundlegenden E-Mail-Bedürfnisse ab, aber es kann vorkommen, dass du die E-Mails, die Jenkins versendet, weiter anpassen und kontrollieren möchtest. Das E-Mail-Erweiterungs-Plugin bietet viele zusätzliche Optionen, um die Handhabung von E-Mails zu erweitern, aber es bringt auch Kompromisse mit sich, wenn du es in einer Pipeline-Umgebung einsetzt. Darauf gehen wir als Nächstes ein.
Erweiterte E-Mail-Benachrichtigungen
Unter gibt es neben der grundlegenden E-Mail-Funktionalität auch ein erweitertes E-Mail-Plugin (email-ext), das zahlreiche zusätzliche Optionen und Steuerungsebenen für den E-Mail-Versand über Jenkins bietet. Es enthält einen ähnlichen allgemeinen E-Mail-Konfigurationsbereich wie das Mail-Plugin, fügt aber zusätzlich Funktionen in drei Bereichen hinzu:
- Inhalt
Es ist möglich, den Inhalt des Betreffs und des Textes einer E-Mail-Benachrichtigung dynamisch zu ändern.
- Empfänger
Du kannst festlegen, welche Benutzerrollen eine E-Mail-Benachrichtigung erhalten sollen.
- Auslöser
Du kannst festlegen, unter welchen Bedingungen eine E-Mail-Benachrichtigung gesendet werden soll. (Beachte, dass dies derzeit nicht für Pipelines gilt.)
Im Folgenden werden wir uns jeden dieser Bereiche genauer ansehen und sehen, wie du sie gegebenenfalls integrieren kannst.
Globale Konfiguration
Das email-ext-Plugin erfordert einige globale Konfigurationen, bevor es in Pipeline-Aufträgen verwendet werden kann. Das meiste davon entspricht der Konfiguration, die wir für die grundlegende E-Mail-Funktionalität vorgenommen haben (siehe Abbildung 4-4).
Abbildung 4-4. Allgemeine Konfiguration für erweiterte Emails
Einige neue Felder verdienen eine nähere Erläuterung. Dazu gehören:
- Listen-ID E-Mail-Kopfzeile verwenden
Wenn du diese Option auswählst, kannst du allen E-Mails eine Listen-ID als Kopfzeile zuweisen. Wie in der Hilfe beschrieben, kann dies bei der Filterung und der Vermeidung von Autorespondern nützlich sein. Die Hilfe enthält Beispielformate.
- E-Mail-Kopfzeile "Vorrang: Bulk" hinzufügen
Diese Option fügt den E-Mails von Jenkins eine Kopfzeile hinzu. Basierend auf einem Standard, der von Mailsystemen verwendet wird, sollte diese Option automatische Antworten, die an Jenkins zurückgeschickt werden, verhindern oder reduzieren.
- Antwort an Liste
Das ist nicht neu, aber wir können eine kommagetrennte Liste von Benutzern/Adressen angeben.
- Notfallumleitung
Wenn dieses Feld ausgefüllt ist, werden alle Jenkins-E-Mails nur an diesen oder diese Empfänger gesendet. Das kann nützlich sein, um Jenkins vorübergehend nicht zu erlauben, weitere E-Mails zu versenden, wenn ein Problem dies rechtfertigt.
- Ausgeschlossene Begünstigte
Wie der Name schon sagt, kannst du damit alle E-Mail-Adressen aus der Liste ausschließen (herausfiltern), die durch andere Funktionen in diesem Plugin erzeugt wurden.
Als Nächstes schauen wir uns die Funktionen des Plugins an, mit denen wir die Standardelemente von E-Mails festlegen können.
Inhalt
Unter in der globalen Konfiguration gibt es eine Reihe von Feldern, die es uns ermöglichen sollen, den Inhalt der von Jenkins versendeten E-Mail-Benachrichtigungen dynamisch zu erstellen/zu ändern. Abbildung 4-5 zeigt diese Felder.
Abbildung 4-5. Standardmäßige globale Inhaltseinstellungen für erweiterte E-Mails
Der emailext Schritt und die Standardfelder
Derzeit haben diese Felder in Pipeline-Skripten keinen Wert, da es keine Möglichkeit zu geben scheint, emailext anzuweisen, die Standardwerte von hier zu verwenden. Wir erwähnen sie jedoch in unserer Diskussion, falls diese Funktion später verfügbar sein sollte.
Die ersten drei Felder (Standard-Betreff, maximale Größe des Anhangs und Standard-Inhalt) sind ziemlich selbsterklärend. Beachte, dass die Größe des Anhangs in Megabyte angegeben werden sollte und dass sie für alle Anhänge gilt.
In den Bereichen Standard-Skript vor dem Versenden und Standard-Skript nach dem Versenden kannst du ein Groovy-Skript eingeben, das vor dem Versenden der E-Mail ausgeführt (und möglicherweise geändert) wird, bzw. nachdem die E-Mail versendet wurde. Wenn du dich dafür interessierst, findest du im Internet eine Reihe von "Rezepten". Eine gute Anlaufstelle ist die Plugin-Seite.
Du kannst auch eine Reihe von Token verwenden, um den Inhalt der Felder Default Subject und Default Content zu erstellen. Mit "Token" sind hier Build- oder Umgebungsvariablen gemeint, die von Jenkins in anderen Kontexten ausgefüllt werden. $BUILD_NUMBER enthält z. B. die Nummer des Builds und $PROJECT_NAME den Namen des Projekts. Falls definiert, können die standardmäßigen Pre-Send- und Post-Send-Skripte in anderen Aufträgen als ${DEFAULT_PRESEND_SCRIPT} bzw. ${DEFAULT_POSTSEND_SCRIPT} referenziert werden.
Die erweiterte E-Mail-Funktionalität bietet nicht nur mehr Optionen für den Inhalt von E-Mails, sondern auch für die Auswahl der Arten von Empfängern, an die E-Mails gesendet werden sollen. Das ist der nächste Schritt.
Empfänger
Das Email Extension Plugin bietet mehrere Kategorien von Empfängern über den emailext Pipelineschritt. Diese kommen zu den individuellen Empfängern hinzu.
Abbildung 4-6 zeigt die auswählbaren Kategorien in der Dropdown-Liste für diesen Schritt.
Abbildung 4-6. Hinzufügen von erweiterten E-Mail-Empfängern
In Tabelle 4-1 sind die Kategorien und ihre Definitionen aufgeführt, wobei der Wortlaut aus der Plugin-Dokumentation übernommen wurde.
| Name | Beschreibung (aus der Plugin-Dokumentation) |
|---|---|
| Schuldige | Sendet eine E-Mail an die Liste der Benutzer, die zwischen dem letzten nicht fehlerhaften Build und jetzt eine Änderung vorgenommen haben. Diese Liste enthält zumindest immer die Personen, die in diesem Build Änderungen vorgenommen haben, aber wenn der vorherige Build ein Fehler war, enthält sie auch die Liste der Schuldigen. |
| Entwickler | Sendet eine E-Mail an alle Personen, die eine Änderung im Changeset verursacht haben. |
| Antragsteller | Sendet eine E-Mail an den Benutzer, der den Build initiiert hat (vorausgesetzt, er wurde manuell initiiert). |
| Verdächtige Ursachen für das Fehlschlagen von Unit Tests | Sendet eine E-Mail an die Liste der Benutzer, die im Verdacht stehen, das Fehlschlagen eines Einheitstests verursacht zu haben. Diese Liste enthält die Committer und Requestors des Builds, in dem der Test fehlgeschlagen ist, und aller aufeinanderfolgenden fehlgeschlagenen Builds vor dem Build, in dem der Test fehlgeschlagen ist. |
| Verdächtige Ursachen für das Fehlschlagen des Builds | Sendet eine E-Mail an die Liste der Benutzer, die im Verdacht stehen, den Build fehlschlagen zu lassen. |
| Upstream Committers | Sendet eine E-Mail an die Liste der Benutzer, die Änderungen in Upstream-Builds vorgenommen haben, die diesen Build ausgelöst haben. |
Wenn wir diese in der Pipeline emailext verwenden, müssen wir die $class Notation verwenden, um die Namen zu referenzieren (zumindest zum Zeitpunkt dieses Schreibens). Zum Beispiel:
emailextbody:'body goes here',recipientProviders:[[$class:'CulpritsRecipientProvider'],[$class:'DevelopersRecipientProvider'],[$class:'RequesterRecipientProvider'],[$class:'FailingTestSuspectsRecipientProvider'],[$class:'FirstFailingBuildSuspectsRecipientProvider'],[$class:'UpstreamComitterRecipientProvider']],subject:'subject goes here'
Auslöser
In der globalen Konfiguration von für das email-ext Plugin kannst du auch eine Reihe von Standardauslösern für Ereignisse auswählen, bei denen E-Mails verschickt werden sollen. Allerdings werden diese automatischen E-Mails nur dann hinzugefügt, wenn du Freestyle-Aufträge verwendest und "Editierbare E-Mail-Benachrichtigungen" in den Teil "Post-Build-Aktionen" des Auftrags einfügst. Im Kontext der Pipeline sind sie also nicht nützlich.
Ein ähnlicher Ansatz kann in einer Pipeline umgesetzt werden, indem z. B. der Build-Status in einem finally -Block in einer Scripted Pipeline oder in einem post -Block mit Bedingungen in einer Declarative Pipeline geprüft und daraufhin eine E-Mail gesendet wird. In Kapitel 3 (über den Ablauf einer Pipeline) und Kapitel 7 (über deklarative Pipelines) findest du Beispiele für solche Post-Build-Verarbeitungen.
Inklusive Protokolle
Eine der anderen nützlichen eingebauten Funktionen für das email-ext Plugin ist, dass es auch Logs einschließen (und komprimieren) kann. Um diese Einstellung im Schritt pipeline zu nutzen, kannst du einfach die hier gezeigten Optionen aktivieren:
attachLog:true,compressLog:true
Letztendlich bietet das Plugin eine gemischte Lösung für Pipeline-Entwickler. Die gute Seite ist, dass es das Hinzufügen der erweiterten Empfängerklassen und Dinge wie das Anhängen von Protokollen ermöglicht. Die Kehrseite ist, dass emailext einer der Schritte ist, die standardmäßig auf der Grundlage der globalen Konfiguration und dem Hinzufügen einer Post-Build-Aktion zu einem Freestyle-Job eine Menge tun sollten. Das lässt sich nicht gut in eine Pipeline-Umgebung übertragen, es sei denn, es gibt eine Möglichkeit, eine ähnliche Nachbearbeitungseigenschaft zu setzen, sodass die Standardfunktionalität aktiviert werden kann. Vielleicht wird diese Funktion in Zukunft noch hinzugefügt.
Ein weiterer Hinweis ist, dass die Verwendung von Pre-Send- oder Post-Send-Skripten in der emailext Pipeline derzeit nicht funktioniert. Auf Objekte, auf die diese Skripte Zugriff haben sollten, wie z. B. das Objekt build, kann nicht zugegriffen werden. Hoffentlich wird auch dies in nicht allzu ferner Zukunft behoben werden.
Hier ist ein letztes Beispiel für die Verwendung des emailext Pipelineschritts mit vielen nützlichen Komponenten:
emailextattachLog:true,body:"""<p>EXECUTED: Job <b>\'${env.JOB_NAME}:${env.BUILD_NUMBER})\'</b></p><p>View console output at "<a href="${env.BUILD_URL}">${env.JOB_NAME}:${env.BUILD_NUMBER}</a>"</p><p><i>(Build log is attached.)</i></p>""",compressLog:true,recipientProviders:[[$class:'DevelopersRecipientProvider'],[$class:'RequesterRecipientProvider']],replyTo:'do-not-reply@company.com',subject:"Status: ${currentBuild.result?:'SUCCESS'} -Job \'${env.JOB_NAME}:${env.BUILD_NUMBER}\'",to:'bcl@nclasters.org Brent.Laster@domain.com'
Bei diesem Schritt gibt es einige Dinge zu beachten:
Der Schritt wird so formatiert, dass er in den verfügbaren Platz auf der Seite passt.
Ein besserer Ansatz beim Schreiben einer Scripted Pipeline wäre es, Variablen zu definieren, die einige der längeren Werte enthalten, und diese dann im Schritt zu verwenden.
Beachte die Verwendung von dreifachen Anführungszeichen um den Text des Textkörpers. Das ist eine Eigenheit von Groovy, wo dreifache Anführungszeichen verwendet werden, um mehrzeilige Nachrichten zu kapseln.
Wir verwenden HTML-Tags im Text der E-Mail. Damit dies als HTML gerendert wird, muss der Standard-Inhaltstyp in der globalen Konfiguration für das email-ext-Plugin auf HTML (nicht Text) eingestellt werden.
Beachte die Verwendung von doppelten Anführungszeichen um Strings, die Variablen enthalten, die interpoliert werden sollen - eine weitere Groovy-Eigenheit.
Die Syntax
${currentBuild.result?:'SUCCESS'}prüft, obcurrentBuild.resultNULList, und wenn ja, weist ihr den Wert'SUCCESS'zu. Das ist notwendig, weil einNULLWert in Jenkins für das Build-Ergebnis einen Erfolg anzeigt.Wir haben das Feld
replyToverwendet, um eine Adresse für Antworten festzulegen.Beachte, dass in der Zeichenfolge
tomehrere Namen verwendet werden können, die durch Leerzeichen getrennt sind.
Abbildung 4-7 zeigt ein Beispiel für eine E-Mail, die mit dem vorherigen Befehl erstellt wurde.
Abbildung 4-7. Beispiel-E-Mail aus dem Beispielbefehl
Während E-Mails immer noch das am weitesten verbreitete Mittel sind, um Jenkins-Nutzer/innen über Ereignisse zu informieren und Informationen auszutauschen, nutzen immer mehr Teams Instant-Messaging-Dienste für die Zusammenarbeit und für Benachrichtigungen. Zwei der beliebtesten sind Slack und HipChat. Schauen wir uns an, wie Jenkins mit jedem dieser Dienste zusammenarbeiten kann.
Kollaborationsdienste
Für einige der beliebten Messaging- und Kommunikationsdienste gibt es Plugins, die Benachrichtigungen von Jenkins an die Dienste weiterleiten. In diesem Abschnitt schauen wir uns zwei davon an - Slack und HipChat.
Slack-Benachrichtigungen
Um Benachrichtigungen an Slack zu senden, musst du zunächst das Slack Notification Plugin installieren. Nachdem du die globalen Teile dieses Plugins installiert und konfiguriert hast, kann deine Pipeline über einen slackSend Schritt Benachrichtigungen an einen Slack-Kanal senden. Aber zuerst musst du die Integration über Slack aktivieren.
Einrichtung in Slack
Aktivieren die Jenkins-Integration mit Slack setzt voraus, dass du ein Slack-Konto, ein Team und einen Kanal definiert hast. (Darauf gehen wir hier nicht ein, aber im Internet gibt es jede Menge Dokumentation dazu.) Für unsere Zwecke hier habe ich ein explore-jenkins Team und einen #jenkins2 Kanal auf Slack erstellt.
Als Nächstes musst du die Jenkins-Integration konfigurieren. Hier erfährst du, wie du ein Slack-API-Integrationstoken erstellst, damit sich Jenkins mit Slack verbinden kann.
Abbildung 4-8 zeigt ein Beispiel für den ersten Bildschirm der Konfiguration. Hier sind wir im explore-jenkins-Team angemeldet und aktivieren die Jenkins-CI-Integration für den Kanal #jenkins2 innerhalb dieses Teams.
Abbildung 4-8. Aktivieren der Jenkins-Slack-Integration in einem Kanal
Nachdem du auf die Schaltfläche "Jenkins CI-Integration hinzufügen" geklickt hast, wirst du zum nächsten Bildschirm weitergeleitet, auf dem du Anweisungen findest, was du in Jenkins tun musst, um die Integration zu nutzen. Weiter unten auf der Seite findest du die Integrationseinstellungen, die du in Jenkins verwenden musst.
Die wichtigsten Dinge, die du dafür brauchst, sind die Basis-URL und das Token. Beides findest du in der Ausgabe für Schritt 3 auf der Seite(Abbildung 4-9). Ändere alle anderen Einstellungen, die du möchtest, und klicke dann auf die Schaltfläche Einstellungen speichern unten auf der Seite. Dadurch werden die Optionen gespeichert, aber du kehrst zur gleichen Seite zurück.
Abbildung 4-9. Informationen von der Slack-Integrationsseite mit Informationen, die für die Jenkins-Konfiguration benötigt werden
Dies ist ein guter Zeitpunkt, um sich um ein Sicherheitsproblem zu kümmern. Du könntest das Token zwar direkt in der globalen Konfiguration von Jenkins verwenden, aber das ist ein Sicherheitsrisiko. Es ist besser, wenn du eine "Geheimtext"-Berechtigung erstellst, die dieses Token enthält. Weitere Informationen zum Erstellen von Berechtigungsnachweisen findest du in Kapitel 5, aber Abbildung 4-10 zeigt den wichtigsten Schritt beim Ausfüllen des Dialogs für einen neuen Berechtigungsnachweis.
Abbildung 4-10. Erstellen einer neuen "Geheimtext"-Benutzerkennung für Slack
Der nächste Abschnitt geht davon aus, dass du einen solchen Berechtigungsnachweis erstellt hast, der in der globalen Konfiguration verwendet wird.
Globale Konfiguration in Jenkins
Die globale Einrichtung von für die Slack-Benachrichtigungen umfasst nur ein paar grundlegende Informationen, wie in Abbildung 4-11 dargestellt.
Abbildung 4-11. Globale Konfiguration für die Jenkins/Slack-Benachrichtigungen
Die erste ist die Basis-URL. Diese kann aus der Ausgabe der Slack-Integration entnommen werden, wie im vorherigen Abschnitt beschrieben.
Als Nächstes folgt die Team-Subdomain, also das Team, das du in Slack verwenden wirst (dasselbe, für das du den Token konfiguriert hast). Als letztes Argument kannst du den Kanal angeben, für den du das Token konfiguriert hast.
Wie im vorherigen Abschnitt beschrieben, ist es besser, ein neues Credential für das Slack-Integrationstoken zu erstellen, als das Token selbst direkt freizugeben. Im Feld "Integration Token Credential ID" wählst du das Credential aus, das du zuvor eingerichtet hast und das das Token enthält. Wenn du diese Option verwendest, kannst du das Feld "Integration Token" leer lassen.
Schließlich gibt es noch das Kontrollkästchen "IsBot User? Wenn du diese Option aktivierst, können Benachrichtigungen von einem Bot-Benutzer gesendet werden. Damit dies funktioniert, müssen die Anmeldedaten des Bot-Benutzers (Integrationstoken) angegeben werden.
Sobald du diese Felder ausgefüllt hast, kannst du die Verbindung testen, indem du auf die Schaltfläche Verbindung testen klickst. Wenn alles geklappt hat, solltest du eine Erfolgsmeldung sehen. In Slack selbst kannst du dann die Benachrichtigungen über die Einrichtung der Integration sehen(Abbildung 4-12).
Abbildung 4-12. Benachrichtigungen über die Einrichtung der Slack-Integration
Webhooks in Slack
Während API-Tokens für die Integration recht einfach einzurichten sind, gibt es noch einen anderen Ansatz, der verwendet werden kann: Webhooks. Dies ist der neuere Ansatz für die Integration von Jenkins und Slack. Er ermöglicht es Slack, eine Nutzlast an einen in Jenkins definierten öffentlichen Endpunkt zu senden, wenn es etwas zu teilen hat. Dies ist auch der Ansatz für Slack-kompatible Anwendungen. Wir werden hier nicht ins Detail gehen, aber ich gebe dir ein paar Tipps, wie du das einrichten kannst, für den Fall, dass du es irgendwann mal brauchst.
Wie bei der zuvor beschriebenen Jenkins CI-Integration musst du zunächst die Webhook-Integration für deine Subdomain/dein Team in Slack aktivieren. Beachte, dass du einen ausgehenden Webhook (von Slack gesendete Informationen) und keinen eingehenden Webhook einrichten willst. Abbildung 4-13 zeigt den Bildschirm in Slack zur Aktivierung der ausgehenden Webhook-Integration.
Abbildung 4-13. Aktivieren der ausgehenden Webhook-Integration in Slack
Nachdem du auf die Schaltfläche "Ausgehende WebHooks-Integration hinzufügen" geklickt hast, wirst du zu einem Bildschirm weitergeleitet, auf dem du zusätzliche Informationen zu deiner neuen Integration findest, darunter auch das Token(Abbildung 4-14).
Abbildung 4-14. Details zur ausgehenden Webhook-Integration - einschließlich Token
Dann kannst du das globale Setup für Slack Webhooks mit dem Token und deinem Endpunkt konfigurieren(Abbildung 4-15).
Abbildung 4-15. Einstellung der globalen Konfiguration in Jenkins für Slack-Webhooks
Slack-Benachrichtigungen in einem Auftrag verschicken
Der Pipelineschritt slackSend ermöglicht es, die Nachricht tatsächlich über Slack zu versenden. Der einzige erforderliche (Standard-)Parameter ist der zu sendende Nachrichtenstring. Du kannst zwar jede beliebige Zeichenkette senden, aber wenn du dies für Benachrichtigungen von Jenkins verwendest, möchtest du wahrscheinlich Jenkins-Umgebungsvariablen oder globale Variablen wie env.JOB_NAME, env.BUILD_NUM, usw. einbeziehen. Wenn du diese verwendest, erinnere dich daran, sie in der ${} Syntax in eine Zeichenkette einzuschließen, die ihrerseits in doppelte Anführungszeichen eingeschlossen ist, damit die Groovy-Interpolation korrekt funktioniert. Hier ist ein einfaches Beispiel mit nur dem Standardparameter:
slackSend"Build ${env.BUILD_NUMBER} completed for ${env.JOB_NAME}."
Hinzufügen von Links in der Nachricht
Links können mit Standard-HTML-Code hinzugefügt werden (vorausgesetzt, die Option "Textformat" ist nicht eingestellt) - codiere das Element einfach als (<link | text>). Um zum Beispiel einen Link zu der URL hinzuzufügen, die du versendest, kannst du den vorherigen Schritt folgendermaßen abändern:
slackSend"Build ${env.BUILD_NUMBER} completed for${env.JOB_NAME}. Details: (<${env.BUILD_URL} | here >)"
Der andere Parameter, den du wahrscheinlich verwenden wirst, ist color. Diese Einstellung wird verwendet, um den Rahmen auf der linken Seite des Nachrichtenanhangs einzufärben.
Farben können über einige vordefinierte Bezeichnungen oder einen Hex-String angegeben werden (mehr dazu in der nächsten Notiz). Die vordefinierten Bezeichnungen sind good (dunkelgrün), warning (orange-gelb) und danger (dunkelrot).
Wenn du eine Farbe und einen Link hinzufügst, könnte der Beispielschritt wie folgt aussehen:
slackSendcolor:'good',message:"Build ${env.BUILD_NUMBER}completed for ${env.JOB_NAME}. Details: (<${env.BUILD_URL} |here >)"
Beachte, dass der Teil der Nachricht mit den Variablen in Anführungszeichen gesetzt werden muss, damit die Werte interpoliert werden können.
Farben und Farbcodes
Der Schritt slackSend kann einen Farbcode verwenden, der durch eine Zeichenkette aus hexadezimalen (Basis-16) Zeichen dargestellt wird. Der Schritt hipchatSend (der in Kürze besprochen wird) verwendet einen Namen für die Farbe. Schauen wir uns kurz an, wie diese Zuordnung aussieht.
Die Hexadezimal-Darstellung für eine Farbe besteht aus sechs Zeichen, die Zahlen von 0-9 oder Buchstaben von A-F sein können. Jede Zeichenposition steht für einen bestimmten Teil/Ton der Farbe, und die Kombination der Werte für die sechs Zeichen ergibt eine einzigartige Farbe.
Bei dieser Kombination stehen die ersten beiden Zeichen für die roten Elemente, die nächsten beiden Farben für die grünen Elemente und die letzten beiden Zeichen für die blauen Elemente.
Durch die Kombination der Hexadezimalziffern in den verschiedenen Positionen können wir jede beliebige Farbe mit verschiedenen Kombinationen der Elemente Rot, Grün und Blau erzeugen. Hier sind einige Beispiele:
#000000bedeutet, dass alle Farbanteile ausgeschaltet sind, also ist dies gleichbedeutend mit Schwarz.#FFFFFFbedeutet, dass alle farbigen Teile eingeschaltet sind, also ist dies gleichbedeutend mit weiß.#FF0000bedeutet, dass alle roten Elemente eingeschaltet sind, also ist dies rot.#00FF00bedeutet, dass alle grünen Elemente eingeschaltet sind, also ist es grün.#FFFF00bedeutet, dass alle roten und grünen Elemente eingeschaltet sind, was Gelb ergibt (Rot gemischt mit Grün).
Wenn du also möchtest, dass die Farbe lila ist, kannst du die roten Komponenten (zwei linke Hexadezimalziffern) und die blauen Komponenten (zwei rechte Hexadezimalziffern) einschalten und die grünen Komponenten (mittlere zwei Ziffern) ausschalten, wie in #FF00FF.
Es gibt zusätzliche Parameter, die der Schritt slackSend annehmen kann. Die meisten von ihnen haben dieselben Namen und Einstellungsarten wie die Werte in der globalen Konfiguration für die Slack-Integration. Sie sollen es dem Schritt ermöglichen, die Standardeinstellungen zu überschreiben, falls gewünscht. Mehr darüber erfährst du, wenn du auf dem Bildschirm Pipeline-Syntax den Schritt slackSend auswählst und auf die Schaltfläche Erweitert klickst.
Schließlich gibt es noch einen weiteren Parameter, der zur Verfügung steht: failOnError. Wenn du ihn auf true setzt, wird der Lauf abgebrochen, wenn es ein Problem beim Senden der Benachrichtigung gibt.
HipChat-Benachrichtigungen
Ähnlich wie das Slack Notification Plugin, gibt es auch ein HipChat Notification Plugin. Es fügt der Pipeline-DSL einen hipchatSend Schritt hinzu. Wie das Slack-Plugin muss auch das HipChat-Plugin zunächst in der Anwendung selbst konfiguriert werden. Anders als bei Slack hast du (derzeit) die Wahl, ob du die API von HipChat in Version 1 oder die neue API in Version 2 verwenden möchtest. Obwohl Version 2 empfohlen wird, wird zum Zeitpunkt der Erstellung dieses Artikels noch Version 1 unterstützt, daher werden wir die Einrichtung für beide Versionen behandeln.
Für diese Beispiele gehe ich davon aus, dass du bereits ein Konto hast, in dem mindestens ein Raum eingerichtet ist. Für das Beispiel hier habe ich einen Raum namens explore-jenkins eingerichtet.
Einrichtung in HipChat für die Nutzung der Version 1 API
Unter kannst du im Menü deines Raums die Option Integrationen auswählen und dann nach der Jenkins-Kachel suchen(Abbildung 4-16).
Abbildung 4-16. Die Kachel für die Jenkins-Integration in HipChat
Wenn du diese Kachel auswählst, wird dir ein Bildschirm mit dem Token der Version 1 angezeigt(Abbildung 4-17).
Abbildung 4-17. v1 Token Bildschirm
Um dieses Token in der globalen Jenkins-Konfiguration zu verwenden, musst du ein neues Jenkins-Anmeldedokument "Geheimtext" erstellen. Der Vorgang wird unter "Einrichtung in Slack" beschrieben . Beachte, dass du in der globalen Jenkins-Konfiguration nicht die Möglichkeit hast, das Token im Klartext zu verwenden, wie du es bei der Einrichtung in Slack tust.
Einrichtung in HipChat für die Nutzung der Version 2 API
Wenn du die HipChat-API Version 2 nutzen möchtest (oder musst), ist es am einfachsten, ein Token zu erhalten, indem du zu http://<dein Raum>.hipchat.com/account/api gehst. (Beachte, dass es sich hier um ein persönliches Token handelt.) Dort gibst du im Bereich "Neues Token erstellen" eine Bezeichnung für das Token ein und wählst den Typ aus. (Die Beispiele hier verwenden die Bezeichnung "jenkins" und den Bereich "Benachrichtigung senden"). Klicke auf die Schaltfläche Erstellen und du siehst ein v2-Token, das du verwenden kannst(Abbildung 4-18).
Abbildung 4-18. Abrufen eines HipChat v2-Tokens
Um dieses Token in der globalen Jenkins-Konfiguration zu verwenden, musst du ein neues Jenkins-Anmeldedokument "Geheimtext" erstellen. Der Vorgang wird unter "Einrichtung in Slack" beschrieben .
Globale Konfiguration in Jenkins
Unter musst du in der globalen HipChat-Konfiguration zunächst den Standort des HipChat-Servers angeben. Wenn du keinen dedizierten Server mit eigenem Namen hast, kannst du ihn einfach auf api.hipchat.com belassen.
Als Nächstes folgt das Kontrollkästchen, mit dem du angibst, ob du die v2-API verwendest oder nicht. Wenn du die v1-API verwendest, lässt du das Kästchen unmarkiert.
Darunter gibst du den Raumnamen ein, an den du Benachrichtigungen senden möchtest. Das kann entweder der Raumname (Groß- und Kleinschreibung wird beachtet) oder die HipChat ID-Nummer sein. Es können mehrere Namen angegeben werden, solange sie durch Kommas getrennt sind.
Wenn du v1 verwendest, kannst du als Nächstes eine andere ID angeben, von der die Benachrichtigungen gesendet werden sollen. Die Standardeinstellung ist "Jenkins".
Das Feld Kartenanbieter hat mit den Benachrichtigungskarten in HipChat zu tun. Eine Diskussion über Benachrichtigungskarten würde den Rahmen dieses Buches sprengen. Wenn du keinen besonderen Grund hast, etwas anderes zu tun, kannst du das Feld einfach auf "Standardkarten" setzen.
Abbildung 4-19 zeigt ein Beispiel für die globale Konfiguration von HipChat in Jenkins.
Abbildung 4-19. HipChat globale Konfiguration
Sobald du diese Informationen ausgefüllt hast, ist es an der Zeit, die Kommunikation zwischen Jenkins und HipChat zu testen. Das kannst du tun, indem du auf die Schaltfläche "Konfiguration testen" klickst. Wenn alles richtig eingerichtet ist, solltest du eine Testbenachrichtigung wie in Abbildung 4-20 sehen.
Abbildung 4-20. Testbenachrichtigung von Jenkins
Standard-Benachrichtigungen
gibt es noch einen weiteren Teil der globalen Konfiguration für das HipChat-Plugin - die Standardbenachrichtigungen. Dies ist der letzte Abschnitt der global konfigurierten Optionen. Die fettgedruckten Überschriften in diesem Abschnitt sind Spalten, die du konfigurieren kannst, wenn du eine Standardbenachrichtigung hinzufügst. Um eine Standardbenachrichtigung hinzuzufügen, klickst du einfach auf die Schaltfläche Hinzufügen und füllst die Felder aus.
Wie der Name schon sagt, geht es hier darum, Standardbenachrichtigungen für einen Auftrag einzurichten. Diese Benachrichtigungen werden jedoch nur verschickt, wenn in einem Auftrag keine spezifischen Benachrichtigungen konfiguriert sind und wenn die Option HipChat-Benachrichtigungen als Post-Build-Aktion hinzugefügt wird. Da diese Bedingungen nur bei einem Freestyle-Projekt erfüllt werden können und Pipeline-Projekte, die die HipChat-Integration nutzen, per Definition einen speziellen Benachrichtigungsschritt haben, gelten diese nicht für Pipeline-Projekte.
HipChat-Benachrichtigungen in einem Auftrag verschicken
Das Plugin HipChat Notification bietet den bereits erwähnten hipchatSend Schritt, den du in deiner Pipeline verwenden kannst. Der einzige erforderliche (Standard-)Parameter ist eine Nachricht. Du kannst zwar jede beliebige Nachricht senden, aber wenn du dies für Benachrichtigungen von Jenkins verwendest, möchtest du wahrscheinlich Jenkins-Umgebungsvariablen oder globale Variablen wie env.JOB_NAME, env.BUILD_NUM usw. einbeziehen. Wenn du diese verwendest, erinnere dich daran, sie in der ${} Syntax in eine Zeichenkette einzuschließen, die ihrerseits in doppelte Anführungszeichen eingeschlossen ist, damit die Groovy-Interpolation korrekt funktioniert. Hier ist ein einfaches Beispiel mit nur dem Standardparameter:
hipchatSend"Build Started: ${env.JOB_NAME} ${env.BUILD_NUMBER}"
Die andere häufig verwendete Option legt die Farbe für den Hintergrund der Nachricht in der Benutzeroberfläche fest. Im Gegensatz zu den Slack-Farboptionen kann der Farbwert nur einer der folgenden Werte sein: GREEN, YELLOW, RED, PURPLE, GRAY oder RANDOM. Der Standardwert ist GRAY.
Zusätzliche Optionen steuern andere Aspekte der Nachricht. Die Option notify kann auf true oder false gesetzt werden. Sie gibt an, ob die Nachricht eine Benutzerbenachrichtigung mit Tönen zur Benachrichtigung von Mobilgeräten usw. auslösen soll. Und die Option textFormat gibt an, ob die Nachricht im Textformat gesendet werden soll (wenn sie auf true gesetzt ist). Die Standardeinstellung ist false (HTML).
Hinzufügen von Links in der Nachricht
Unter der Voraussetzung, dass die Option textFormat nicht auf true gesetzt hat, können Links in hipchatSend Nachrichten eingefügt werden, indem einfach Standard-HTML verwendet wird. Zum Beispiel:
hipchatSend"Build ${env.BUILD_NUMBER} completed for${env.JOB_NAME}. Details: <a href=${env.BUILD_URL}>here</a>"
Ein Beispiel für einen aufwändigeren Befehl mit der Option color und Benachrichtigungen für den Raum würde wie folgt aussehen:
hipchatSendcolor:'GREEN',notify:true,message:"Build ${env.BUILD_NUMBER} completed for${env.JOB_NAME}. Details: <a href=${env.BUILD_URL}>here</a>"
Die Benachrichtigung in HipChat würde wie in Abbildung 4-21 aussehen.
Abbildung 4-21. HipChat-Benachrichtigung von Jenkins
Es gibt zusätzliche Parameter, die der Schritt hipchatSend annehmen kann. Diese haben die gleichen Namen und Einstellungsarten wie die Werte in der globalen Konfiguration für HipChat. Sie sollen es dem Schritt ermöglichen, die Standardeinstellungen zu überschreiben, falls gewünscht. Mehr darüber erfährst du, wenn du auf dem Bildschirm Pipeline-Syntax den Schritt hipChat auswählst und auf die Schaltfläche Erweitert klickst.
Anders als die zugrunde liegende E-Mail-Funktionalität entwickeln sich die Integrationspunkte für die Kollaborationsdienste weiter. HipChat wechselt von der API v1 zur API v2. Slack bietet jetzt mehr Unterstützung für Webhooks. Und kompatible Dienste können auch leicht unterschiedliche Ansätze verwenden. Schau immer im Plugins-Index nach, um die neuesten Informationen zu erhalten.
Es gibt sicherlich noch andere Arten von Benachrichtigungen, die Jenkins mit der entsprechenden Plugin-Integration bereitstellen kann, aber ich hoffe, dieser Abschnitt hat dir genug gegeben, um mit einer sinnvollen Kommunikation zu beginnen.
Ein weiteres Mittel, mit dem Jenkins Informationen übermittelt, ist die Erstellung von Berichten - oder besser gesagt, die Anwendungen, in die Jenkins integriert ist, erstellen Berichte. Wie du diese für einen leichteren Zugriff zugänglich machst, ist Thema des nächsten Abschnitts.
Berichte
Viele Plugins oder Tools, die mit Jenkins verwendet werden, erstellen HTML-Berichte für verschiedene Aufgaben. Zu den Aufgaben gehören zum Beispiel Codeanalyse, Codeabdeckung und Unit-Test-Berichte. Einige dieser Plugins, wie z. B. die für SonarQube und JaCoCo, bieten benutzerdefinierte Integrationen mit der Jenkins-Auftragsausgabe. In der Regel handelt es sich dabei um visuelle Elemente wie Abzeichen oder Diagramme oder einfache Links, auf die der Nutzer klicken kann, um zur Anwendung selbst zu gelangen und die Berichte anzuzeigen.
Einige Tools bieten jedoch keine solche Integration mit Jenkins. Sie erstellen die Berichte einfach an einem Ort in Bezug auf den Arbeitsbereich und überlassen es dem Nutzer, den Ort zu bestimmen, ihn aufzusuchen und den Inhalt dort anzuzeigen. Das ist weniger praktisch als ein Link zum Bericht auf der Ausgabeseite des Auftrags, vor allem, wenn du versuchst, den Bericht in einem der Arbeitsbereiche von Jenkins zu finden und/oder über mehrere Durchläufe eines Auftrags hinweg auf diese Informationen zugreifen musst.
Zum Glück gibt es unter das HTML Publisher Plugin. Mit diesem Plugin kannst du einen Schritt in deinen Pipeline-Code einfügen, der auf einen HTML-Bericht verweist. Außerdem kannst du einen benutzerdefinierten Link auf der Ausgabeseite des Auftrags erstellen lassen und hast die Möglichkeit, sicherzustellen, dass die Berichte über einen längeren Zeitraum aufbewahrt (archiviert) werden.
HTML-Berichte veröffentlichen
Um zu sehen, wie das HTML-Publisher-Plugin funktioniert, schauen wir uns ein Beispiel an. Angenommen, wir haben einen Gradle-Build für ein Projekt mit mehreren Unterprojekten, darunter eines namens api und eines namens util. Unsere Pipeline führt die Gradle-Testaufgabe für diese Unterprojekte aus und testet dabei eine Reihe von Unit-Tests, die wir für jedes Projekt erstellt haben.
Normalerweise erstellt Gradle für jeden Unit-Test einen Bericht namens index.html und legt ihn im Verzeichnis <component>/build/reports/test ab. Für unsere Pipeline wollen wir Links zu den HTML-Testberichten hinzufügen, die Gradle für die Unterprojekte api und util erstellt.
Damit haben wir die grundlegenden Informationen, die wir an den DSL-Schritt mit dem Namen publishHTML übergeben müssen. Ein Aufruf dieses Schritts für den api-Bericht könnte wie folgt aussehen:
publishHTML(target:[allowMissing:false,alwaysLinkToLastBuild:false,keepAll:true,reportDir:'api/build/reports/test',reportFiles:'index.html',reportName:"API Unit Testing Results"])
Der Zweck der meisten Felder, die für den Schritt angegeben werden, ist aus ihren Namen ersichtlich, und wenn das HTML Publisher Plugin installiert ist, ist die Syntax über den Snippet Generator verfügbar. Wir gehen hier trotzdem auf die Felder ein, aber wie immer kann es einfacher sein, den eigentlichen Code über den Generator zu erzeugen.
Unter findest du zunächst den target Block als Hauptparameter. Innerhalb dieses Blocks haben wir eine Reihe von Unterparametern:
allowMissingDiese Einstellung legt fest, ob der Build fehlschlagen soll, wenn der Bericht fehlt. Wenn sie auf
falsegesetzt ist, schlägt ein fehlender Bericht den Build fehl.alwaysLinkToLastBuildWenn diese Einstellung
truelautet, zeigt Jenkins immer einen Link zum Bericht des letzten erfolgreichen Builds an - auch wenn der aktuelle Build fehlgeschlagen ist.keepAllWenn dies auf
truegesetzt ist, archiviert Jenkins die Berichte für alle erfolgreichen Builds. Andernfalls archiviert Jenkins nur den Bericht für den letzten erfolgreichen Build.reportDirDies ist der Pfad zur HTML-Datei, relativ zum Jenkins-Arbeitsbereich.
reportFilesDies ist der Name der HTML-Datei(en), die angezeigt werden soll(en) (wenn es mehrere sind, sollten sie durch Kommas getrennt werden).
reportNameDies ist der Name, den der Link zum Bericht auf der Ausgabeseite haben soll.
In der Regel soll dieser Schritt, wie eine Benachrichtigung, am Ende des Builds ausgeführt werden. Und vielleicht soll er auch unabhängig davon ausgeführt werden, ob der Build erfolgreich war (vor allem, wenn wir ihn mit dem letzten erfolgreichen Build verknüpfen). Wir können ihn zu einer Benachrichtigungsstufe in einem try-catch-finally Abschnitt für eine skriptgesteuerte Pipeline oder einem post Abschnitt für eine deklarative Pipeline hinzufügen. Ein Beispiel finally Abschnitt eines Pipeline-Skripts mit diesem Schritt wird im Folgenden gezeigt. Beachte, dass wir hier Inhalte entflechten, weil sie auf separaten Knoten erzeugt wurden, die in einem parallel Schritt laufen:
finally{unstash'api-reports'publishHTML(target:[allowMissing:false,alwaysLinkToLastBuild:false,keepAll:true,reportDir:'api/build/reports/test',reportFiles:'index.html',reportName:"API Unit Testing Results"])unstash'util-reports'publishHTML(target:[allowMissing:false,alwaysLinkToLastBuild:false,keepAll:true,reportDir:'util/build/reports/test',reportFiles:'index.html',reportName:"Util Unit Testing Results"])}
Ein entsprechender post Abschnitt könnte in einer deklarativen Pipeline verwendet werden.
Abbildung 4-22 zeigt die Ausgabeseite unseres Auftrags mit den benutzerdefinierten Berichtsnamen-Links, die wir auf der linken Seite erstellt haben.
Abbildung 4-22. Auftragsausgabe mit den Links zu den benutzerdefinierten Berichten im linken Menü
Zusammenfassung
Unter haben wir in diesem Kapitel einige der grundlegenden Möglichkeiten zur Erleichterung der Jenkins-Benutzer-Kommunikation bei der Arbeit mit Pipelines behandelt. Wir haben uns die eingebauten und erweiterten E-Mail-Funktionen angeschaut und wie wir sie nutzen können. Außerdem haben wir gesehen, wie wir Kollaborationsdienste wie Slack und HipChat nutzen können, um dynamische Statusinformationen an alle Nutzer dieser Apps zu senden.
Außerdem haben wir uns überlegt, wie wir die HTML-Berichte, die von vielen Anwendungen erstellt werden, besser in die Ausgabeseite des Auftrags integrieren können, um den Zugang zu erleichtern.
Es ist wichtig zu wissen, dass die hier vorgestellten Informationen die grundlegendste Implementierung für einige der Schritte sind, insbesondere für die Benachrichtigungen. Andere Pipeline-Konstrukte könnten sicherlich verwendet werden, um sie auf elegantere Weise in den Code einzubauen.
Aus Platzgründen wurden zum Beispiel lange Strings in einige der Schritte aufgenommen, die in einer Scripted Pipeline besser als Variablen definiert und an den Schritt übergeben würden.
Außerdem können Shared-Library-Routinen verwendet werden, um Funktionen mit einem der Schritte zu kapseln, damit sie leichter aufrufbar und allgemeiner sind. (Shared Libraries werden in Kapitel 6 behandelt.)
Wir hoffen jedoch, dass du in diesem Kapitel die Informationen erhalten hast, die du für den Einstieg brauchst. Ich möchte dich ermutigen, diese Beispiele zu erforschen und darauf aufzubauen, um deine Pipeline optimal auf die Benachrichtigungsmechanismen abzustimmen, die du und dein Team brauchen.
Im nächsten Kapitel erfahren wir, wie du Jenkins-Anmeldeinformationen einrichtest und verwendest und wie du deine Pipelines absicherst.
Get Jenkins 2: Auf und davon now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
