Integrierter Entwicklungsprozess mit JIRA, Bitbucket und Jenkins

Die Ausgangssituation ist ein offenes JIRA-Ticket im initialen Status TO DO, das bereits dem entsprechenden Entwickler zugeordnet ist (s. Abb.1).

Um sich bei der Entwicklung nicht ins Gehege zu kommen, macht es Sinn, dass jeder Entwickler in seinem eigenen Feature-Branch arbeitet und nur einen abgeschlossenen Stand integriert. So wird vermieden, dass zum Beispiel andere Entwickler durch einen eingecheckten (Compile-)Fehler behindert werden oder die spätere Software halbfertige Entwicklungen enthält. Um einen Feature-Branch zu erstellen, kann der Entwickler den Hyperlink Create Branch im rechten Bereich des JIRA-Tickets verwenden und wird auf den entsprechenden Dialog in Bitbucket geleitet.

In dem sich öffnenden Dialog zum Erstellen des Branches (s. Abb.2) wird neben dem Quellbrach (master) auch ein Name für den neuen Branch gesetzt. Der vorbelegte Name bietet sich an, da er bereits mit dem Schlüssel des JIRA-Tickets beginnt, was die Voraussetzung für die Verknüpfung von JIRA und Jenkins ist.

Nach der Erstellung des Branches kann er direkt ausgecheckt und bearbeitet werden. Über einen besonders hervorgehobenen Button kann der Branch sogar direkt in SourceTree (graphischer Git-Client von Atlassian) geöffnet werden, insofern es installiert ist (s. Abb.3).

Angenommen, irgendetwas passt noch nicht und er weist den Pull Request ab (decline), dann wird das JIRA-Ticket zurück in den Status To Do versetzt und wieder dem ursprünglichen Entwickler zugewiesen. Außerdem wird die Begründung des Reviewers dem JIRA-Ticket als Kommentar hinzugefügt (s. Abb.12).

Nachdem die Kritik des Reviewers eingearbeitet wurde, kann der Entwickler einen neuen Pull Request erstellen. Der Reviewer ist dieses Mal zufrieden und akzeptiert den Pull Request (approve) (s. Abb.13). Das JIRA-Ticket wird nun ebenfalls wieder dem Entwickler zugewiesen, allerdings kommt er in den Zustand Done und erhält den Wert Resolved als Lösung.

Abschließend kann der Entwickler auf der Pull Request-Seite von Bitbucket den Merge, die Integration des Feature-Branches in den Hauptzweig, automatisch per Knopfdruck starten. Dabei führt Bitbucket beide Code-Stände zusammen und committet die Änderungen. Der Jenkins-Server baut dann automatisch den neuen master-Stand mit dem neuen Feature. Nur bei Konflikten im Code oder fehlerhaften Tests muss hier noch manuell nachgearbeitet werden.

Wie man gesehen hat, werden dem Entwickler einige Arbeitsschritte abgenommen und er kann sich auf seinen eigentlichen Job, die Feature-Entwicklung, konzentrieren. Wie man zu dieser Konfiguration der drei Werkzeuge JIRA, Bitbucket und Jenkins kommt, wird im folgenden Tutorial beschrieben.

Für den integrierten Workflow werden zwei Bitbucket-Accounts bzw. Benutzer vorausgesetzt, ein Entwickler und ein Reviewer, da Reviews vernünftigerweise nicht von den Bearbeitern selbst durchgeführt werden dürfen.

Nach dem Einloggen in Bitbucket kann ein Entwicklungsteam über das obere Hauptmenü mit Team => Create Team erstellt werden. Neben einem beliebigen Namen muss hier eine in Bitbucket eindeutige Team ID vergeben werden. Als Team-Administrator ist automatisch der angemeldete Benutzer eingetragen. Weitere Benutzer können dem Team über ihr Benutzerkürzel hinzugefügt werden (s. Abb.14).

Im nächsten Schritt muss ein Repository für dieses Team angelegt werden. Alternativ kann auch ein bereits bestehendes Bitbucket oder Github-Repository importiert werden. Beim Erstellen des Repositories wird auch gleichzeitig ein Projekt erstellt (s. Abb.15).

In den Einstellungen des Repositories (Settings => Default Reviewer) wird schließlich einer der beiden Benutzer als Default Reviewer definiert (s. Abb.16).

Bitbucket ist nun so konfiguriert, dass beide Benutzer an dem angelegten Projekt arbeiten können. Sie können Code aus- und einchecken sowie Pull Requests bzw. Reviews erstellen und bearbeiten. Bis jetzt können diese Aktionen allerdings nur direkt in Bitbucket durchgeführt werden.

