Einrichtung des Kanban-Frontends und Erstellung einer CI-Pipeline

Ziel

Zeil dieser Übung ist es das das Kanban-Frontend in GitHub Codespaces ausgeführt werden kann und die Anbindung an das Backend funktioniert. Zusätzlich erstellen wir mittels GitHub Actions eine Continuous Integration (CI) Pipeline.

Hierzu werden wir in dieser Übung die folgenden Schritte durchführen:

• Einführende Erklärung des Themenkomplexes
• Erstellen eines neuen Branches
• Starten eines GitHub Codespaces mit dem zuvor erstellten Branch
• Erstellen eines CI-Scripts mittels GitHub Actions
• Einen Commit mit unseren Änderungen erstellen und diesen an unser GitHub Repo pushen
• Einen Pull-Request in GitHub erstellen
• Ausführung des Build auf GitHub beobachten, das Log auswerten und auf das Artefakt zugreifen

Einführung

In diesem Abschnitt werden wir für unsere Frontend-Applikation einen automatischen Build erstellen.

Ein automatisierter Build stellt einen wichtigen Bestandteil einer Continuous Integration Pipeline oder auch kurz CI dar.

Diese Automatisierung werden wir mittels GitHub Actions durchführen. GitHub Actions ermöglicht es eine Vielzahl von Aufgaben zu automatisieren ebenso wartet GitHub Actions auch mit einigen Integrationen auf.

Als Einführung in das Thema sowie zum Erlernen der Begrifflichkeiten als auch der Funktionsweise ist der nachfolgende Link zu lesen Understanding GitHub Actions

Die offizielle Dokumentation zu GitHub Actions können diesem Link entnommen werden.

Import des Anwendungs-Source-Codes

Wie zuvor navigieren wir hierzu zuerst in der oberen Menüleiste nach rechts und klicken auf den Pfeil nach unten neben den Plus (1) und anschließend auf “Import repository” (2). Siehe auch Screenshot unten.

Wir importieren das Repository https://github.com/FHB-Student/Kanban-Frontend-Starter in unseren eigenen GitHub Account.

Wir vergeben einen eindeutigen Namen für das neue Repository und starten anschließend den Import.

Sobald der Import abgeschlossen ist wechseln wir in GitHub in das Repository.

Erstellen der CI-Pipeline

GitHub Actions Berechtigungen vergeben

Bevor der Workflow ausgeführt werden kann, müssen wir an den Berechtigungen noch etwas anpassen. Hierzu wählen wir in unserem GitHub Repository den Tab „Settings“ aus. Danach wählen wir im linken Menü die Option „Actions -> General“ aus. Bei den Berechtigungseinstellungen wählen wir die Option „Allow all actions and reusable workflows“ und bestätigen das mittels „Save“.

Erstellen eines Feature-Branches

Da wir Änderungen am Source-Code vornehmen und wir nicht jede Änderung direkt auf den Main-Branch haben wollen legen wir in diesem Schritt einen eigenen Branch an. Für unsere Übungen werden wir einen Feature Branch Workflow verwenden. Zur Auffrischung bitte diese kurze Zusammenfassung von Atlassian zum Feature-Branch-Workflow lesen.

Wir erstellen wie in der vohergegangenen Übung einen neuen Branch. Auch diesmal benennen wir diesen verständlich so das wir bereits am Namen erkennen wobei es sich hierbei handelt.

Nachdem wir den Branch erfolgreich erstellt haben, wurde dieser von GitHub bereits als aktiver Branch gesetzt.

GitHub Codespaces öffnen

Um unser Repo in GitHub Codespaces zu öffnen klicken wir zuerst auf “Code” (1) danach wählen wir den Tab “Codespaces” (2) aus. Anschließend klicken wir auf “Create codespace on …” (3) um den Codespace zu starten.

Es öffnet sich nun ein neuer Browser-Tab mit einer VS Code Oberfläche.

GitHub Action CI-Script erstellen

Da nun unsere Online-Entwicklungsumgebung bereitsteht können wir nun beginnen das CI-Script zu erstellen.

Hierzu erstellen wir zuerst ein neues Verzeichnis, gemäß der Konventionen von GitHub Actions. Das Verzeichnis muss „.github/workflows“ heißen da GitHub Actions automatisch nach Scripts in diesem Ordner sucht.

Das erledigen wir, indem wir zuerst auf das Icon mit dem Ordner und dem Plus anklicken, siehe rote Markierung. Als Name wählen wir „.github“ und darin erstellen wir ein Unterverzeichnis namens „workflows“. Wenn wie im Screenshot der Name „.github/workflows“ angegeben wird so wird wie gewollt als Verzeichnis .github und darin das Verzeichnis workflows erstellt.

Caution

Im Verzeichnisbaum muss man sich auf der obersten Ebene befinden da die Verzeichnisse, die gerade erstellt werden, als untergeordnete Elemente des gerade gewählten erstellt werden.

Nun müssen wir nur noch eine YAML-Datei mit der „Action“ erstellen. Sollte YAML dir nicht geläufig sein so ist es Empfehlenswert das du dich ein paar Minuten mit diesem Link beschäftigst.

Um eine neue Datei zu erstellen, wählen zuerst unser neu erstelltes Verzeichnis in der Baumstruktur aus. Anschließend wählen wir das Icon welches ein Blatt Papier inklusive dem Plus Symbol darstellt, siehe rote Markierung, aus. Die Datei nennen wir für diese Übung „ci.yml“. Hier kann aber entgegen dem Verzeichnisname ein beliebiger Name vergeben werden.

In die neue Datei fügen wir den nachfolgenden Code ein.

ci.yml

