Docs: AGENTS.md & README.md an aktuelle CI/CD-Pipeline angepasst

Beide Dokumente hinkten dem tatsaechlichen Stand der .gitea/workflows/ und renovate.json hinterher. Ergaenzt: - Neue Workflow-Dateien (unit-tests, security-scan, trufflehog-scan, renovate) und renovate.json in den Projektstruktur-Uebersichten - AGENTS.md: neuer Abschnitt 5 mit Branch-Flow, actions/cache-Details inkl. der target/-Bereinigungs-Falle, der Build-Nummer-Logik ueber die Gitea-Packages-API und der Renovate-Gruppierung/baseBranches - README.md: zwei weitere CI-Badges sowie ein kurzer CI/CD & Contributing- Abschnitt fuer Branch-Flow, PR-Tests, Security-Scans und Renovate Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kh9v73QApBwJj96w6A8R55
2026-09-10 22:50:00 +02:00
parent 3d33972e98
commit 8359d6e4bf
2 changed files with 55 additions and 10 deletions
@@ -32,7 +32,11 @@ Dieses Dokument dient als technischer Leitfaden und Kontextdokument für KI-Codi
 ├── .gitea/
 │   └── workflows/
 │       ├── main.yaml            # CI/CD: Stabile Builds, Multi-Arch-Paketierung, Release & Upload
-│       └── testing.yaml        # CI/CD: Preview-Builds & Testing-Pakete
+│       ├── testing.yaml         # CI/CD: Preview-Builds & Testing-Pakete
+│       ├── unit-tests.yaml      # CI: cargo test bei PRs mit Ziel-Branch testing
+│       ├── security-scan.yaml   # CI: Trivy (vuln/secret/misconfig) & OSV-Scanner
+│       ├── trufflehog-scan.yaml # CI: TruffleHog Secret-Scanning
+│       └── renovate.yaml        # CI: Renovate Dependency-Updates (self-hosted, wöchentlich)
 ├── scripts/
 │   ├── get-build-number.py     # Ermittelt automatisch die nächste Revisions-/Build-Nummer
 │   └── package-arch.py         # Erzeugt native Arch Linux .pkg.tar.zst Pakete
@@ -52,6 +56,7 @@ Dieses Dokument dient als technischer Leitfaden und Kontextdokument für KI-Codi
 ├── Dockerfile                  # Minimales & gehärtetes Runtime-Container-Image
 ├── docker-compose.example.yml  # Beispielkonfiguration für Docker Compose
 ├── Cargo.toml                  # Projekt-Manifest & Metadaten für deb, rpm und arch
+├── renovate.json               # Renovate-Konfiguration (baseBranches, Gruppierung, Custom-Manager)
 ├── LICENSE                     # Lizenztext
 ├── README.md                   # Benutzerdokumentation
 └── AGENTS.md                   # Dieses Agenten-Handbuch
@@ -77,7 +82,7 @@ Bei Änderungen an Binärnamen, Abhängigkeiten oder Beschreibungen müssen die
   - `pkgrel`, `arch`, `depends`, `optdepends`.

 ### 3.3 Skripte in `scripts/`
- **Generizität**: Die Skripte dürfen keine hardcodierten Anwendungsnamen, spezifischen Abhängigkeiten oder projektspezifischen URLs enthalten. Alle Werte müssen dynamisch aus `Cargo.toml` oder Umgebungsvariablen (`BUILD_NUMBER`, `GITEA_URL`, `REPO`, `TOKEN`) ermittelt werden.
+- **Generizität**: Die Skripte dürfen keine hardcodierten Anwendungsnamen, spezifischen Abhängigkeiten oder projektspezifischen URLs enthalten. Alle Werte müssen dynamisch aus `Cargo.toml` oder Umgebungsvariablen (`BUILD_NUMBER`, `GITEA_URL`, `REPO`, `REPO_OWNER`, `TOKEN`) ermittelt werden.
 - **Python-Kompatibilität**: Verwende Standard-Python 3 ohne externe PyPI-Abhängigkeiten (nur Standardbibliothek).

 ### 3.4 Container-Sicherheit & Persistenz
@@ -119,8 +124,32 @@ python3 scripts/package-arch.py --arch x86_64 --pkgrel 1

 ## 5. CI/CD-Pipeline Details

