README auf das Wiki verweisen

Das Wiki dieses Repositories ist jetzt angelegt und traegt die Langform zu
beiden Bausteinen. Ohne einen Verweis von hier aus erfaehrt davon niemand, der
nur das README liest.

Die Aufteilung steht dabei gleich mit: Diese Datei bleibt die Kurzreferenz fuer
Aufrufer und wird nicht gekuerzt, das Wiki begruendet sie.

Part of jlab-cluster/helm-charts#66

.gitea/workflows/docker-build-push.yml

@@ -28,16 +28,37 @@ on:
         required: false
         default: '0'
         type: string
+      # Bewusst `type: string` und nicht `boolean` — siehe Issue #4. Auf dieser
+      # Gitea-Version (gemessen an 1.27.0) kommt eine boolesche
+      # workflow_call-Eingabe im aufgerufenen Workflow gar nicht an: weder ihre
+      # Vorgabe noch ein ausdruecklich uebergebenes `push: true`. `inputs.push`
+      # war in beiden Faellen leer, der Baustein baute immer im Pruefmodus und
+      # meldete dabei Erfolg. Alle Eingaben vom Typ string desselben Laufs
+      # (platforms, registry, image-owner, container-name) kamen korrekt an;
+      # push war die einzige boolesche und die einzige, die versagte.
+      #
+      # Wer das beim naechsten Aufraeumen "korrekt" auf boolean zurueckstellt,
+      # holt den Fehler still zurueck: nichts wird veroeffentlicht, und der
+      # Lauf bleibt gruen.
+      #
+      # Die Bedingung `inputs.push && inputs.push != 'false'` musste dafuer
+      # nicht angefasst werden. Sie wurde seinerzeit ausdruecklich so gebaut,
+      # dass sie Boolean und String vertraegt (Begruendung am
+      # 1Password-Schritt), und traegt die Umstellung unveraendert: 'true' ist
+      # truthy und ungleich 'false', 'false' ist truthy aber gleich 'false'.
       push:
         description: >-
