isy-github-actions-templates

Table of Contents

• Entkopplungs-Workflows
• Templates
  • Next Version Template
  • Build Template
  • Dependency Review Template
  • Dependency Scan Template
  • Deploy Template
  • OSS Review Toolkit Template
  • PR-Agent Template
  • Docs Build Template
  • Create Release Template
  • Dependabot Auto Changelog Template
  • Semgrep Template

Dieses Repository beinhaltet GitHub Action Templates (Reusable Workflows). Diese Templates können in bereits vorhandene Workflows eingebunden werden, um ihre Funktionalität mit sehr geringem Aufwand an anderer Stelle nutzen zu können.

Ein Beispiel-Szenario dazu: Der Commit Message Checker ist eine fertige GitHub Action, welche es ermöglicht, Commit Messages nach einem RegEx-Muster zu prüfen. Diese Funktionalität ist in einigen meiner Repositories gewünscht, wobei der Commit Message Checker überall gleich konfiguriert sein soll. Statt die Action in jedem Repository einzeln einzubinden und zu konfigurieren, erstellt man ein Template in einem Repository mit der gewünschten Konfiguration und ruft dieses in allen anderen auf.

Entkopplungs-Workflows

Templates

Next Version Template

Das Template next_version.yml stellt einen Job zur Berechnung der Versionsnummer eines Builds bereit. Dazu nutzt es die Action Semantic Version (https://github.com/PaulHatch/semantic-Dversion), welche die Version auf Basis von Conventional Commits bestimmt. Die berechnete Version ist als Ausgabe next-version für andere Jobs in einem Workflow verfügbar.

Eingabe	Erforderlich	Standardwert	Beschreibung
next-version	Nein		Überspringt die Berechnung der Version und gibt stattdessen die angegebene Version mit SNAPSHOT Suffix aus

Verwenden der berechneten Version in anderen Jobs

jobs:
  Version:
    uses: IsyFact/isyfact-standards/.github/workflows/next_version.yml@master

  OtherJob:
    needs: [Version]
    # ...
    run: echo "${{ needs.Version.outputs.next-version }}"

ℹ️

Da hier eine Action aus dem GitHub Market von einem Dritten verwendet wird, wird in dem Template sichergestellt, dass das GitHub Token nur die Rechte contents:read bereitstellt. Zudem wird die berechnete Version mit dem regulären Ausdruck ^(0|[1-9]*)\.(0|[1-9]*)\.(0|[1-9][0-9]*)$ auf Korrektheit geprüft.

Build Template

Das Template maven_build_template.yml bietet einen Workflow zum Bauen und Testen von Java/Maven Projekten. Es enthält folgende Jobs:

• Compile:
  Führt das Maven Goal compile aus.

• Test:
  Führt das Maven Goal test aus.

• CodeQuality:
  Führt die beiden Maven Plugins checkstyle und ‚spotbugs‘ aus. Der Job wird nur ausgeführt, wenn für ein Projekt Sonar (SONAR_PROJECT_KEY) nicht konfiguriert wurde.

• SonarScan:
  Führt das Maven Plugin SonarScan aus. Der Scan wird nach dem Job Test ausgeführt, damit dessen Ergebnisse (insb. die Test Coverage) auch auf Sonar Cloud verfügbar sind. Dieser Job ist optional und wird nur ausgeführt, wenn ein Sonar Projekt Key konfiguriert wurde. Dieser Job schlägt nur fehl, wenn es nicht möglich war eine Analyse durchzuführen. Die Prüfung, ob das zugehörige Quality Gate erfüllt wurde, erfolgt in SonarCloud und wird über einen zusätzlichen Status Check angezeigt. Zudem wird dieser Job nicht bei Pull Requests, die durch den Dependabot erstellt wurden, gestartet, da der Dependabot keinen Zugriff auf das SONAR_TOKEN hat.

• Commit Message Checker:
  Gleicht die Commit-Messages mit einem RegEx-Pattern ab und gibt eine Success bzw. Error Message aus, je nachdem, ob sie der Konvention entsprechen. Ein GitHub-Token (secrets.GITHUB_TOKEN), welches ausschließlich ein Lese-Recht auf Inhalte besitzt, wird zur Authentifizierung verwendet.

Beim Aufruf des Templates können folgende Parameter übergeben werden:

Eingabe	Erforderlich	Standardwert	Beschreibung
jdk-version	Nein	25	Version des zu verwendenden JDKs
maven-opts	Nein	""	Zusätzliche Argumente, die an Maven weitergegeben werden
checkout-lfs	Nein	false	Gibt an, ob LFS-Dateien mit auf den Runner geklont werden
version	Nein	0.0.0-SNAPSHOT	Version für Maven CI Friendly Versions
sonar-skip	Nein	false	Erlaubt das Überspringen des Jobs SonarScan
Secrets
SONAR_TOKEN	Nein		Token zu Sonar Cloud um das Ergebnis des Scans zu veröffentlichen
GH_PACKAGES_TOKEN	Nein		Token für Zugriff auf GitHub Packages

Dependency Review Template

Das Template dependency_review_template.yml stellt einen Job DependencyReview bereit, der verwendet wird, um die Dependencies eines Projekts zu überprüfen und sicherzustellen, dass sie mit den definierten Lizenzanforderungen übereinstimmen.

Die Datei dependency_review_config.yml definiert die Lizenztypen, die in den Projekten erlaubt sind. Diese Konfiguration basiert auf bekannten und anerkannten Lizenzreferenzen von Google Open Source.

Dependency Scan Template

Das Template maven_depenency_scan_template.yml wurde entwickelt, um Snyk für das Monitoring und Scanning der Open-Source-Dependencies eines Maven-Projektes zu integrieren. Sie enthält verschiedene konfigurierbare Inputs, um die Einrichtung und Ausführung des Dependency-Scan-Prozesses anzupassen.

Beim Aufruf des Templates können folgende Parameter übergeben werden:

Eingabe	Erforderlich	Standardwert	Beschreibung
jdk-version	Nein	25	Version des zu verwendenden JDKs
checkout-lfs	Nein	false	Gibt an, ob LFS-Dateien mit auf den Runner geklont werden
snyk-organization	Nein		Organisations-ID für die Zuordnung auf Snyk
snyk-reference	Ja		Referenz für das Ergebnis auf Snyk, z.B. Branchname
snyk-arguments	Nein	--maven-aggregate-project	Optionale Befehle für die Snyk CLI
perform-scan	Nein	false	Durchführung von Scanning statt Monitoring
severity-threshold	Nein	critical	Schweregrad für Snyk-Scan
scan-dependency-management	Nein	true	Scannen von Dependencies in Dependency Management
Secrets
SNYK_TOKEN	Ja		Token zur Authentifizierung bei Snyk

Deploy Template

Das Template maven_deploy_template.yml stellt Jobs zum Veröffentlichen von Artefakten bereit. Es kann sowohl für die Veröffentlichung von Snapshots als auch stable Releases genutzt werden. Das Deployment kann auf verschiedene Repositories, wie z.B. Maven Central oder GitHub Packages erfolgen. Das Template enthält folgende Jobs:

• Validate:
  Prüft die Korrektheit eines Releases und insbesondere die verwendete Version. Der Job stellt sicher, dass die angegebene Version im Build/POM verwendet wird und diese den Vorgaben von Semantic Versioning folgt. Bei Releases, die über tags ausgelöst wurden, wird geprüft, dass es sich bei der Version um keinen Snapshot handelt und, dass die verwendete Version nicht bereits auf Deployment-Repository vorhanden ist. Bei Releases, die ohne tag erfolgen, wird geprüft, dass es sich um Snapshots handelt.

• Deploy:
  Führt das Deployment aus. Neben den Jars (inklusive Source und Dokumentation) kann der Job auch eine SBOM erstellen und alle erzeugten Artefakte signieren.

Beim Aufruf des Templates können folgende Parameter übergeben werden:

Eingabe	Erforderlich	Standardwert	Beschreibung
jdk-version	false	25	JDK Version
version	true		Version des zu deployenden Artefakts
maven-opts	false	""	Zusätzliche Argumente, die an Maven weitergegeben werden
checkout-lfs	false	false	Gibt an, ob LFS-Dateien mit auf den Runner geklont werden
deploy-server-id	false		Referenz auf das Deployment-Repo
deploy-server-url	false	'https://oss.sonatype.org/service/ local/repositories/releases/content'	URL des Deployment-Repo
deploy-url-release	false		Deployment-URL für Releases
deploy-url-snapshot	false		Deployment-URL für Snapshots
sbom	false	false	Erstellt eine SBOM im CycloneDX Format
sign	false	false	Signiert alle Artefakte. Erfordert GPG Private Key und Passphrase.
Secrets
GPG_PRIVATE_KEY	false		Privater GPG Key zur Signierung der Artefakte
GPG_PASSPHRASE	false		Passphrase für GPG Key
DEPLOY_SERVER_USER_NAME	false		Benutzer für Repository zum Deployment
DEPLOY_SERVER_TOKEN	false		Token oder Passwort für Repository zum Deployment
GH_PACKAGES_TOKEN	false		Token für Zugriff auf GitHub Packages

💡	Die Secrets (außer dem Token für GitHub Packages) sowie der Input deploy-server-id werden durch die GitHub Action setup-java einer generierten settings.xml hinzugefügt. (https://github.com/actions/setup-java/blob/v3.11.0/docs/advanced-usage.md#publishing-using-apache-maven)

OSS Review Toolkit Template

Das Template oss_review_toolki_template.yml stellt einen Job zur Verfügung, welcher das OSS Review Toolkit aufruft. Dieses scannt alle Abhängigkeiten im Projekt und prüft sie auf CVEs. Weiterhin werden alle Lizenzen analysiert und gegebenenfalls auf Regelverstöße überprüft. All dies wird dann in verschiedenen Reports mittels Pipeline-Artefakt ausgegeben. Das Template hat keinerlei Parameter.

PR-Agent Template

Das Template pr_agent_template.yml automatisiert PR-Analyse und Feedback unter Verwendung des CodiumAI PR-Agenten und OpenAIs ChatGPT. Ausgelöst durch einen workflow_call, wird er nur bei von Menschen initiierten Events ausgeführt. Der Workflow benötigt einen OpenAI-API-Schlüssel OPENAI_KEY und ein GitHub-Token GITHUB_TOKEN als Secrets, die es ihm ermöglichen, sich zu authentifizieren und mit GitHub- und OpenAI-Diensten zu interagieren. Es verfügt über Schreibrechte für Issues, Pull-Requests und Repository-Inhalte, sodass es Überprüfungen und Aktualisierungen effizient automatisieren kann. Dieser Arbeitsablauf steigert die Produktivität, indem er KI zur Erledigung von Routineaufgaben einsetzt und es den Entwicklern ermöglicht, sich auf komplexere Arbeiten zu konzentrieren.

Standardmäßig werden die Befehle /describe, /review, /improve ausgeführt. Eine vollständige Liste der Befehle und ihrer Beschreibungen können unter PR-Agent Documentation/Tools gefunden werden oder durch Kommentieren des Befehls /help im PR.

Docs Build Template

Das Template docs_build_template.yml erleichtert die automatische Durchführung von Builds der Dokumentation für Antora-Projekte. Es ist aktuell für die Erstellung von Release-Dokumentation und zum Kommentieren von Pull Requests mit Änderungen an der Dokumentation gedacht.

Auslösen der Dokumentationserstellung: Der Workflow löst den Workflow antora_build.yml im Repository IsyFact/isyfact.github.io unter Verwendung der GitHub CLI aus. Er wartet, bis der ausgelöste Build abgeschlossen ist. Wenn der Workflow durch einen Pull Request gestartet wurde, verarbeitet er das als Artefakt veröffentlichte Antora-Log gegen den letzten Build der produktiven Online-Dokumentation und bereitet eine Übersicht der behobenen (fixed) und neu hinzugekommenen (introduced) Log-Einträge auf. Zusammen mit einer allgemeinen Übersicht des Builds und relevanter Log-Einträge veröffentlicht der Workflow das Ergebnis als Kommentar am Pull Request.

Prüfung der Diagramme (draw.io): Der Workflow prüft, ob Diagramme im SVG-Format den Anforderungen der Online-Dokumentation genügen. Aktuell prüft der Workflow, ob die Diagramme adaptive Farben verwenden, da diese in der Online-Dokumentation nicht korrekt dargestellt werden können. Weiter Erläuterungen hierzu finden sich im Leitfaden Dokumentation.

Anpassbares Logging: Der Workflow ermöglicht es, das Logging des Antora-Builds zu steuern:

• Parameter log_level: Spezifiziert den Schweregrad, ab dem eine Nachricht ins Log geschrieben wird. Weitere Details: Antora: Log Severity Level.

• Parameter failure_level : Spezifiziert den Schweregrad, ab dem der Antora-Build mit einem Fehlercode (Rückgabewert ungleich 0) antwortet. Weitere Details: Antora: Log Failure Level.

Fehlerbehandlung: Wenn der Antora-Build fehlschlägt (s. Parameter failure_level), schlägt der Workflow ebenfalls fehl. Wenn der Workflow durch einen Pull Request gestartet wurde, kann das Repository so konfiguriert werden, dass ein fehlschlagender Antora-Build den Merge blockiert.

Parameter

Eingabe	Erforderlich	Standardwert	Beschreibung
log_level	Nein	info	Antora: Log Severity Level
failure_level	Nein	fatal	Antora: Log Failure Level
Secrets
ANTORA_TRIGGER_TOKEN	Ja		GitHub-Token zum Auslösen des Antora-Builds

Nutzung zur Veröffentlichung eines Releases

on:
  push:
    tags:
      - '^\\d+\\.\\d+\\.\\d+$'

jobs:
  Build:
    uses: IsyFact/isy-github-actions-templates/.github/workflows/docs_build_template.yml@main (1)
    secrets:
      ANTORA_TRIGGER_TOKEN: ${{ secrets.ANTORA_TRIGGER_TOKEN }}

1. Für die Verwendung eines stabilen Standes muss eine Release-Version gesetzt werden.

Nutzung für die Kommentierung von PRs

on:
  pull_request:
    types: [ opened, synchronize, reopened ]

jobs:
  Build:
    uses:  IsyFact/isy-github-actions-templates/.github/workflows/docs_build_template.yml@main
    secrets:
      ANTORA_TRIGGER_TOKEN: ${{ secrets.ANTORA_TRIGGER_TOKEN }}

Create Release Template

Mithilfe des Templates maven_create_release_template.yml wird automatisch ein Release aus einem Tag heraus erstellt. Die Datei CHANGELOG.md im jeweiligen Repository wird als Release Notes verwendet und dargestellt.

Dependabot Auto Changelog Template

Mithilfe des Templates dependabot_auto_changelog_template.yml wird automatisch ein Changelog-Eintrag in einem Dependabot Merge-Request erstellt. Dieser wird unter der Überschrift Dependency Upgrades zusammengefasst.

Semgrep Template

Das Template semgrep.yml führt einen Semgrep-Sicherheitsscan durch. Es nutzt das offizielle Semgrep-Container-Image und prüft den Code auf Sicherheitslücken und Best Practices.

Das Template verwendet die Semgrep-Regeln aus dem Verzeichnis .github/config/semgrep dieses Repositories. Diese werden automatisch aus dem Template-Repository geladen, sodass keine lokale Kopie im aufrufenden Repository erforderlich ist.

Nutzung

on:
  pull_request:
    branches:
      - main

jobs:
  semgrep-scan:
    uses: IsyFact/isy-github-actions-templates/.github/workflows/semgrep.yml@<version>