Im nächsten Schritt wird ein JIRA-Projekt angelegt und mit Bitbucket verbunden. Dies ermöglicht den Zugriff auf Bitbucket-Funktionen (z. B. Erstellung von Pull Requests) direkt aus den JIRA-Tickets heraus.

Einrichtung des Projektes

Der Dialog zum Erstellen neuer Projekte kann über die obere Menüleiste aufgerufen werden (oder bei einer frischen Installation direkt über einen Link auf der Hauptseite). Hier wird die Vorlage für Basic Software Development ausgewählt (s. Abb.17). Sie enthält bereits alle für die Softwareentwicklung notwendigen Vorgangstypen wie Verbesserungen, Neue Funktionen, Bugs sowie Aufgaben und Unteraufgaben. Der enthaltene Workflow wirkt zwar im Vergleich zum klassischen JIRA-Workflow etwas primitiv, da es zum Beispiel keine fest definierten Transitionen zwischen den einzelnen Zuständen gibt, reicht aber für die einfache Entwicklung vollkommen aus. Nach dem anschließenden Festlegen eines Projektnamens (z. B. New Idea) und des Kürzels (z. B. NI) ist das Projekt einsatzbereit.

Anschließend müssen beide Benutzer (Entwickler und Reviewer), die dem Team in Bitbucket zugewiesen wurden, auch in JIRA eingerichtet werden. Dabei ist es (später für die Synchronisation) notwendig, dass die Benutzerkürzel in Bitbucket und JIRA übereinstimmen! Außerdem werden zusätzlich zwei weitere Benutzer benötigt: Ein Benutzer, über den die automatisierten JIRA-Aktionen durchgeführt werden (z. B. Automation for JIRA) und ein Benutzer für die Aktionen des Jenkins-Server (z. B. Jenkins) (s. Abb.18).

Benutzer können über das User Management erstellt und konfiguriert werden. Bestimmte Benutzerrollen müssen nicht definiert werden, da standardmäßig alle JIRA-Benutzer an allen Projekten arbeiten können.

Verknüpfung von JIRA und Bitbucket

Für die Verknüpfung von Bitbucket und JIRA stellt Atlassian bereits eine Anleitung zur Verfügung [5]. Hier werden beide Applikationen über OAuth, ein offenes Protokoll zur sicheren API-Autorisierung, miteinander verbunden [6].

Installation der Plugins

Bei einer frischen Jenkins-Installation fehlen für die Integration mit Bitbucket und JIRA noch folgende Plugins, die nachinstalliert werden müssen:

• Mit dem Bitbucket Branch Source Plugin kann man gruppierte Build-Jobs anlegen, welche das definierte Repository nach Branches und Pull Requests durchsuchen und für jeden Zweig automatisch einen eigenen Build-Job anlegen.
• Das Plugin JIRA Pipeline Steps stellt zahlreiche JIRA-Funktionen zur Verfügung, die im Jenkinsfile (Groovy-Skript) zum Konfigurieren der Build-Pipeline verwendet werden können.

Konfiguration der Plugins

Für die korrekte Funktionalität der JIRA Pipeline Steps muss noch eine zu verwendende JIRA-Instanz konfiguriert werden. Dafür müssen in den Jenkins-Einstellungen unter Manage Jenkins => Configure System im Abschnitt JIRA Steps die URL des JIRA-Servers und die Anmeldedaten des Benutzers Jenkins eingetragen werden. Der Name (hier LOCAL) wird bei den JIRA-Funktionen als Parameter mitgegeben, um die Ziel-Instanz der Funktion zu wählen (s. Abb.19).

Anlegen des Build-Jobs

Bevor ein Jenkins-Job angelegt werden kann, sollte noch ein einfaches Projekt erstellt werden. Die Quellcodes 1 und 2 enthalten ein Beispiel für eine einfache "Hello World"-Java-Anwendung mit Spring Boot, welche mit dem Buildtool Maven gebaut wird.

Quellcode 1: Maven-Konfigurationsdatei (/pom.xml)

<?xml version="l.0" encoding="UTF-8"?>
<project xmglns="http://maven.apache.org/POM/4.0.0" xmmlns:xsi"http://www.w3.org/200l/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 maven.apache.org/xsd/maven-4.0.0.xsd"&gt;
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.sboehm.demo</groupId>
  <artifactId>new-idea</artifactld>
  <version>0.0.l-SNAPSHOT</version>
  <packaging>jar</packaging>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>l.5.2.RELEASE</version>
    <relativePath/>
  </parent>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>l.8</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