- **Trigger**:
-  - `push` auf `main`: Baut Binaries für alle 3 Architekturen, baut `.deb`, `.rpm` und `.pkg.tar.zst`, lädt sie in die Gitea Package Registry hoch, erstellt ein Gitea Release `v<VERSION>` und baut/veröffentlicht das Docker-Container-Image mit den Tags `:latest`, `:<VERSION>`, `:v<VERSION>` und `:<VERSION>.<BUILD_NUMBER>`.
-  - `push` auf `testing`: Baut Binaries & Pakete für den `testing`-Kanal, erstellt ein Pre-Release `v<VERSION>-preview` und baut/veröffentlicht das Docker-Container-Image ausschließlich mit eindeutigen Testing-Tags (`:testing`, `:<VERSION>-preview`, `:<VERSION>-testing`, `:<VERSION>-preview.<BUILD_NUMBER>`, `:testing-<BUILD_NUMBER>`). Der Tag `:latest` ist strikt dem `main`-Workflow vorbehalten.
- **Secrets**:
-  - `PACKAGE_TOKEN` (bzw. Fallback-Token-Namen wie `RELEASE_TOKEN`, `GITEA_TOKEN`) wird für API-Zugriffe auf Gitea Packages, Container Registry und Releases verwendet.
+### 5.1 Branch-Flow & Trigger
+Promotion-Flow: `dev` → `testing` → `main`, ausschließlich per Merge (nie direkt gepusht).
+
+- `pull_request` mit Ziel-Branch `testing` (`unit-tests.yaml`): führt `cargo test` aus (`types: opened, synchronize, reopened`).
+- `push` auf `main` (`main.yaml`): Baut Binaries für alle 3 Architekturen, baut `.deb`, `.rpm` und `.pkg.tar.zst`, lädt sie in die Gitea Package Registry hoch, erstellt ein Gitea Release `v<VERSION>` und baut/veröffentlicht das Docker-Container-Image mit den Tags `:latest`, `:<VERSION>`, `:v<VERSION>` und `:<VERSION>.<BUILD_NUMBER>`.
+- `push` auf `testing` (`testing.yaml`): Baut Binaries & Pakete für den `testing`-Kanal, erstellt ein Pre-Release `v<VERSION>-preview` und baut/veröffentlicht das Docker-Container-Image ausschließlich mit eindeutigen Testing-Tags (`:testing`, `:<VERSION>-preview`, `:<VERSION>-testing`, `:<VERSION>-preview.<BUILD_NUMBER>`, `:testing-<BUILD_NUMBER>`). Der Tag `:latest` ist strikt dem `main`-Workflow vorbehalten.
+- `push`/`pull_request`/wöchentlich (`security-scan.yaml`, `trufflehog-scan.yaml`): Trivy (vuln/secret/misconfig) & OSV-Scanner bzw. TruffleHog laufen auf `main`/`testing`/`dev` sowie bei jedem PR; Funde werden per `scripts/report-security-issue.py` als Gitea-Issue gemeldet.
+- wöchentlich, `workflow_dispatch` (`renovate.yaml`): Renovate (containerisiert via `ghcr.io/renovatebot/renovate`) prüft Dependency-Updates, siehe 5.5.
+
+### 5.2 Caching (`actions/cache@v6`)
+`main.yaml`/`testing.yaml` cachen mehrere Verzeichnisse, um wiederholte Cross-Compile-Builds zu beschleunigen:
+- `~/.cargo/registry`, `~/.cargo/git`, `target` – Cache-Key basiert auf `hashFiles('Cargo.lock')`.
+- `~/.rustup/.../lib/rustlib/<target>` für die zwei zusätzlichen Cross-Targets – Cache-Key basiert auf der **aufgelösten** `rustc --version`, nicht auf dem gleitenden `stable`-Label. Sonst könnte nach einem Rust-Update eine veraltete gecachte Std-Lib mit einem neueren Compiler kombiniert werden.
+- `~/.cargo/bin` für `cargo-binstall`/`cargo-deb`/`cargo-generate-rpm` – alle drei sind auf feste Versionen gepinnt (Job-`env`), nicht auf `latest`.
+
+**Wichtige Falle:** `target/debian`, `target/generate-rpm` und `target/arch` hängen ebenfalls unter `target` und werden dadurch mitgecacht, aber von keinem Tool automatisch geleert. Vor jedem Paketbau werden sie daher explizit per `rm -rf` bereinigt – sonst werden alte, bereits hochgeladene Paket-Dateien aus früheren Builds erneut mit hochgeladen, und die Gitea Package Registry lehnt sie mit `409 Conflict` ab (Paket-Dateien sind dort unveränderlich). Bei neuen Paketierungs-Outputs außerhalb dieser drei Ordner muss diese Bereinigung entsprechend erweitert werden.
+
+### 5.3 Build-Nummer (`scripts/get-build-number.py`)
+Pro CI-Lauf wird genau **eine** Build-Nummer ermittelt und identisch an `cargo deb`, `cargo generate-rpm` und `package-arch.py --pkgrel` weitergereicht – `.deb`, `.rpm` und Arch-Paket tragen also immer dieselbe Nummer. Zur Ermittlung wird pro Paket-Typ (`debian`, `rpm`, `arch`) gezielt `GET /api/v1/packages/{owner}/{type}/{name}/-/latest` abgefragt (ein Request pro Typ, kein Paging, unbeeinflusst von Docker-Tags/anderen Paketen desselben Owners); das Maximum aller drei Typen + 1 ergibt die neue Nummer. Eine pauschale, ungefilterte Abfrage über alle Pakete des Owners (`GET /packages/{owner}`) darf hier nicht mehr verwendet werden, da sie durch Docker-Image-Tags & Co. verdrängt werden kann.
+
+### 5.4 Secrets
+- `PACKAGE_TOKEN` (bzw. Fallback-Token-Namen wie `RELEASE_TOKEN`, `GITEA_TOKEN`) wird für API-Zugriffe auf Gitea Packages, Container Registry und Releases verwendet.
+- `SECURITY_TOKEN` für die Security-Scan-Workflows (Gitea-Issue-Erstellung).
+- `RENOVATE_TOKEN` für den Renovate-Workflow.
+
+### 5.5 Renovate (`renovate.json`)
+- `baseBranches: ["dev"]` – Renovate liest Dependency-Dateien ausschließlich von `dev` und öffnet PRs nur dort, passend zum `dev → testing → main`-Promotion-Flow. Die Konfigurationsdatei selbst muss trotzdem über den Gitea-Default-Branch auffindbar sein.
+- Drei Gruppen (`packageRules`), jeweils mit `separateMajorMinor: false`/`separateMinorPatch: false` (sonst reißt Renovate Major-Updates trotz `groupName` standardmäßig in einen eigenen PR): "Gitea Actions" (dateibasiert über `matchFileNames: [".gitea/workflows/**"]`, deckt auch die Custom-Manager unten ab), "Cargo Dependencies", "Docker-Images".
+- `customManagers` (Regex) tracken Versionen, die als reine Strings in `run:`-Blöcken stecken und vom `github-actions`-Manager nicht erkannt werden: `TRIVY_VERSION`, `OSV_SCANNER_VERSION`, `TRUFFLEHOG_VERSION`, `CARGO_BINSTALL_VERSION`, `CARGO_DEB_VERSION`, `CARGO_GENERATE_RPM_VERSION`. Wird in einer Workflow-Datei eine weitere Tool-Version nach demselben Muster (`NAME_VERSION: "x.y.z"`) gepinnt, muss hier ein passender Eintrag ergänzt werden, sonst bleibt sie von Renovate unbemerkt veraltet.
@@ -2,6 +2,8 @@

 [![Main Release & Publish](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions/workflows/main.yaml/badge.svg?branch=main)](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions?workflow=main.yaml)
 [![Testing Build, Publish & Preview Release](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions/workflows/testing.yaml/badge.svg?branch=testing)](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions?workflow=testing.yaml)