-          Whether the built image is pushed. With push: false no credentials are
+          Whether the built image is pushed, as the string 'true' or 'false'.
-          fetched from 1Password and no registry login happens, so the workflow
+          Deliberately a string, not a boolean: boolean workflow_call inputs do
-          doubles as a build check. Caveat: the checkout token comes from the
+          not reach the called workflow on this Gitea version (see issue #4).
-          same 1Password step, so without push the checkout falls back to the
+          With push: 'false' no credentials are fetched from 1Password and no
-          job token — which cannot clone private submodules.
+          registry login happens, so the workflow doubles as a build check.
+          Caveat: the checkout token comes from the same 1Password step, so
+          without push the checkout falls back to the job token — which cannot
+          clone private submodules.
         required: false
-        default: true
+        default: 'true'
-        type: boolean
+        type: string
       container-name:
         required: true
         type: string
@@ -113,6 +134,24 @@ jobs:
       # gesetzt, bleibt die Variable leer und Docker nutzt seinen Default.
       DOCKER_HOST: ${{ vars.DOCKER_HOST }}
     steps:
+      # Issue #4 blieb so lange unbemerkt, weil nirgends sichtbar war, was
+      # ueberhaupt ankommt — und weil ein Lauf ohne Push genauso gruen aussieht
+      # wie einer mit. Der Schritt macht beides sichtbar: den rohen Wert der
+      # Eingabe und den daraus abgeleiteten Modus. Gleiches Muster wie
+      # "Docker-Socket ermitteln": rein informativ, mit `|| true` abgesichert,
+      # damit er den Job unter keinen Umstaenden scheitern laesst.
+      #
+      # Der Wert wird ueber die Umgebung gereicht statt in die Kommandozeile
+      # interpoliert; so bleibt er auch dann harmlos, wenn ein Aufrufer etwas
+      # Unerwartetes uebergibt.
+      - name: Eingaben melden
+        env:
+          PUSH_ROH: ${{ inputs.push }}
+          PUSH_MODUS: ${{ (inputs.push && inputs.push != 'false') && 'veroeffentlichen' || 'nur bauen' }}
+        run: |
+          echo "push (roh):        '${PUSH_ROH}'" || true
+          echo "Modus:             ${PUSH_MODUS}" || true
+
       # Der Token, den Gitea jedem Job stellt, taugt fuer zwei Dinge nicht:
       # Er gilt nur fuer das ausfuehrende Repository, waehrend die Submodule in
       # eigenen, privaten Repositories liegen — deren Klon scheitert an
@@ -135,6 +174,12 @@ jobs:
       # Strings sind truthy), `inputs.push == 'true'` waere beim echten Boolean
       # true falsch (ein Vergleich ueber Typgrenzen laeuft ueber Zahlen, 'true'
       # wird dabei zu NaN). Die Kombination aus beidem deckt alle vier Faelle ab.
+      #
+      # Genau deshalb blieb sie bei der Umstellung von push auf `type: string`
+      # (Issue #4) unveraendert: sie war von Anfang an fuer beide Schreibweisen
+      # gebaut. 'true' ergibt wahr, 'false' ergibt falsch, ein leerer Wert
+      # ergibt falsch — und die Boolean-Faelle gelten unveraendert weiter,
+      # falls ein Aufrufer doch einmal ein YAML-Boolean uebergibt.
       - name: Zugangsdaten aus 1Password laden
         id: op-secrets
         if: ${{ inputs.push && inputs.push != 'false' }}

.gitea/workflows/publish-helm-chart.yml

@@ -0,0 +1,249 @@
+name: Publish Helm Chart with patched Application Version
+
+# Called through "uses:" only, never triggered here. The thin wrappers in the
+# calling repository carry their own "workflow_dispatch" and "on: push", so the
+# workflow_dispatch block this file used to have is gone: a dispatch in THIS
+# repository would run against this repository's files, where there is no chart.
+#
+# The comments below are kept from the copy this file replaces, in English as
+# they were written. Each of them records something that was paid for once -
+# none of it is restating what the YAML already says.
+on:
+  workflow_call:
+    inputs:
+      chart-location:
+        required: false
+        type: string
+        default: "."
+        description: "location of the helm chart directory"
+      chart-name:
+        required: true
+        type: string
+        description: "name of the helm chart"
+      # Deliberately required and without a default, following the house rule
+      # of this repository: an owner segment is never guessed. The caller
+      # passes "${{ github.repository_owner }}", where the value is measured
+      # (jlab-cluster, run 282 of validate-charts.yml) - inside a workflow
+      # called from another repository it is documented to stay the caller's
+      # owner, but that is not measured on this Gitea version, and a published
+      # chart landing under the wrong owner is not worth relying on a context
+      # semantic for. As an input the value is evaluated in the caller, where
+      # it is known to be right.
+      #
+      # type: string, like every input here. On this Gitea version (measured on
+      # 1.27.0, issue #4) a boolean workflow_call input does not reach the
+      # called workflow at all - neither its default nor an explicitly passed
+      # value - while the run stays green. Every input of this block is
+      # therefore a string, even one that is a switch in meaning.
+      registry-owner:
+        required: true
+        type: string
+        description: >-
+          Owner segment of the chart registry URL, i.e. the <owner> in
+          <base>/<owner>/helm/api/charts. Deliberately has no default: an owner
+          segment is never guessed. Callers pass github.repository_owner, which
+          resolves in the calling repository, where the value is measured.
+    outputs:
+      chart-version:
+        description: "the version of the published helm chart"
+        value: ${{ jobs.publish-helm-chart.outputs.chart-version }}
+    secrets:
+      OP_CONNECT_TOKEN:
+        required: true
+jobs:
+  publish-helm-chart:
+    outputs:
+      chart-version: ${{ steps.get-chart-version.outputs.CHART_VERSION }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v7
+      - name: "Install Helm"
+        uses: azure/setup-helm@v5
+      # The Connect host is a variable of the CALLING repository, not a value
+      # wired into this file: a shared building block must not carry one
+      # tenant's infrastructure address. The price of that is a prerequisite
+      # that can be forgotten, and an unset variable arrives as an empty
+      # string. An empty connect-host does not fail here - it fails two steps
+      # later, inside the loading action, against a URL nobody can see. So the
+      # guard comes first and names the setting, the place to set it and the
+      # shape of the value.
+      - name: "Check the calling repository's prerequisites"
+        env:
+          OP_CONNECT_HOST: ${{ vars.OP_CONNECT_HOST }}
+        run: |-
+          if [ -z "$OP_CONNECT_HOST" ]; then
+            echo "::error::the variable OP_CONNECT_HOST is not set in the calling repository (Settings -> Actions -> Variables). It must hold the address of the 1Password Connect server, e.g. https://op-connect.example.com. This workflow deliberately does not hardcode a host."
+            exit 1
+          fi
+      - name: "Configure OP-Connect"
+        uses: 1password/load-secrets-action/configure@v5
+        with:
+          connect-host: ${{ vars.OP_CONNECT_HOST }}
+      # helm package exits 1 with "found in Chart.yaml, but missing in charts/
+      # directory" while a declared dependency has not been fetched, so this
+      # comes first. It is a no-op for every chart without a dependencies:
+      # block; ci/helm-dependencies.sh explains why it resolves from Chart.yaml
+      # instead of a committed Chart.lock. Note the consequence for the
+      # published artifact: the subchart .tgz is packaged INTO ours, so the
+      # version pinned in Chart.yaml is the version operators get, and nothing
+      # downstream ever sees the dependency again.
+      #
+      # The script belongs to the CALLING repository and that is unchanged by
+      # the move: the checkout above clones the repository the run belongs to -
+      # the caller - so ${{ github.workspace }} is the caller's tree and the
+      # script is the caller's copy. It is therefore a prerequisite of every
+      # caller, the same way OP_CONNECT_HOST is, and the guard below says so
+      # rather than letting the shell report a missing file.
+      - name: "Fetch chart dependencies"
+        env:
+          HELM_DEPENDENCIES_SCRIPT: ${{ github.workspace }}/ci/helm-dependencies.sh
+          CHART_NAME: ${{ inputs.chart-name }}
+        run: |-
+          test -x "$HELM_DEPENDENCIES_SCRIPT" || {
+            echo "::error::${HELM_DEPENDENCIES_SCRIPT} is missing or not executable - ci/helm-dependencies.sh is a script of the calling repository and this workflow runs it before helm package"
+            exit 1
+          }
+          "$HELM_DEPENDENCIES_SCRIPT" "$CHART_NAME"
+        working-directory: ${{ inputs.chart-location }}
+      - name: "Package Helm Chart"
+        run: helm package ${{ inputs.chart-name }}
+        working-directory: ${{ inputs.chart-location }}
+      - name: "Get Helm Chart Version"
+        id: get-chart-version
+        run: |-
+          CHART_VERSION=$(grep '^version:' ${{ inputs.chart-name}}/Chart.yaml | awk '{print $2}')
+          echo $CHART_VERSION
+          echo "CHART_VERSION=$CHART_VERSION" >> $GITHUB_OUTPUT
+        working-directory: ${{ inputs.chart-location }}
+      - name: "Load Chart Registry Credentials"
+        id: load-registry-creds
+        uses: 1password/load-secrets-action@v5
+        env:
+          OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
+          REGISTRY_PASSWORD: op://GitHub-Actions/jlab-registry-access/password
+          REGISTRY_USERNAME: op://GitHub-Actions/jlab-registry-access/username
+          REGISTRY_CHARTS_URL: op://GitHub-Actions/jlab-registry-access/charts-url
+      # The target is a classic, index-based Helm registry, not an OCI one, so
+      # there is no "helm registry login" session and no "helm push": the upload
+      # is a single HTTP POST of the packaged .tgz to
+      # <charts-url>/<owner>/helm/api/charts, authenticated per request.
+      #
+      # That URL is composed, not stored (jlab-cluster/helm-charts#63).
+      # charts-url holds only the base up to "/api/packages"; the owner segment
+      # comes from the registry-owner input, which the caller fills with
+      # github.repository_owner - measured as "jlab-cluster" in run 282 of
+      # validate-charts.yml, on a temporary step that was removed again. So no
+      # value pointing at the registry - not even a path segment - lives in the
+      # calling repository, and a second owner on the same instance needs no
+      # second setting. Two guards make the switch from the old shape loud
+      # instead of puzzling: charts-url is rejected unless it ends in
+      # "/api/packages" (an old full URL still carrying "/helm", "/api/charts"
+      # or the owner is named explicitly), and the owner is rejected when empty
+      # or when it holds characters that are not a path segment - an empty one
+      # would build "<base>//helm/api/charts", i.e. another bare 404 against a
+      # masked URL.
+      #
+      # Three further properties of this step are load-bearing and each of them
+      # was paid for once already.
+      #
+      # 1) The values are mapped into the step's own env block and read as quoted
+      # shell variables - never interpolated into the command line. load-secrets-
+      # action v5 no longer exports the loaded values as environment variables
+      # for later steps the way v4 did; only the step outputs carry them. Every
+      # "${{ env.* }}" reference therefore resolved to an empty string from that
+      # bump on, with nothing reporting an error - the loading step logs
+      # "Populating variable" and stays green either way. The ":?" guards fail
+      # loudly and name the op:// field that is missing, and quoting keeps an
+      # empty value from silently shifting arguments.
+      #
+      # 2) The credentials never reach the process list. "curl --user $U:$P"
+      # would put them in argv; "curl --config -" reads its options from stdin
+      # instead, so nothing sensitive appears in any argument. The price of that
+      # config file is its value syntax: an unquoted value ends at the first
+      # space (measured on curl 8.5.0 - "has space" arrived as "has"), so the
+      # step refuses whitespace in the credentials up front rather than letting
+      # a truncated password come back as a puzzling 401. A Gitea access token
+      # is 40 hex characters, so this only ever fires on a mis-entered item.
+      #
+      # 3) "--fail-with-body" is what makes a failed upload fail the job. Unlike
+      # "helm push", curl exits 0 on HTTP 401/403/409 unless asked not to - the
+      # publish would go green while nothing was uploaded. Measured against Gitea
+      # 1.24.7: a 401 without the flag is exit 0, with the flag exit 22, and the
+      # response body is still printed so the log names the cause.
+      #
+      # The file name is built from the chart name and the version read above
+      # instead of a "<chart>-*.tgz" glob: --upload-file takes exactly one file,
+      # and a glob matching two turns the second into curl's URL argument, while
+      # a glob matching none is passed through literally. Both fail obscurely.
+      # "helm package" keeps the "+" of a "1.4.0+up1.9.2" version verbatim in the
+      # file name, so "<name>-<version>.tgz" is an exact match (measured).
+      - name: "Upload Helm Chart to the Chart Registry"
+        env:
+          REGISTRY_PASSWORD: ${{ steps.load-registry-creds.outputs.REGISTRY_PASSWORD }}
+          REGISTRY_USERNAME: ${{ steps.load-registry-creds.outputs.REGISTRY_USERNAME }}
+          REGISTRY_CHARTS_URL: ${{ steps.load-registry-creds.outputs.REGISTRY_CHARTS_URL }}
+          REGISTRY_OWNER: ${{ inputs.registry-owner }}
+          CHART_NAME: ${{ inputs.chart-name }}
+          CHART_VERSION: ${{ steps.get-chart-version.outputs.CHART_VERSION }}
+        run: |-
+          : "${REGISTRY_CHARTS_URL:?empty - check op://GitHub-Actions/jlab-registry-access/charts-url}"
+          : "${REGISTRY_USERNAME:?empty - check op://GitHub-Actions/jlab-registry-access/username}"
+          : "${REGISTRY_PASSWORD:?empty - check op://GitHub-Actions/jlab-registry-access/password}"
+          : "${REGISTRY_OWNER:?empty - the registry-owner input did not arrive; the caller passes it from github.repository_owner, do not hardcode an owner}"
+          : "${CHART_NAME:?empty - the chart-name input did not arrive}"
+          : "${CHART_VERSION:?empty - could not read version: from ${CHART_NAME}/Chart.yaml}"
+          # 1Password masks the full URL, but a curl connection error prints only
+          # "<host>:<port>", which that mask would not cover. Mask the host too.
+          CHARTS_HOST="${REGISTRY_CHARTS_URL#*://}"
+          echo "::add-mask::${CHARTS_HOST%%/*}"
+          # charts-url is the base only; this workflow appends the owner, the
+          # package type and the endpoint. Reject the old, full shape by name so
+          # the failure says what to change in the vault item instead of 404ing
+          # against a URL the log has masked.
+          CHARTS_BASE="${REGISTRY_CHARTS_URL%/}"
+          case "$CHARTS_BASE" in
+            */api/charts)
+              echo "::error::op://GitHub-Actions/jlab-registry-access/charts-url still ends in /api/charts - it must hold only the base up to /api/packages (https://<host>/api/packages); this workflow appends /<owner>/helm/api/charts itself"
+              exit 1
+              ;;
+            */helm|*/helm/*)
+              echo "::error::op://GitHub-Actions/jlab-registry-access/charts-url still contains the /helm path segment - it must hold only the base up to /api/packages (https://<host>/api/packages); this workflow appends /<owner>/helm/api/charts itself"
+              exit 1
+              ;;
+            */api/packages) ;;
+            *)
+              echo "::error::op://GitHub-Actions/jlab-registry-access/charts-url must end in /api/packages (https://<host>/api/packages) - no owner, no package type, no endpoint; this workflow appends /<owner>/helm/api/charts itself"
+              exit 1
+              ;;
+          esac
+          # An empty owner would build "<base>//helm/api/charts", a stray "/" or
+          # "?" would build something else entirely - both are bare 404s.
+          case "$REGISTRY_OWNER" in
+            *[!A-Za-z0-9._-]*)
+              echo "::error::the registry-owner input is not usable as a URL path segment: '${REGISTRY_OWNER}'"
+              exit 1
+              ;;
+          esac
+          CHARTS_API_URL="${CHARTS_BASE}/${REGISTRY_OWNER}/helm/api/charts"
+          case "${REGISTRY_USERNAME}${REGISTRY_PASSWORD}" in
+            *[[:space:]]*)
+              echo "::error::username/password in op://GitHub-Actions/jlab-registry-access must not contain whitespace - curl --config truncates an unquoted value at the first space"
+              exit 1
+              ;;
+          esac
+          CHART_PACKAGE="${CHART_NAME}-${CHART_VERSION}.tgz"
+          test -f "$CHART_PACKAGE" || {
+            echo "::error::${CHART_PACKAGE} does not exist - helm package produced: $(ls -1 ./*.tgz 2>&1)"
+            exit 1
+          }
+          echo "uploading ${CHART_PACKAGE}"
+          printf 'user = %s:%s\nurl = %s\n' \
+            "$REGISTRY_USERNAME" "$REGISTRY_PASSWORD" "$CHARTS_API_URL" |
+            curl --config - \
+                 --fail-with-body \
+                 --silent --show-error \
+                 --request POST \
+                 --upload-file "$CHART_PACKAGE" \
+                 --write-out '\nHTTP %{http_code}\n'
+        working-directory: ${{ inputs.chart-location }}