</project>

Quellcode 2: "Hello World" - Java-Klasse (/src/main/java/org/sboehm/demo/DemoApplication.java)

package org.sboehm.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);

  }

  public DemoApplication() {
    System.out.printIn ("Hello World! ");
  }

}

Außerdem werden die Schritte der Build-Pipeline ebenfalls im Code definiert (Quellcode 3). Hier wird nicht im Detail auf den gesamten Inhalt oder die Syntax eingegangen, zusammenfassend checkt das Groovy-Skript den Quellcode aus dem später im Jenkins-Job definierten GIT-Repository aus, kompiliert ihn und kommentiert das JIRA-Ticket, welches über den Kommentar des zu bauenden Commits verknüpft ist.

Hier ist der Inhalt von stage("Comment on JIRA") interessant: Zunächst wird der Schlüssel des JIRA-Tickets aus dem Namen des zu bauenden Branches extrahiert (man geht davon aus, dass der Branchname mit dem Schlüssel beginnt). Anschließend wird der Kommentartext erstellt, welcher einen Link auf den jeweiligen Jenkins-Job und auf eine Bitbucket-Seite enthält, die die Änderungen des zu bauenden Commits darstellt. Die dafür benötigten Informationen werden aus von Jenkins definierten Variablen (z. B. BRANCH_NAME, JOB_BASE_NAME, BUILD_URL) und Objekten (currentBuild) entnommen. Schließlich wird der Kommentar über die Funktion jiraAddComment an die JIRA-Instanz mit dem Namen LOCAL geschickt.

Quellcode 3: Jenkinsfile (Pipeline-Konfiguration in Groovy)

node {

  def mvnHome = tool 'Maven'

  stage("Checkout") {
    checkout scm
  }

  stage("Build") {
    try {
      sh "${mvnHome}/bin/mvn clean install"
      currentBuild.result = "success"
    } catch(exception) {
      currentBuild.result = "failure"
    }
  }

  stage("Comment on JIRA") {
    def jiraIssueNumber = getJiraIssueNumber()
    if (jiraIssueNumber) {
      def comment = "success".equalsIgnoreCase(currentBuild.result) ? "Successfully integrated" : "Integration failed";
      comment += " in [${JOB_BASE_NAME} ${BUILD_DISPLAY_NAME}|${BUILD_URL}]:" 
      comment += getChangesAsComment().replaceAll("BASE_COMMIT_URL", getBaseCommitUrl())
      jiraAddComment site: "LOCAL", idOrKey: jiraIssueNumber, comment: comment
    }
  }

}

def getChangesAsComment() {
  def changes = "\n"
  for (changeSet in currentBuild.changeSets) {
    for (item in changeSet.items) {
      changes += "- *Commit ${item.commitId} by ${item.author}*\n${item.msg} ([Details|BASE_COMMIT_URL${item.commitId}])\n"
    }
  }
  return changes
}

def getBaseCommitUrl() {
  sh "git config --get remote.origin.url > .git/remote-url"
  def gitRemoteUrl = readFile('.git/remote-url').trim()
  return gitRemoteUrl.replaceAll("\\.git", "/commits/")
}

@NonCPS
def getJiraIssueNumber() {
  def matcher = (BRANCH_NAME =~ "^([A-Za-z]+-\\d)")
  return matcher ? matcher[0][1] : null
}

Sobald der Code für das Projekt geschrieben, committet und gepusht wurde, kann der Jenkins-Job angelegt werden. Hierfür kommt man unter dem Menüpunkt New Item in den Projekttyp-Auswahldialog, in dem man Bitbucket Team/Project auswählt (s. Abb.20). Dieser Job-Typ holt sich aus einem definierten Bitbucket-Repository alle verfügbaren Branches und baut, sobald irgendwo ein Commit getätigt wurde. Die Build-Schritte werden aus dem gerade erstellten Jenkinsfile entnommen.

Für die Konfiguration des zu verwendenden Bitbucket-Repositories müssen im Einrichtungsdialog des Jenkins-Jobs im Abschnitt Bitbucket Team/Project unter Owner die ID des Bitbucket-Teams, der Name des Repositories und natürlich die Anmeldedaten (Bitbucket-Account) angegeben werden (s. Abb.21).

Sobald die Job-Einstellung gespeichert wurden, fängt der Jenkins an zu bauen. Mit einem Klick auf den eingerichteten Job erscheint eine Liste mit allen gefundenen Repositories (man kann auch mehrere überwachen lassen) und nach einem Klick auf eines der Repositories kommt eine Liste mit allen Zweigen, in denen dann für jeden Commit ein Build angestoßen wird (s. Abb.22).