+[![Security Scans](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions/workflows/security-scan.yaml/badge.svg?branch=main)](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions?workflow=security-scan.yaml)
+[![TruffleHog Secret Scan](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions/workflows/trufflehog-scan.yaml/badge.svg?branch=main)](https://gitea.creative-dragonslayer.de/Linuxapps/MirrorPackage/actions?workflow=trufflehog-scan.yaml)

 Automatisiertes Werkzeug zum Extrahieren, Herunterladen und Spiegeln vorkompilierter Linux-Pakete aus GitHub-Releases in eine selbstgehostete Gitea- / Forgejo-Paket-Registry.

@@ -203,7 +205,11 @@ services:
 ├── .gitea/
 │   └── workflows/
 │       ├── main.yaml            # CI/CD: Release, Pakete & Container (Stable)
-│       └── testing.yaml        # CI/CD: Preview, Pakete & Container (Testing)
+│       ├── testing.yaml         # CI/CD: Preview, Pakete & Container (Testing)
+│       ├── unit-tests.yaml      # CI: cargo test bei PRs gegen testing
+│       ├── security-scan.yaml   # CI: Trivy & OSV-Scanner
+│       ├── trufflehog-scan.yaml # CI: TruffleHog Secret-Scanning
+│       └── renovate.yaml        # CI: automatisierte Abhängigkeits-Updates (Renovate)
 ├── scripts/
 │   ├── get-build-number.py     # Dynamische Ermittlung der Build-/Revisionsnummer
 │   └── package-arch.py         # Erstellung nativer Arch Linux-Pakete
@@ -223,6 +229,7 @@ services:
 ├── Dockerfile                  # Gehärtetes, minimales Runtime-Container-Image
 ├── docker-compose.example.yml  # Beispielkonfiguration für Docker Compose
 ├── Cargo.toml                  # Projekt-Manifest und Paketierungs-Metadaten
+├── renovate.json               # Renovate-Konfiguration für automatisierte Abhängigkeits-Updates
 ├── LICENSE                     # GPL-3.0-or-later Lizenztext
 ├── AGENTS.md                   # Agenten- & Entwickler-Richtlinien
 └── README.md                   # Projektdokumentation
@@ -251,6 +258,15 @@ cargo build --release

 ---

+## CI/CD & Contributing
+
+- **Branch-Flow**: Änderungen durchlaufen `dev` → `testing` → `main`, jeweils per Merge (nie direkt gepusht).
+- **Pull Requests gegen `testing`** lösen automatisch `cargo test` aus.
+- **Sicherheits-Scans** (Trivy, OSV-Scanner, TruffleHog) laufen bei jedem Push auf `main`/`testing`/`dev` sowie bei jedem Pull Request; Funde werden als Gitea-Issue gemeldet.
+- **Abhängigkeits-Updates** werden automatisiert über [Renovate](https://docs.renovatebot.com/) als PRs gegen `dev` vorgeschlagen.
+
+---
+
 ## Lizenz

 Dieses Projekt ist unter der [GPL-3.0-or-later](LICENSE)-Lizenz lizenziert.