README.md

@@ -4,6 +4,12 @@ Geteilte CI/CD-Bausteine für die Gitea-Instanz `git.jk-dev.de`. Die Workflows
 hier werden nicht selbst ausgelöst, sondern von anderen Repositories über
 `uses:` aufgerufen (`on: workflow_call`).
 
+Diese Datei ist die **Kurzreferenz für Aufrufer**: was ein Baustein tut, seine
+Eingaben, ein Aufrufbeispiel, die Voraussetzungen. Wer einen Aufruf schreibt,
+braucht nur das. Die Langform — warum die Dinge so sind und was dafür gemessen
+wurde — steht im [Wiki](https://git.jk-dev.de/workflow-util/pipelines/wiki),
+eine Seite je Baustein und eine für die Eigenheiten dieser Forge.
+
 ## Bausteine
 
 ### `.gitea/workflows/docker-build-push.yml`
@@ -25,7 +31,7 @@ Gepusht wird unter fünf Tags:
 Der Checkout holt Submodule mit; die Zugangsdaten dafür und für die Registry
 kommen zur Laufzeit aus 1Password Connect.
 
-Mit `push: false` entfällt der Push — der Baustein baut dann nur. Damit nutzt
+Mit `push: 'false'` entfällt der Push — der Baustein baut dann nur. Damit nutzt
 die CI eines Projekts dieselbe Bau-Logik wie das Deployment, statt sie zu
 duplizieren. Siehe [Prüfmodus](#prüfmodus-ohne-push).
 
@@ -37,7 +43,7 @@ duplizieren. Siehe [Prüfmodus](#prüfmodus-ohne-push).
 | `dockerfile`           | ja      | —                         | Pfad zum Dockerfile |
 | `docker-context`       | ja      | —                         | Build-Kontext |
 | `image-owner`          | ja      | —                         | Eigentümer-Segment des Images, also der mittlere Teil von `<registry>/<owner>/<name>` |
-| `push`                 | nein    | `true`                    | Ob das Image gepusht wird. Bei `false` werden keine Zugangsdaten aus 1Password geholt und es findet kein Registry-Login statt — siehe [Prüfmodus](#prüfmodus-ohne-push) |
+| `push`                 | nein    | `'true'`                  | Zeichenkette `'true'` oder `'false'`. Ob das Image gepusht wird. Bei `'false'` werden keine Zugangsdaten aus 1Password geholt und es findet kein Registry-Login statt — siehe [Prüfmodus](#prüfmodus-ohne-push) |
 | `registry`             | nein    | `git.jk-dev.de`           | Registry, für die getaggt und — beim Push — bei der angemeldet wird |
 | `version-number`       | nein    | `0.0.0`                   | Vollständige Version, wird als Tag gesetzt |
 | `version-number-major` | nein    | `0`                       | Major-Anteil für die mitwandernden Tags |
@@ -52,6 +58,23 @@ ist je Projekt verschieden und soll nie stillschweigend geraten werden — genau
 das war der Fehler des früher fest verdrahteten `suer`, unter dem die Images
 aller Projekte landeten. Die Registry ist dagegen praktisch immer dieselbe.
 
+`push` ist eine Zeichenkette und kein Boolean — und das ist Absicht. Auf dieser
+Gitea-Version (gemessen an 1.27.0) werden **boolesche `workflow_call`-Eingaben
+nicht an den aufgerufenen Workflow durchgereicht**: Weder ihre Vorgabe noch ein
+ausdrücklich übergebenes `push: true` kamen an, `inputs.push` blieb leer, und
+der Baustein baute immer im Prüfmodus — bei grünem Lauf. Alle Eingaben vom Typ
+`string` kamen im selben Lauf korrekt an. Details in
+[Issue #4](https://git.jk-dev.de/workflow-util/pipelines/issues/4).
+
+Deshalb bitte immer in Anführungszeichen schreiben: `push: 'true'` bzw.
+`push: 'false'`. Ein unquotiertes `push: false` ist im YAML ein Boolean und
+wird verschluckt.
+
+> **Brechende Änderung gegenüber `v1`.** Aufrufer, die `push` als YAML-Boolean
+> übergeben, müssen auf `@v2` wechseln und dabei auf die Schreibweise mit
+> Anführungszeichen umstellen. Wer `@v1` weiterverwendet, behält das alte
+> Verhalten samt Fehler.
+
 Die vier Versionsangaben dienen ausschließlich der Tag-Liste. Sie sind keine
 Pflicht mehr, damit ein Prüflauf keine Platzhalter erfinden muss; wer pusht,
 übergibt sie wie bisher. Ihre Vorgabe ist bewusst `0.0.0` und nicht leer — die
@@ -63,7 +86,7 @@ Tag-Liste wird auch ohne Push gebildet, und ein leerer Wert ergäbe das ungülti
 ```yaml
 jobs:
   image:
-    uses: workflow-util/pipelines/.gitea/workflows/docker-build-push.yml@v1
+    uses: workflow-util/pipelines/.gitea/workflows/docker-build-push.yml@v2
     with:
       version-number: 2026.09.1
       version-number-major: '2026'
@@ -73,6 +96,7 @@ jobs:
       dockerfile: ./Dockerfile
       docker-context: .
       image-owner: bekemeyer-klein
+      push: 'true'
     secrets: inherit
 ```
 
@@ -81,7 +105,7 @@ dem aufrufenden Repository.
 
 #### Prüfmodus ohne Push
 
-Mit `push: false` baut der Baustein nur und veröffentlicht nichts. Es werden
+Mit `push: 'false'` baut der Baustein nur und veröffentlicht nichts. Es werden
 dann keine Zugangsdaten aus 1Password geholt und es findet kein Registry-Login
 statt. Die CI eines Projekts nutzt damit dieselbe Bau-Logik wie das Deployment,
 statt sie zu duplizieren.
@@ -91,15 +115,21 @@ Weder Secrets noch Versionsangaben sind dafür nötig:
 ```yaml
 jobs:
   build-check:
-    uses: workflow-util/pipelines/.gitea/workflows/docker-build-push.yml@v1
+    uses: workflow-util/pipelines/.gitea/workflows/docker-build-push.yml@v2
     with:
       container-name: bk-dev-website
       dockerfile: ./Dockerfile
       docker-context: .
       image-owner: bekemeyer-klein
-      push: false
+      push: 'false'
 ```
 
+Die Anführungszeichen sind nicht kosmetisch: `push: false` ohne sie ist ein
+YAML-Boolean und kommt im Baustein nicht an (siehe oben). Es griffe dann die
+Vorgabe `'true'`, der Lauf versuchte also trotz `push: false` zu
+veröffentlichen — sofern Gitea die Typabweichung nicht ohnehin als Fehler
+zurückweist.
+
 > **Private Submodule funktionieren in diesem Modus nicht.**
 > Der Checkout-Token stammt aus demselben 1Password-Schritt, der ohne Push
 > übersprungen wird. Der Checkout fällt deshalb auf den Standard-Token des Jobs
@@ -124,12 +154,127 @@ Die eigentlichen Zugänge für Checkout und Registry liegen in 1Password
 (`GitHub-Actions/jlab-git-checkout-token`, `GitHub-Actions/jlab-registry-access`)
 und müssen in Gitea nicht hinterlegt werden.
 
+### `.gitea/workflows/publish-helm-chart.yml`
+
+Packt ein Helm-Chart und lädt es in eine **klassische, indexbasierte**
+Helm-Registry. Das ist kein OCI-`helm push`: Es gibt keine Registry-Sitzung,
+sondern ein einzelnes HTTP-`POST` des gepackten `.tgz`, je Anfrage
+authentifiziert. Läuft auf `ubuntu-latest`.
+
+Die Ziel-URL wird zusammengesetzt, nicht gespeichert:
+
+```
+<charts-url>/<registry-owner>/helm/api/charts
+```
+
+`<charts-url>` ist die Basis bis `/api/packages` und liegt in 1Password
+(`GitHub-Actions/jlab-registry-access`, Feld `charts-url`), `<registry-owner>`
+ist die Pflichteingabe. Damit steht im aufrufenden Repository kein Wert, der auf
+die Registry zeigt — nicht einmal ein Pfadsegment —, und ein zweiter Eigentümer
+auf derselben Instanz braucht keine zweite Einstellung.
+
+#### Eingaben
+
+| Eingabe          | Pflicht | Vorgabe | Bedeutung |
+| ---------------- | ------- | ------- | --------- |
+| `chart-name`     | ja      | —       | Name des Charts, zugleich der Name seines Verzeichnisses unterhalb von `chart-location` |
+| `registry-owner` | ja      | —       | Eigentümer-Segment der Ziel-URL, also der `<owner>` in `<basis>/<owner>/helm/api/charts` |
+| `chart-location` | nein    | `.`     | Verzeichnis, in dem das Chart-Verzeichnis liegt |
+
+Dass `registry-owner` Pflicht ist und keine Vorgabe hat, folgt derselben
+Hausregel wie `image-owner` oben: Ein Eigentümer-Segment wird nie geraten.
+Aufrufer übergeben `${{ github.repository_owner }}`; der Wert wird damit im
+**aufrufenden** Repository ausgewertet, wo er gemessen ist (`jlab-cluster`, Lauf
+282 von `validate-charts.yml`). Dass der Kontext auch in einem von fremd
+aufgerufenen Workflow der des Aufrufers bleibt, ist dokumentiert, auf dieser
+Gitea-Fassung aber nicht gemessen — und ein Chart, das unter dem falschen
+Eigentümer veröffentlicht wird, ist nichts, wofür man sich auf eine
+Kontext-Semantik verlassen müsste. Als Eingabe hängt der Baustein an keiner.
+
+Alle Eingaben sind `type: string`, auch dort, wo künftig ein Schalter
+hinzukommt: Boolesche `workflow_call`-Eingaben werden auf dieser Gitea-Version
+nicht durchgereicht — 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.
+
+#### Ausgaben
+
+| Ausgabe         | Bedeutung |
+| --------------- | --------- |
+| `chart-version` | Die veröffentlichte Chart-Version, gelesen aus `version:` in `Chart.yaml` |
+
+#### Aufrufbeispiel
+
+```yaml
+jobs:
+  publish-outline:
+    name: Publish Outline Helm Chart
+    uses: workflow-util/pipelines/.gitea/workflows/publish-helm-chart.yml@v3
+    with:
+      chart-name: 'outline'
+      registry-owner: ${{ github.repository_owner }}
+    secrets: inherit
+```
+
+`secrets: inherit` ist notwendig — der Workflow braucht `OP_CONNECT_TOKEN` aus
+dem aufrufenden Repository.
+
+Der Baustein löst sich nicht selbst aus. Wann veröffentlicht wird, entscheidet
+die Hülle im aufrufenden Repository über ihr eigenes `on:` — üblicherweise ein
+`push` auf `main`, eingeschränkt auf das Chart-Verzeichnis, dazu ein
+`workflow_dispatch` für den Fall, dass von Hand nachgeschoben werden muss.
+
+#### Form des Tresor-Felds `charts-url`
+
+Das Feld enthält **nur** die Basis:
+
+```
+https://<host>/api/packages                             # so
+https://<host>/api/packages/<owner>/helm/api/charts      # nicht so
+```
+
+Drei Wächter weisen eine andere Form namentlich zurück: wenn der Wert auf
+`/api/charts` endet, wenn er das Segment `/helm` enthält, und wenn er nicht auf
+`/api/packages` endet. Der Grund ist die Lesbarkeit des Fehlers — 1Password
+maskiert die URL im Protokoll, ein 404 gegen eine maskierte Adresse wäre nicht zu
+deuten. Der Eigentümer wird aus demselben Grund geprüft: Ein leerer Wert ergäbe
+`<basis>//helm/api/charts`, also wieder einen nackten 404.
+
+#### Voraussetzungen im aufrufenden Repository
+
+| Name                      | Art               | Zweck |
+| ------------------------- | ----------------- | ----- |
+| `OP_CONNECT_HOST`         | Variable          | Adresse des 1Password-Connect-Servers im Cluster, etwa `https://op-connect.example.com` |
+| `OP_CONNECT_TOKEN`        | Secret            | Zugang zu diesem Connect-Server, kommt über `secrets: inherit` |
+| `ci/helm-dependencies.sh` | Datei im Repository | Ausführbares Skript, das die deklarierten Abhängigkeiten eines Charts nach `charts/` holt |
+
+`OP_CONNECT_HOST` ist bewusst eine Variable des aufrufenden Repositories und
+kein fest verdrahteter Wert: Ein geteilter Baustein trägt nicht die
+Infrastruktur-Adresse eines einzelnen Mandanten. Der Preis dafür ist eine
+Voraussetzung, die man vergessen kann, und eine nicht gesetzte Variable kommt als
+leere Zeichenkette an. Deshalb prüft der erste Schritt sie und benennt beim
+Abbruch die Einstellung samt Ort — statt zwei Schritte später an einer leeren
+Adresse zu scheitern.
+
+`ci/helm-dependencies.sh` ist ein Skript des **aufrufenden** Repositories, und
+das bleibt nach dem Umzug hierher so: Der Checkout holt das Repository, zu dem
+der Lauf gehört — das des Aufrufers —, also ist `${{ github.workspace }}` dessen
+Arbeitsverzeichnis. Der Aufruf steht vor `helm package`, weil `helm package` mit
+`found in Chart.yaml, but missing in charts/ directory` abbricht, solange eine
+deklarierte Abhängigkeit nicht geholt ist. Für ein Chart ohne `dependencies:`
+tut das Skript nichts, vorhanden und ausführbar muss es trotzdem sein; fehlt es,
+sagt der Lauf genau das.
+
+Der Registry-Zugang selbst liegt in 1Password
+(`GitHub-Actions/jlab-registry-access`: `username`, `password`, `charts-url`) und
+muss in Gitea nicht hinterlegt werden.
+
 ## Auf einen Tag zeigen, nicht auf `@main`
 
 Aufrufe bitte immer an einen Tag binden:
 
 ```yaml
-uses: workflow-util/pipelines/.gitea/workflows/docker-build-push.yml@v1   # so
+uses: workflow-util/pipelines/.gitea/workflows/docker-build-push.yml@v2   # so
 uses: workflow-util/pipelines/.gitea/workflows/docker-build-push.yml@main # nicht so
 ```
 
@@ -140,3 +285,24 @@ im jeweiligen Projekt.
 
 Änderungen hier bekommen deshalb einen neuen Tag. Bricht eine Änderung
 bestehende Aufrufe, wird der Major-Anteil erhöht.
+
+`v2` ist genau so ein Fall: Die Umstellung von `push` auf `type: string` bricht
+Aufrufe, die den Wert als YAML-Boolean übergeben. `v1` bleibt unverändert
+stehen; wer umstellt, wechselt auf `@v2` und schreibt `push: 'true'` bzw.
+`push: 'false'`.
+
+### 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.
+
+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
+`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.