Nach jedem Build werden die Ergebnisdaten an Bitbucket geschickt, sodass man auch schon direkt auf den Infoseiten der Commits in Bitbucket erkennen kann, ob der Commit erfolgreich integriert werden konnte. Die Weitergabe der Ergebnisse an das jeweilige JIRA-Ticket erfolgt über die JIRA-Pipeline-Funktionen, die im Jenkinsfile definiert wurden. So müssen in den Job-Einstellungen hierfür keine Anpassungen mehr durchgeführt werden.

Die Automatisierungsregeln können in den JIRA-System-Einstellungen über den Menüpunkt Automation rules verwaltet werden. Für neue Regeln werden mehrere Vorlagen angeboten, aus denen die leere Vorlage (Blank rule) ausgewählt wird (s. Abb.23).

Auf der linken Seite des sich öffnenden Dialogs sieht man den Ablauf der Automatisierungsregel. Er besteht aus einem Auslöser (Trigger), mindestens einer Aktion (Component) und optionalen Bedingungen (Condition) (s. Abb.24). Auf der rechten Seite können Eigenschaften der Regel (z. B. Name, betroffene Projekte) bzw. ihrer einzelnen Komponenten (Trigger, Component oder Condition) bearbeitet werden. Als Name wird "PullRequest Created" definiert, die Regel soll nur für das Projekt "New Idea" gelten und von dem JIRA-Benutzer Automation for JIRA ausgeführt werden (Actor). Somit ist später in den JIRA-Tickets klar, welche Aktionen von einer Automatisierungsregel durchgeführt wurden.

Anschließend wird eine Aktion mit der Vorlage Assign issue erstellt, welche den zuzuweisenden Benutzer mit Hilfe der smart-value

{{webhookData.pullrequest.reviewers.first.username}} 

setzt (Auswahl von Smart value in Assign the Issue to), die das Benutzerkürzel des Reviewers aus den Webhook-Request-Daten extrahiert. Diese Aktion ist der Grund dafür, dass die Benutzerkürzel in Bitbucket und JIRA synchron sein müssen (gleicher Benutzer = gleiches Kürzel) (s. Abb.28)!

Schließlich wird noch eine letzte Aktion mit der Vorlage Comment on issue erstellt, in der mit dem smart-value

{{webhookData.pullrequest.author.display_name}} 

der Name des Pull Request-Erstellers und mit

{{webhookData.pullrequest.description}}

der im Pull Request geschriebene Kommentar in das JIRA-Ticket eingetragen werden (s. Abb.29).

Mit einem letzten Speichern der Aktion und dem finalen Veröffentlichen der Regel (Publish rule) ist sie vollständig eingerichtet und kann nun in Bitbucket registriert werden.

Registrierung des Webhooks in Bitbucket

Für die Registrierung des Webhooks der Automatisierungsregel wird dessen URL benötigt, die aus dem Konfigurationsdialog des Auslösers Incoming webhook kopiert werden kann. In Bitbucket navigiert man zum Einstellungsdialog des verwendeten Repositories und kann dort unter dem Menüpunkt Webhooks einen neuen Webhook hinzufügen. Dabei wählt man als Auslöser (Trigger) nur Pull Request Created aus der angebotenen Liste aus (Radiobutton hinter Triggers auf Choose from a full list of triggers setzen). Mit einem Klick auf Save ist der Webhook aktiviert und kann bereits verwendet werden (s. Abb.30).

Wurde nun ein Webhook durch einen erstellten Pull Request aktiviert, kann man sich den Webhook-Request ansehen, indem man auf View Request des entsprechenden Webhooks im Webhooks-Einstellungsdialog klickt. Hier sieht man alle durchgeführten Anfragen und deren Details (Klick auf View Details): Neben den Antwort-Informationen vom JIRA-Server kann man auch die Request-Daten einschließlich der Payload einsehen (Link Show Request Body) (s. Abb.31). Hier ist die gesamte JSON-Strukur abgebildet, die an den Webhook gesendet wurde (einschließlich der eben verwendeten Pfade pullrequest.title, pullrequest.reviewers.first.username und pullrequest.description). Für das Erstellen eigener Automatisierungsregeln können in dieser Ansicht die Pfade zu den benötigten Informationen schnell gefunden werden.

Weitere Webhooks

Jetzt müssen noch die entsprechenden Webhooks für das Akzeptieren und Ablehnen von Pull Requests erstellt werden. Hier geht man analog mit folgenden Werten vor:

Tabelle 1: Konfigurationsdaten für alle benötigten Webhooks