SonarQube-Analyse als geteilten Baustein aufnehmen

Neuer Baustein sonar-analysis.yml, on: workflow_call. Ein Waechter fuer die
Voraussetzungen des Aufrufers, Checkout mit vollstaendiger Historie, dann die
offizielle Scan-Action. Beide Actions auf einen Commit gepinnt.

Projektspezifisches steht in der sonar-project.properties des aufrufenden
Repositories, nicht hier - damit ist der Workflow fuer jedes Repository
identisch und ein zweiter Abnehmer kostet eine Datei mit drei Zeilen.

Kein Quality-Gate-Schritt, und das absichtlich: Die Community Build analysiert
nur den Hauptzweig, der Ausloeser liegt damit nach dem Merge, und dort ist
nichts mehr zu blockieren. Ein rotes main ohne Wirkung nimmt die
Glaubwuerdigkeit der uebrigen Pruefungen mit. Die zwei Bedingungen, unter denen
ein Gate richtig waere, stehen im README und als Kommentar an der Stelle, an
der der Schritt stuende.

SONAR_HOST_URL ist eine Variable des Aufrufers, SONAR_TOKEN sein Secret. Die
Adresse bleibt als Variable im Protokoll lesbar - erst das macht eine falsche
Adresse diagnostizierbar. Der Waechter prueft beide, bevor er abbricht, damit
ein Repository ohne beide das in einem Lauf erfaehrt.