name: build-and-archive-kanban-frontend-app
on: [push]
jobs:
    build:
        runs-on: "ubuntu-latest"
        steps:
          - name: Checkout repository
            uses: "actions/checkout@v4"
          - name: Setup Node-Environment
            uses: "actions/setup-node@v4"
            with:
              node-version: '22'
          - name: Build optimized web application
            run: |
              npm ci
              npm run build
          - name: Archive production artifacts
            uses: actions/upload-artifact@v4
            with:
              name: dist
              path: dist

Was passiert hier genau? Gehen wir kurz gemeinsam das Script Zeile für Zeile durch.

Änderungen in Git festschreiben (Commit)

Nachdem wir das Script erfolgreich angelegt haben, ist es jetzt Zeit unsere Änderungen für alle Bereitzustellen indem wir diese wieder in den Main-Branch mergen. Zuerst müssen wir also einen Git-Commit durchführen. Das können wir ebenso über die Entwicklungsumgebung durchführen.

Uns werden dann alle geänderten Dateien gegenüber letzten Commit in den Fall aus dem Basis-Branch in unserem Fall „main“ angezeigt. In unserem Fall gibt es eine neue Datei names “ci.yml” im neu erstellten Verzeichnis “.github/workflows”..

Im Eingabefeld können wir einen Text angeben, der den Commit beschreibt. Über die optimale Beschreibung wir fleißig diskutiert. Für unsere Übung reicht es jedoch, wenn wir klar beschreiben, was bzw. warum wir etwas geändert haben. Für dieses Beispiel habe ich den Text „Adding CI Workflow“ gewählt. Dieser ist jedoch frei wählbar und hat für unsere Übung keine weitere Bewandtnis. Bei sonstiger Verwendung ist es äußert ratsam Wert auf eine gepflegte History zu legen da diese zur einfacheren Fehlersuche und erhöhter Nachvollziehbarkeit beiträgt.

Anschließend fragt die Web-UI nach einer Bestätigung ob wir alle Änderungen zuerst stagen und danach commiten wollen.

Dies bestätigen wir mittels eines Klicks auf “Ja”.

GitHub Codespace stoppen

Anschließend stoppen wir noch unseren GitHub Codespace da wir ihn nicht weiter benötigen.

Hierzu betätigen wir zuerst die “F1”-Taste und geben dann in der Befehlsleiste “Codespaces: Stop Current Codespace” und wählen diese Option anschließend aus.

Das dies erfolgreich durchgeführt wurde zeigt uns dieser Screenshot an.

Änderung in den Main-Branch bringen (Pull Request/Merge Request)

Nachdem wir den GitHub Codespace gestoppt haben und wir auf GitHub zurückgewechselt sind, zeigt uns die Weboberfläche an das es einen Push auf den Branch „feature/ci-build“ gegeben hat.

Wir klicken auf „Compare & pull request“ um einen Pull-Request zu öffnen.

Wie im Screenshot ersichtlich gibt es keine Konflikte, somit kann der Pull-Request gemergt werden. Um den Pull-Request zu erstellen, klicken wir auf „Create pull request“. Wir werden zu einer neuen Bildschirmmaske weitergeleitet. Hier können weitere Informationen zu den Änderungen eingeholt werden. Beispielsweise enthält der Tab „Commits“ eine Liste der Commits und bei „Files changed“ wird eine Ansicht präsentiert mit den geänderten Dateien.

Mittels eines Klicks auf „Merge pull request“ wird der eine Commit mit den zwei geänderten Dateien in den Main-Branch gemergt. Hierbei entstehen in der History zwei Commits. Zum einen der Commit mit den Änderungen und auch ein Merge-Commit. Weiters können wir dem Screenshot entnehmen das der Build bereits läuft. Dieser Job wird auf einem Runner abgearbeitet der von GitHub bereitgestellt wird. Nach ein paar Minuten Wartezeit sollte der Build erfolgreich durchgelaufen sein.

Somit kann der Branch nun in den Main-Branch übernommen werden.

Dies bestätigen wir mit „Confirm merge“.

Ausführung der GitHub Action des Main-Branches

Nach dem erfolgreichen mergen des Pull Requests startet die Action nun nochmals, diesmal für den Branch „main“. Wenn der Build abgeschlossen ist wird das in GitHub angezeigt.

Hierzu muss der „main“ Branch ausgewählt sein, sobald der Build erfolgreich durchgelaufen ist, wird durch ein grünes Häkchen angezeigt. Mittels eines Klicks auf das grüne Häkchen öffnet sich ein Pop-Up mit einem Link namens „Details“.

In den Details ist ein ausführliches Log des Aufrufes angeführt.

Zusätzlich kann im Menü auf „Summary“ gewechselt werden. In dieser Ansicht stehen einige Statusinformation zur Verfügung. Weiters könne hier die Artefakte die durch die Action erzeugt und gespeichert wurden heruntergeladen werden.

Durch unser Skript wird die Seite gebaut und eine optimierte Version wird als Artefakt abgelegt. Dieses Artefakt kann nun die Basis für weitere Tätigkeiten, beispielsweise eine Continuous Delivery Pipeline sein.

Zusammenfassung

In diesem Lab wurden die nachfolgenden Themen erklärt:

• Einführende Erklärung des Themenkomplexes
• Erstellen eines neuen Branches
• Starten eines GitHub Codespaces mit einem zuvor erstellten Branch
• Erstellen eines CI-Scripts mittels GitHub Actions
• Einen Commit mit unseren Änderungen erstellen und diesen an unser GitHub Repo pushen
• Einen Pull-Request in GitHub erstellen
• Ausführung des Build auf GitHub beobachten, das Log auswerten und auf das Artefakt zugreifen