diff --git a/AGENTS.md b/AGENTS.md index 275cfca..a2ce60e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,8 +31,12 @@ Dieses Dokument dient als technischer Leitfaden und Kontextdokument für KI-Codi │ └── config.toml # Linker für Cross-Target-Kompilierung & Registry-Konfiguration ├── .gitea/ │ └── workflows/ -│ ├── main.yaml # CI/CD: Stabile Builds, Multi-Arch-Paketierung, Release & Upload -│ └── testing.yaml # CI/CD: Preview-Builds & Testing-Pakete +│ ├── main.yaml # CI/CD: Stabile Builds, Multi-Arch-Paketierung, Release & Upload +│ ├── 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` und baut/veröffentlicht das Docker-Container-Image mit den Tags `:latest`, `:`, `:v` und `:.`. - - `push` auf `testing`: Baut Binaries & Pakete für den `testing`-Kanal, erstellt ein Pre-Release `v-preview` und baut/veröffentlicht das Docker-Container-Image ausschließlich mit eindeutigen Testing-Tags (`:testing`, `:-preview`, `:-testing`, `:-preview.`, `:testing-`). 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` und baut/veröffentlicht das Docker-Container-Image mit den Tags `:latest`, `:`, `:v` und `:.`. +- `push` auf `testing` (`testing.yaml`): Baut Binaries & Pakete für den `testing`-Kanal, erstellt ein Pre-Release `v-preview` und baut/veröffentlicht das Docker-Container-Image ausschließlich mit eindeutigen Testing-Tags (`:testing`, `:-preview`, `:-testing`, `:-preview.`, `:testing-`). 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/` 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. diff --git a/README.md b/README.md index e3fcbcf..07d4880 100644 --- a/README.md +++ b/README.md @@ -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. @@ -202,8 +204,12 @@ services: │ └── config.toml # Linker- & Cargo-Konfiguration ├── .gitea/ │ └── workflows/ -│ ├── main.yaml # CI/CD: Release, Pakete & Container (Stable) -│ └── testing.yaml # CI/CD: Preview, Pakete & Container (Testing) +│ ├── main.yaml # CI/CD: Release, Pakete & Container (Stable) +│ ├── 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.