Beide Eingaben sind type: string, auch project-base-dir: Boolesche
workflow_call-Eingaben kommen auf dieser Gitea-Version nicht an (Issue #4), und
die Regel gilt fuer jede Eingabe hier, damit sie nicht je Datei neu entschieden
wird.

Die Langform - warum fetch-depth: 0 nicht optional ist, warum kein
Docker-Runner noetig ist, was der Scanner zur Laufzeit holt und was an diesem
Baustein noch nicht gemessen ist - steht im Wiki unter sonar-analysis.

Der Baustein ist ab v4 verfuegbar; die Tag-Nummer bezeichnet wie bisher den
Zustand des Repositories und nicht die Version einer Datei.

README.md

@@ -269,6 +269,91 @@ Der Registry-Zugang selbst liegt in 1Password
 (`GitHub-Actions/jlab-registry-access`: `username`, `password`, `charts-url`) und
 muss in Gitea nicht hinterlegt werden.
 
+### `.gitea/workflows/sonar-analysis.yml`
+
+Schickt den Baum des aufrufenden Repositories durch eine **SonarQube-Analyse**.
+Der Baustein checkt mit vollständiger Historie aus und ruft dann die offizielle
+Scan-Action auf; alles Projektspezifische — Projektschlüssel, Ausschlüsse,
+Quellpfade — steht in der `sonar-project.properties` des aufrufenden
+Repositories, nicht hier. Läuft auf `ubuntu-latest`.
+
+**Die Analyse ist kein Torwächter.** Es gibt bewusst keinen
+Quality-Gate-Schritt: Auf der SonarQube Community Build wird nur der Hauptzweig
+analysiert, der Auslöser liegt damit **nach** dem Merge, und dort ist nichts
+mehr zu blockieren. Ein rotes Gate färbte nur `main` rot, und einen Dauerzustand
+lernt man zu ignorieren. Sinnvoll wird es erst, wenn PR-Analyse verfügbar ist
+oder ein Deployment an diesem Workflow hängt — bis dahin ist ein Gate hier eine
+Verschlechterung und keine vergessene Zeile. Ein Befund ist eine Beobachtung des
+Zustands, und wer ihn sehen will, schaut in SonarQube.
+
+#### Eingaben
+
+| Eingabe            | Pflicht | Vorgabe | Bedeutung |
+| ------------------ | ------- | ------- | --------- |
+| `args`             | nein    | —       | Zusätzliche Argumente für den Sonar-Scanner-CLI, unverändert an die Scan-Action weitergegeben. Für einen einmaligen Diagnoselauf, etwa `-Dsonar.verbose=true` |
+| `project-base-dir` | nein    | `.`     | Verzeichnis, in dem die Analyse beginnt (`sonar.projectBaseDir`); die `sonar-project.properties` wird relativ dazu gesucht |
+
+Beide Eingaben sind `type: string`. Das ist kein Versehen: Boolesche
+`workflow_call`-Eingaben kommen auf dieser Gitea-Version nicht an — bei grünem
+Lauf. Siehe
+[Issue #4](https://git.jk-dev.de/workflow-util/pipelines/issues/4) und die
+Begründung im Abschnitt zu `push` oben.
+
+Die Vorgabe von `project-base-dir` ist `.` und nicht leer, weil die Scan-Action
+selbst `.` als Vorgabe hat: Ein leerer Wert würde durchgereicht und überschriebe
+diese Vorgabe, statt sie stehen zu lassen.
+
+#### Aufrufbeispiel
+
+```yaml
+name: SonarQube
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  sonar:
+    uses: workflow-util/pipelines/.gitea/workflows/sonar-analysis.yml@v4
+    secrets: inherit
+```
+
+`secrets: inherit` ist notwendig — der Workflow braucht `SONAR_TOKEN` aus dem
+aufrufenden Repository.
+
+Der Baustein löst sich nicht selbst aus. Wann analysiert wird, entscheidet die
+Hülle im aufrufenden Repository über ihr eigenes `on:` — üblicherweise ein
+`push` auf `main`, weil die Community Build ausschließlich den Hauptzweig
+analysiert.
+
+#### Voraussetzungen im aufrufenden Repository
+
+| Name                      | Art                 | Zweck |
+| ------------------------- | ------------------- | ----- |
+| `SONAR_HOST_URL`          | Variable            | Adresse des SonarQube-Servers, etwa `https://sonar.example.com` — ohne Pfad dahinter |
+| `SONAR_TOKEN`             | Secret              | Token mit dem Recht, Analysen auszuführen; soll das Projekt beim ersten Lauf selbst entstehen, zusätzlich das Recht zum Anlegen. Kommt über `secrets: inherit` |
+| `sonar-project.properties` | Datei im Repository | Trägt mindestens `sonar.projectKey`. Der Schlüssel sollte den Eigentümer enthalten (`<owner>_<repo>`), weil die Instanz mehrere Eigentümer bedient und ein nackter Repository-Name beim zweiten kollidiert |
+
+Dass die Adresse eine **Variable** ist und kein Secret, ist Absicht: Sie ist
+kein Zugangsdatum, und als Variable bleibt sie im Protokoll lesbar — erst das
+macht eine falsche Adresse überhaupt diagnostizierbar.
+
+Beides gehört dem aufrufenden Repository, nicht diesem Baustein — ein geteilter
+Baustein trägt weder die Infrastruktur-Adresse eines einzelnen Mandanten noch
+dessen Token. Der Preis sind zwei Voraussetzungen, die man vergessen kann, und
+eine nicht gesetzte Variable kommt als leere Zeichenkette an. Deshalb prüft der
+erste Schritt beide und benennt beim Abbruch die Einstellung samt Ort; geprüft
+wird vollständig, bevor abgebrochen wird, damit ein Repository ohne beide das in
+einem Lauf erfährt und nicht in zwei.
+
+Für `SONAR_TOKEN` fängt der Wächter allerdings nur den Fall eines leeren oder
+nicht durchgereichten Secrets. Ein **ganz fehlendes** kommt nie so weit: Der
+Workflow deklariert es als `required`, und ein fehlendes Pflicht-Secret lässt auf
+dieser Instanz die Job-Erzeugung scheitern — der Lauf steht dann ohne Schritte
+da. Das ist hier der verständliche Fall, denn ohne Token gibt es keine Analyse;
+nachzulesen im Wiki unter
+[Gemessenes-Verhalten](https://git.jk-dev.de/workflow-util/pipelines/wiki/Gemessenes-Verhalten).
+
 ## Auf einen Tag zeigen, nicht auf `@main`
 
 Aufrufe bitte immer an einen Tag binden:
@@ -294,15 +379,17 @@ stehen; wer umstellt, wechselt auf `@v2` und schreibt `push: 'true'` bzw.
 ### Die Nummer bezeichnet den Zustand des Repositories
 
 Tags gelten hier **repository-weit**, nicht je Datei. `v3` ist der Stand, ab dem
-es `publish-helm-chart.yml` gibt; unter `v1` und `v2` existiert die Datei nicht,
-ein Aufruf auf `@v2` findet sie also nicht.
+es `publish-helm-chart.yml` gibt, `v4` der Stand, ab dem es
+`sonar-analysis.yml` gibt; unter `v1` und `v2` existiert keine der beiden
+Dateien, ein Aufruf auf `@v2` findet sie also nicht.
 
 Das hat eine Folge, die man kennen muss, weil sie sonst als Fehler gelesen wird:
-Wer künftig `docker-build-push.yml` ändert, erhöht auf `v4` — und ein Aufruf von
+Wer künftig `docker-build-push.yml` ändert, erhöht auf `v5` — und ein Aufruf von
 `publish-helm-chart.yml@v3` bleibt gültig und richtig, obwohl sich an dieser
 Datei nichts geändert hat. Die Nummer ist keine Dateiversion. Umgekehrt zwingt
 eine brechende Änderung an einem Baustein die Aufrufer der anderen zu nichts:
 Sie bleiben auf ihrem Tag stehen, bis sie bewusst nachziehen.
 
-`v3` selbst ist additiv. Der neue Baustein ändert an `docker-build-push.yml`
-nichts, bestehende Aufrufer auf `@v2` bleiben unberührt.
+`v3` und `v4` sind beide additiv. Sie nehmen je einen Baustein hinzu und ändern
+an den vorhandenen nichts; bestehende Aufrufer auf `@v2` bzw. `@v3` bleiben
+unberührt.