sandbox

Test- und Beispiel-Repository für einen lokalen Dev-Platform-Stack mit:

• Gitea 1.22.x
• Jenkins Multibranch Pipeline
• Webhook-Trigger von Gitea nach Jenkins
• C++/CMake/Ninja Build
• PR Policy Checks
• Docker-basiertem CI-Agent

---

Aktueller Funktionsumfang

Dieses Repository und das zugehörige Jenkins/Gitea-Setup können aktuell:

SCM / Repository

• Repository in Gitea hosten
• Änderungen per Git Push empfangen
• Pull Requests in Gitea verwalten
• Webhooks von Gitea an Jenkins senden

Jenkins / CI

• Jenkins als Multibranch Pipeline verwenden
• Branches und Pull Requests automatisch erkennen
• Builds durch Push Events automatisch starten
• Build-Status an Gitea zurückmelden

Build-Umgebung

• Pipeline-Schritte in einem Docker-Container ausführen
• dafür ein vorbereitetes CI-Image verwenden
• folgende Tools im CI bereitstellen:
  • python3
  • clang-format
  • cmake
  • ninja
  • git
  • g++
  • make

C++ Projektbasis

• minimales Beispielprogramm über main.cpp
• Build mit CMake
• Testausführung über CTest
• Testdateien unter tests/

---

Repository-Struktur

.
├── .clang-format
├── CMakeLists.txt
├── Dockerfile.ci
├── Jenkinsfile
├── README.md
├── ci/
│   └── check_pr_policies.py
├── main.cpp
└── tests/
    └── test_main.cpp

---

CI / Jenkins Pipeline

Die Jenkins-Pipeline umfasst aktuell diese Schritte:

1. Checkout

   • Repository aus Gitea auschecken
   • zusätzliche Fetch-/Submodule-Schritte ausführen

2. Policy Checks

   • ci/check_pr_policies.py ausführen
   • Formatierung und Testbezug prüfen

3. Configure

   • CMake-Buildverzeichnis erzeugen

4. Build

   • Projekt mit CMake/Ninja bauen

5. Test

   • Tests über ctest ausführen

6. Cleanup

   • Workspace am Ende bereinigen

---

PR Policy Checks

Für geänderte C/C++-Dateien werden in der CI folgende Regeln geprüft:

• .clang-format muss im Repository vorhanden sein
• geänderte C/C++-Dateien müssen mit clang-format konform sein
• zu geänderten C/C++-Dateien muss ein passender Test unter tests/ oder test/ vorhanden sein

Vergleichsbasis der Policy

Die Policy unterscheidet zwischen Pull-Request-Builds und normalen Branch-Builds:

• bei Pull Requests wird gegen den Zielbranch verglichen, z. B. origin/main
• bei normalen Branch-Builds wird auf eine lokale Vergleichsbasis zurückgefallen, z. B. HEAD~1, falls kein Zielbranch-Ref verfügbar ist

Damit funktioniert die Policy sowohl in PR-Builds als auch bei regulären Branch-Indexing- oder Branch-Build-Läufen.

---

Docker-basierter CI-Agent

Die Pipeline verwendet ein vorbereitetes Docker-Image statt bei jedem Lauf ein neues Build-Image zu erzeugen.

Beispiel

Das Image wird lokal oder auf dem Build-Host gebaut:

docker build -t lifemaps/ci-cpp:latest -f Dockerfile.ci .

Danach nutzt Jenkins dieses Image als Build-Agent.

Vorteile

• schnellere PR-Builds
• reproduzierbare Toolchain
• keine langen apt install-Phasen pro Build
• saubere Trennung zwischen Jenkins-Controller und Build-Umgebung

---

Branch- und PR-Workflow

Der aktuelle Workflow unterstützt:

• Arbeiten auf Feature-Branches
• Öffnen von Pull Requests gegen main
• automatisches Bauen von PRs
• Rückmeldung des Build-Status an Gitea

Empfohlen ist:

• keine direkten Änderungen auf main
• Änderungen über Feature-Branch + Pull Request
• Merge erst nach erfolgreichem CI-Lauf

---

Lokales Arbeiten

Formatierung prüfen

clang-format --dry-run --Werror main.cpp tests/test_main.cpp

Formatierung anwenden

clang-format -i main.cpp tests/test_main.cpp

CI-Policy lokal testen

python3 ci/check_pr_policies.py

Build lokal ausführen

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel
ctest --test-dir build --output-on-failure

---

Voraussetzungen auf Jenkins-Seite

Für das Setup werden u. a. folgende Jenkins-Plugins benötigt:

• docker-workflow
• pipeline-model-definition
• workflow-scm-step
• workflow-cps
• ws-cleanup
• gitea
• git
• git-client
• scm-api
• workflow-multibranch

Zusätzlich muss der Jenkins-Container Zugriff auf Docker haben, z. B. über:

• Docker CLI im Jenkins-Container
• Mount von /var/run/docker.sock

---

Webhook / Automatischer Trigger

Gitea ist so konfiguriert, dass Push Events an Jenkins gemeldet werden.

Beispiel-Endpunkt:

https://jenkins.life-maps.com/gitea-webhook/post

Damit können automatisch Jenkins-Builds für Branches und Pull Requests ausgelöst werden.

---

Beispielziel des Repositories

Dieses Repository dient aktuell als:

• Referenz für Jenkins/Gitea-Integration
• Testumgebung für PR-Policies
• Minimalbeispiel für C++/CMake-basierte CI
• Grundlage für weitere CI- und Policy-Erweiterungen

---

Status

Aktuell ist das Setup geeignet für:

• Jenkins/Gitea-Webhook-Integration
• Pull-Request-basierte CI
• C++/CMake/Ninja Beispielprojekte
• Policy-basierte Qualitätsprüfungen im PR-Prozess