# ci-templates — org-weites Quality-Gate

Reusable Workflow fuer alle Orgs. Scans (betterleaks/semgrep/trivy/actionlint) laufen per
**Default**; Sprach-Linter (python/node/php) sind **opt-in**. **Report-only** per Default,
`blocking: true` macht SAST/Vuln/Lint zum harten Gate. **Secrets (betterleaks) sind IMMER hart.**

## Secret-Scan: betterleaks statt gitleaks (seit 2026-09-11)
gitleaks ist **feature-frozen** (letztes Release 03/2026, nur noch Security-Patches);
die Maintainer inkl. Original-Autor entwickeln **betterleaks** weiter (v1.8.1, MIT,
aktive Releases). betterleaks findet in denselben Repos deutlich mehr als gitleaks
(Bsp.: 34 -> 58 Treffer), kann Secrets per `validate` auf "noch aktiv?" pruefen und
filtert Rauschen per Expr-Regeln.

Zentrale Richtlinie liegt inline im Job `secret-scan` (`[extend] useDefault = true`
+ `[allowlist]`): Beispiel-Dateien (`.env.example`, `*.sample`, `*.template`),
Uebersetzungen (`i18n/*.json`), Abhaengigkeiten/Build (`node_modules`, `vendor`,
`dist`, Lockfiles) und Fixtures werden nicht gemeldet. **Nicht** ausgeschlossen:
`.env`/`.env.prod`, `docker-compose*`, Code und echte Config-Dateien - dort laesst
ein Fund den Gate fehlschlagen.

Pro Repo:
- `.betterleaks.toml` im Repo-Root **ersetzt** die zentrale Richtlinie (Vorrang).
- `.betterleaksignore` im Repo-Root nimmt einzeln akzeptierte Altlasten auf.
  Format `<pfad>:<regel>:<zeile>` (empfohlen — greift auch nach neuen Commits) oder
  der volle `Fingerprint` aus dem JSON-Report `<commit>:<pfad>:<regel>:<zeile>`.
  Fingerprints lokal per `betterleaks git . --report-format json --report-path r.json`.
- Inline-Ausnahme direkt im Code: Kommentar `betterleaks:allow` in der Zeile.

## WICHTIG — Sichtbarkeit (Gitea-Limitation, verifiziert 2026-08-25)
Private reusable Workflows koennen von anderen Repos NICHT gelesen werden
("no permission to read reusable workflow"). Zwei Adoptions-Modi:

### A) ci-templates PUBLIC  (empfohlen fuer org-weit)
Pro Repo `.gitea/workflows/quality.yml`:
```yaml
name: quality
on: [push, pull_request]
jobs:
  quality:
    uses: digiflo/ci-templates/.gitea/workflows/quality.yml@main
    with:
      python: true       # node: true / php: true je nach Repo
      # blocking: true    # spaeter: hartes Gate
```

### B) ci-templates PRIVAT -> lokale Kopie pro Repo
Komplette `quality.yml` ins Ziel-Repo kopieren, lokal referenzieren
(`uses: ./.gitea/workflows/quality.yml`). Nachteil: Updates muessen nachgezogen werden.

## Inputs
| Input | Default | Wirkung |
|-------|---------|---------|
| skip_secret_scan / skip_sast / skip_vuln | false | Scan abschalten |
| python / node / php | false | Sprach-Linter aktivieren |
| blocking | false | SAST/Vuln/Lint hart (Secrets immer hart) |

## Constraints
- Runner `ct117-docker` (catthehacker, Debian/PEP668): pip mit `--break-system-packages`.
- **KEINE** neuen Docker-Hub-Images im Job (unauth Pull-Limit) -> Tools via GitHub-Release/pip.
- Fuer harte Gates zusaetzlich Branch-Protection (Required status checks) auf `main` setzen.