# 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

```text
.
├── .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:

```bash
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
```bash
clang-format --dry-run --Werror main.cpp tests/test_main.cpp
```

### Formatierung anwenden
```bash
clang-format -i main.cpp tests/test_main.cpp
```

### CI-Policy lokal testen
```bash
python3 ci/check_pr_policies.py
```

### Build lokal ausführen
```bash
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:

```text
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