Feture/gitops7 (#44)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com>
Reviewed-on: #44

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

@@ -8,6 +8,12 @@ on:
       version:
         required: true
         type: string
+      chart_path:
+        required: true
+        type: string
+      extra_dependency_paths:
+        required: false
+        type: string
     secrets:
       GITEA_TOKEN:
         required: true
@@ -47,6 +53,13 @@ jobs:
           repository: niko/gitea-ci-library
           path: .ci
 
+      - name: Resolve extra subchart dependencies
+        if: inputs.extra_dependency_paths != ''
+        run: |
+          for path in $(echo "${{ inputs.extra_dependency_paths }}" | tr ',' '\n'); do
+            helm dependency update "${path}"
+          done
+
       - name: Package Helm chart
         run: |
           CHART_DIR=$(dirname "${CHART_FILE}")

docs/workflows.md

@@ -103,7 +103,8 @@ joten `actions/checkout` toimii ilman node-asennuksia.
 |-----------|------------|--------|
 | `env_json` | Kyllä | Konffi `gitea-env.conf`:stä |
 | `version` | Kyllä | Version string (check-version output) |
-| `chart_path` | Ei | Polku Chart.yaml-hakemistoon, oletus `.` |
+| `chart_path` | Kyllä | Polku Chart.yaml-hakemistoon |
+| `extra_dependency_paths` | Ei | Pilkulla erotellut polut subcharttien dependeinceille, joille ajetaan `helm dependency update` ennen päächartin buildia |
 
 **`env_json`-avaimet:**
 
@@ -124,9 +125,10 @@ build-push (helm package → helm push OCI) → tag-commit (git-tagin luonti)
 **Steppien kuvaus `build-push`-jobissa:**
 1. **Node.js-asennus** — `apk add --no-cache nodejs` (vaaditaan `actions/checkout`-actionia varten)
 2. **Checkout** — sovellusrepo ja gitea-ci-library `.ci/`-polkuun
-3. **Package** — `helm package` versiolla `$VERSION`
-4. **Push OCI** — `helm push` registryyn autentikoinnilla
-5. **Report status** — commit-status + UI-linkki
+3. **Resolve extra subchart dependencies** — `helm dependency update` jokaiselle `extra_dependency_paths`-polulle (vain jos input on annettu)
+4. **Package** — `helm dependency update` + `helm package` versiolla `$VERSION`
+5. **Push OCI** — `helm push` registryyn autentikoinnilla
+6. **Report status** — commit-status + UI-linkki
 
 **Kompromissi:** Kontti `alpine/helm` ei sisällä node.js:ää, mutta
 `actions/checkout@v4` on JavaScript-action ja vaatii sen. Siksi nodejs

skills/consumer-pipelines/SKILL.md

@@ -368,9 +368,18 @@ Pakkaa ja pushee Helm-chartin OCI-registryyn. Käyttää `alpine/helm`-konttia.
 
 ```yaml
 HELM_REGISTRY: gitea.app.keskikuja.site/niko
-VERSION_FILE: platform-helm/Chart.yaml  # chart-hakemisto + versionlähde
+VERSION_FILE: platform-helm/Chart.yaml  # versionlähde, chart_path määrää chart-hakemiston
 ```
 
+**Inputit:**
+
+| Parametri | Pakollinen | Kuvaus |
+|-----------|------------|--------|
+| `env_json` | Kyllä | Konffi `gitea-env.conf`:stä |
+| `version` | Kyllä | Version string (check-version output) |
+| `chart_path` | Kyllä | Polku Chart.yaml-hakemistoon (esim. `platform-helm`) |
+| `extra_dependency_paths` | Ei | Pilkulla erotellut polut subcharttien dependeinceille |
+
 **Käyttö reitittimessä:**
 
 ```yaml
@@ -382,11 +391,19 @@ helm-build-push:
   with:
     env_json: ${{ needs.load-config.outputs.env_json }}
     version:  ${{ needs.check-version.outputs.version }}
+    chart_path: platform-helm
+    # extra_dependency_paths: subchart-a,subchart-b  # tarvittaessa
 ```
 
-Chart-hakemisto johdetaan `VERSION_FILE`-polusta: `dirname "${VERSION_FILE}"`.
-Jos `VERSION_FILE` on `Chart.yaml`, konteksti on juuri. Jos `platform-helm/Chart.yaml`,
-konteksti on `platform-helm/`.
+`chart_path` on eksplisiittinen polku chart-hakemistoon (esim. `platform-helm`).
+`VERSION_FILE` määrää version lähteen (`Chart.yaml:n` `version`-kenttä) —
+nämä voivat olla eri polkuja, mutta tyypillisesti molemmat osoittavat samaan
+chart-hakemistoon.
+
+**`extra_dependency_paths`:** Jos chartilla on alikarttoja (subchartteja) jotka
+vaativat `helm dependency update` -ajon ennen päächartin buildia, anna niiden
+polut pilkulla eroteltuna. Provider ajaa `helm dependency update` jokaiselle
+polulle ennen päächartin buildia.
 
 **Yksittäisten Helm-UI-linkkien raportointi:** `HELM_UI_URL` on
 tarkoitettu yleiselle registry UI:lle — provider muodostaa linkin

skills/gitops-update/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: gitops-update
 description: |
-  Setting up GitOps version updates: GitOps-repo workflow template, code
-  repo dispatch, secret requirements, and two-repo commit-status pattern.
-  Activates when the user needs to wire up artifact builds to GitOps
-  configuration updates.
+  Getting GitOps configuration updates working for a consumer project —
+  GitOps repo setup, consumer pipeline wiring, secrets, and commit-status
+  output.
 activation-gate: |
   User mentions GitOps update, gitops-update, dispatch to another repo,
   two-repo version bump, cross-repo deployment, or wiring build output to
@@ -13,47 +12,26 @@ category: ci
 impact: high
 ---
 
-# GitOps Update — Provider-palvelu
+# GitOps Update — consumer setup
 
-`scripts/gitops-update.sh` ja `scripts/dispatch-workflow.sh` muodostavat
-GitOps-päivityspalvelun. Artifact buildataan code repossa, minkä jälkeen
-code repo dispatchaa GitOps-repoon, joka päivittää konfiguraatiotiedoston
-ja pushaa muutoksen.
+## What you need
 
-## Arkkitehtuuri
+- **GitOps repo** — holds the configuration files (e.g. `Chart.yaml`, `values.yaml`)
+- **Consumer repo** — builds artifacts and triggers the update
+- **Bottitoken** — Gitea token with write access to the GitOps repo only
 
-Kaksi erillistä repoa, eristetyt oikeudet:
+Two repos, isolated access. The consumer never writes to GitOps directly;
+it dispatches a workflow that clones, updates, commits, and pushes.
 
-```
-Code repo                          GitOps repo
-(build & push artifact)            (konfiguraatiot)
+---
 
-build & push onnistuu (v0.2.3)
-         │
-         │ dispatch ci-main.yml
-         │ {file, yq_tpl, version, source_repo, source_commit}
-         │
-         └────────────────────────────────────→┐
-                                               │
-         dispatch-workflow.sh pollaa ←─────────┘
-                                               │
-         code repo asettaa                     │ git clone, yq update,
-         oman commit-statusnsa                 │ git commit + push
-         dispatchin exit-koodilla              │ status GitOps-repoon
-```
+## 1. GitOps-repo setup
 
-**Token-periaate:** Vain GitOps-repoon kirjoitetaan. Code repo asettaa
-oman commit-statusnsa dispatch-kutsun exit-koodin perusteella omalla
-auto-tokenillaan. GitOps-repon auto-token ei tarvitse oikeuksia code
-repoon.
-
-## GitOps-repon workflow (ci-main.yml)
-
-GitOps-repoon luodaan `.gitea/workflows/ci-main.yml`:
+Create `.gitea/workflows/gitops-service.yaml`:
 
 ```yaml
 name: GitOps Update
-run-name: "GitOps Service (${{ inputs.dispatch_id || 'manual' }})"
+run-name: "GitOps (${{ inputs.dispatch_id || 'manual' }})"
 on:
   workflow_dispatch:
     inputs:
@@ -86,7 +64,6 @@ env:
   SOURCE_REPO: ${{ inputs.source_repo }}
   SOURCE_COMMIT: ${{ inputs.source_commit }}
   GITOPS_REPO: ${{ github.repository }}
-  GITOPS_BRANCH: ${{ github.ref_name }}
   GITEA_API_URL: ${{ gitea.server_url }}
   GIT_TAG_PREFIX: ${{ inputs.git_tag_prefix || '' }}
 
@@ -95,18 +72,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
       - uses: actions/checkout@v4
         with:
           repository: niko/gitea-ci-library
           path: .ci
-
       - name: Install yq
         run: |
           wget -qO /usr/local/bin/yq \
             https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
           chmod +x /usr/local/bin/yq
-
       - name: Run GitOps update
         env:
           GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
@@ -114,297 +88,130 @@ jobs:
           bash .ci/scripts/gitops-update.sh
 ```
 
-**Huomiot:**
-- `GITEA_TOKEN` on Gitean auto-token — scopeutuu GitOps-repoon, riittää
-  cloneen, committiin, pushiin ja commit-statusiin GitOps-repossa
-- `run-name` ja `dispatch_id` mahdollistavat dispatchaavan skriptin tunnistaa
-  tämän workflow-runin yksiselitteisesti `display_title`-kentästä, vaikka
-  samassa repossa olisi samanaikaisia ajoja
-- yq ladataan lennossa (kompromissi, ks. "Tuleva CI-kontti")
+> **⚠️ yq ladataan lennossa.** Tämä on väliaikainen kompromissi. Myöhemmin
+> julkaistaan Docker Hubiin custom CI-kontti, jossa nodejs + git + yq
+> valmiina. Sama patterni kuin `ci-bats` ja `ci-cucumber`.
+> Ks. `skills/ci-container-build/SKILL.md`. 
 
-### Tulossa: custom CI-kontti
+Key points:
+- `run-name` must include `dispatch_id` — the consumer's poll step uses it to find the run
+- `secrets.GITEA_TOKEN` is the **auto-token** — write access to the GitOps repo only, no consumer access needed
+- Commit message becomes `"[skip ci] gitops: update version to X.Y.Z"` — used by consumer to find the commit SHA
 
-Nykyinen job lataa yq:n lennossa. Myöhemmin rakennetaan oma kontti
-(`ci-gitops`), jossa on nodejs + git + yq valmiina. Sama patterni kuin
-`ci-bats` ja `ci-cucumber`. Ks. `skills/ci-container-build/SKILL.md`.
+---
 
-## Code-repon dispatch-step
+## 2. Consumer-repo setup
 
-Code repo dispatchaa GitOps-repon workflown artifact buildin onnistuttua:
+### 2.1 Token
+
+Create a Gitea token with write access to the GitOps repo:
+
+1. Gitea → `Settings` → `Applications` → `Generate Token`
+2. Select the GitOps repo, grant write access
+3. Save as an Actions secret in the consumer repo: **`GITOPS_DISPATCH_TOKEN`**
+
+### 2.2 Pipeline call
+
+Add a job after your build step that calls the dispatch workflow:
 
 ```yaml
 gitops-update:
-  needs: [helm-build-push]
+  needs: [build-push]
   if: success()
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-
-    - uses: actions/checkout@v4
-      with:
-        repository: niko/gitea-ci-library
-        path: .ci
-
-    - name: Dispatch GitOps update
-      id: dispatch
-      env:
-        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-      run: |
-        INPUTS=$(jq -nc \
-          --arg file "dev/Chart.yaml" \
-          --arg yq_tpl '(.dependencies[] | select(.name == "agent-platform-helm") | .version) = "{{VERSION}}"' \
-          --arg version "${{ needs.check-version.outputs.version }}" \
-          --arg source_repo "${{ github.repository }}" \
-          --arg source_commit "${{ github.sha }}" \
-          '{file: $file, yq_tpl: $yq_tpl, version: $version, source_repo: $source_repo, source_commit: $source_commit}')
-        OUTPUT=$(bash .ci/scripts/dispatch-workflow.sh \
-          "niko/agent-platform-gitops" \
-          "ci-main.yml" \
-          "main" \
-          "$INPUTS" \
-          "${{ fromJson(needs.load-config.outputs.env_json).GITEA_API_URL }}" \
-          "${{ secrets.GITEA_TOKEN }}" \
-          "30")
-        echo "$OUTPUT"
-        GITOPS_COMMIT=$(echo "$OUTPUT" | grep '^GITOPS_COMMIT=' | cut -d= -f2)
-        echo "gitops_commit=$GITOPS_COMMIT" >> "$GITHUB_OUTPUT"
+  uses: niko/gitea-ci-library/.gitea/workflows/gitops-dispatch.yml@v1
+  secrets: inherit
+  with:
+    env_json: ${{ needs.load-config.outputs.env_json }}
+    version: ${{ needs.version.outputs.version }}
+    GITOPS_FILE: dev/Chart.yaml
+    GITOPS_YQ_TPL: '.version = "{{VERSION}}"'
+    GITOPS_REPO: niko/your-gitops-repo
 ```
 
-### Multi-artifact pipeline (kontti + helm)
+This single job handles: dispatch → poll → find commit SHA → set commit-status on your commit → produce `GITOPS_SUMMARY` output.
 
-Yksi main-haaran build tuottaa usein sekä Docker-imagen että Helm-chartin.
-Kumpikin artefakti dispatchaa oman GitOps-päivityksensä rinnakkain:
+### 2.3 Parameters
 
-```yaml
-gitops-helm:
-  needs: [helm-build-push]
-  if: success()
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/checkout@v4
-      with:
-        repository: niko/gitea-ci-library
-        path: .ci
-    - name: Update helm version
-      id: helm
-      run: |
-        INPUTS=$(jq -nc \
-          --arg file "dev/Chart.yaml" \
-          --arg yq_tpl '(.dependencies[] | select(.name == "git-pages") | .version) = "{{VERSION}}"' \
-          --arg version "${{ needs.check-version.outputs.version }}" \
-          --arg source_repo "${{ github.repository }}" \
-          --arg source_commit "${{ github.sha }}" \
-          --arg git_tag_prefix "helm" \
-          '{dispatch_id: "", file: $file, yq_tpl: $yq_tpl, version: $version, source_repo: $source_repo, source_commit: $source_commit, git_tag_prefix: $git_tag_prefix}')
-        OUTPUT=$(bash .ci/scripts/dispatch-workflow.sh \
-          "niko/gitea-ci-gitops-tests" "gitops-service.yaml" "main" \
-          "$INPUTS" "${{ fromJson(needs.load-config.outputs.env_json).GITEA_API_URL }}" \
-          "${{ secrets.GITOPS_DISPATCH_TOKEN }}" "30")
-        echo "$OUTPUT"
-        echo "helm_commit=$(echo "$OUTPUT" | grep '^GITOPS_COMMIT=' | cut -d= -f2)" >> "$GITHUB_OUTPUT"
-
-gitops-docker:
-  needs: [docker-build-push]
-  if: success()
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/checkout@v4
-      with:
-        repository: niko/gitea-ci-library
-        path: .ci
-    - name: Update docker tag
-      id: docker
-      run: |
-        INPUTS=$(jq -nc \
-          --arg file "dev/values.yaml" \
-          --arg yq_tpl '.service.tag = "{{VERSION}}"' \
-          --arg version "${{ needs.check-version.outputs.version }}" \
-          --arg source_repo "${{ github.repository }}" \
-          --arg source_commit "${{ github.sha }}" \
-          --arg git_tag_prefix "docker" \
-          '{dispatch_id: "", file: $file, yq_tpl: $yq_tpl, version: $version, source_repo: $source_repo, source_commit: $source_commit, git_tag_prefix: $git_tag_prefix}')
-        OUTPUT=$(bash .ci/scripts/dispatch-workflow.sh \
-          "niko/gitea-ci-gitops-tests" "gitops-service.yaml" "main" \
-          "$INPUTS" "${{ fromJson(needs.load-config.outputs.env_json).GITEA_API_URL }}" \
-          "${{ secrets.GITOPS_DISPATCH_TOKEN }}" "30")
-        echo "$OUTPUT"
-        echo "docker_commit=$(echo "$OUTPUT" | grep '^GITOPS_COMMIT=' | cut -d= -f2)" >> "$GITHUB_OUTPUT"
-```
-
-Kaksi dispatchia, kaksi eri tiedostoa, kaksi eri `GIT_TAG_PREFIX`-arvoa.
-Kummallakin on oma commit-status-linja ja oma summary-rivi.
-`dispatch-workflow.sh` hoitaa rinnakkaisuuden `display_title`-matchauksella.
-
-**GITEA_TOKEN dispatch-vaiheessa:** Tarvitaan manuaalinen token,
-jolla on **write-oikeus GitOps-repoon** (esim. org-tason token).
-Code-repon auto-token ei oikeuta dispatchaamaan toiseen repoon.
-Token luodaan Giteassa: `Settings → Applications → Generate Token`
-ja asetetaan code-repoon Actions Secretiksi.
-
-### Commit-status dispatchin perusteella
-
-`dispatch-workflow.sh` tulostaa `GITOPS_COMMIT=<sha>` stdoutiin onnistuneen
-GitOps-päivityksen jälkeen. Code repo parsii sen ja asettaa commit-statusin
-linkillä GitOps-committiin:
-
-```yaml
-    - name: Set commit-status with GitOps link
-      if: always()
-      env:
-        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-        GITEA_API_URL: ${{ fromJson(needs.load-config.outputs.env_json).GITEA_API_URL }}
-        GITOPS_COMMIT: ${{ steps.dispatch.outputs.gitops_commit }}
-        VERSION: ${{ needs.check-version.outputs.version }}
-      run: |
-        GITOPS_URL="${GITEA_API_URL}/niko/agent-platform-gitops/commit/${GITOPS_COMMIT}"
-        CTX="gitops/$(basename ${{ github.repository }})"
-        DESC="Deploy to dev ${VERSION}"
-        if [ -n "$GITOPS_COMMIT" ]; then
-          bash .ci/scripts/report-status.sh success "$DESC" "$CTX" "" "$GITOPS_URL"
-        else
-          bash .ci/scripts/report-status.sh success "$DESC" "$CTX"
-        fi
-```
-
-`dispatch-workflow.sh` palauttaa:
-- exit 0 = GitOps-päivitys onnistui (+ `GITOPS_COMMIT=<sha>`)
-- exit 1 = GitOps-päivitys failasi
-- exit 124 = aikakatkaisu (360 min oletus)
-
-### Loppuraportti (report-summary)
-
-Code-repon viimeinen job (`report-summary`) lisää GitOps-päivityksestä
-rivin GITHUB_STEP_SUMMARYyn:
-
-```yaml
-    - name: GitOps summary
-      if: always()
-      env:
-        GITEA_API_URL: ${{ fromJson(needs.load-config.outputs.env_json).GITEA_API_URL }}
-        GITOPS_COMMIT: ${{ steps.dispatch.outputs.gitops_commit }}
-        VERSION: ${{ needs.check-version.outputs.version }}
-      run: |
-        if [ -n "$GITOPS_COMMIT" ]; then
-          LINK="${GITEA_API_URL}/niko/agent-platform-gitops/commit/${GITOPS_COMMIT}"
-        else
-          LINK="#"
-        fi
-        cat >> "$GITHUB_STEP_SUMMARY" << 'GITOPS'
-
-        ## GitOps updates
-
-        | Component | Version | Status | Commit |
-        |-----------|---------|--------|--------|
-        | agent-platform-helm | __VERSION__ | __STATUS__ | [link](__LINK__) |
-        GITOPS
-        sed -i "s|__VERSION__|${VERSION}|; s|__STATUS__|${{ job.status }}|; s|__LINK__|${LINK}|" \
-          "$GITHUB_STEP_SUMMARY"
-```
-
-## Secretit ja tokenit
-
-| Secret | Missä | Scope | Kuvaus |
-|--------|-------|-------|--------|
-| `GITEA_TOKEN` (auto) | Code repo | Vain code repo | Asettaa commit-statusin dispatchin jälkeen |
-| `GITEA_TOKEN` (auto) | GitOps repo | Vain GitOps repo | Klooni, push, commit-status GitOps-repossa |
-| `GITOPS_DISPATCH_TOKEN` (manuaalinen) | Code repo | Write GitOps-repoon | Dispatchaa GitOps-repon workflow |
-
-**Tokenin luonti:**
-1. Gitea → `Settings` → `Applications` → `Generate Token`
-2. Valitse repo-oikeudet: valitse GitOps-repo, anna write-oikeudet
-3. Token asetetaan code-repoon: `{repo} → Settings → Actions Secrets`
-4. Salaisuuden nimi: esim. `GITOPS_DISPATCH_TOKEN`
-
-## Provider-skriptit
-
-### `scripts/gitops-update.sh`
-
-Ajaan GitOps-repon workflow'ssa. Päivittää konfiguraatiotiedoston yq:llä,
-committaa ja pushaa. Asettaa commit-statuksen vain GitOps-repoon.
-
-**Input-ympäristömuuttujat:**
-
-| Muuttuja | Pakollinen | Kuvaus |
+| Input | Required | Description |
 |---|---|---|
-| `INPUT_FILE` | Kyllä | Tiedosto GitOps-repossa (esim. `dev/Chart.yaml`) |
-| `YQ_TPL` | Kyllä | yq-lauseke `{{VERSION}}`-placeholderilla |
-| `VERSION` | Kyllä | Uusi versio (esim. `0.2.3`) |
-| `SOURCE_REPO` | Kyllä | Code-repo slug (esim. `org/app`) |
-| `SOURCE_COMMIT` | Kyllä | Code-repon commit SHA |
-| `GITOPS_REPO` | Kyllä | GitOps-repo slug |
-| `GITEA_API_URL` | Kyllä | Gitean API-URL |
-| `GITEA_TOKEN` | Kyllä | Gitea API-token (write GitOps-repoon) |
-| `GITOPS_BRANCH` | Ei | Branch (oletus `main`) |
-| `GIT_TAG_PREFIX` | Ei | Komponentin tag-prefix status-nimeämiseen (esim. `agent-platform-helm`) |
-| `GITOPS_CLONE_URL` | Ei | Yliajaa clone-URL (esim. eri protokolla) |
-| `GITOPS_TARGET_DIR` | Ei | Yliajaa clone-kohdehakemisto |
+| `env_json` | Yes | Config JSON with `GITEA_API_URL`, optional `GIT_TAG_PREFIX` (for multi-component repos) |
+| `version` | Yes | Version to write (e.g. `0.2.3`) |
+| `GITOPS_FILE` | Yes | Path in GitOps repo (e.g. `dev/Chart.yaml`) |
+| `GITOPS_YQ_TPL` | Yes | yq expression, `{{VERSION}}` is replaced at runtime |
+| `GITOPS_REPO` | Yes | GitOps repo slug (e.g. `niko/agent-platform-gitops`) |
 
-**Commit-status muoto:**
+### 2.4 Output
 
-GitOps-repoon asetetaan commit-status:
+The workflow produces a `summary` output in pipe format:
 
-| Kenttä | Formaatti | Esimerkki |
-|--------|-----------|-----------|
-| Context | `{repo}/{GIT_TAG_PREFIX} {RUN_ID}` tai `{repo} {RUN_ID}` | `gitea-ci-library/agent-platform-helm 473` |
-| Description | `Install to {env} {version}` | `Install to dev 0.2.0` |
-| Target URL | Linkki code-repon committiin | `/niko/gitea-ci-library/commit/abc123` |
+```
+component|version|status|commit_sha|repo
+agent-platform-helm|0.2.3|success|abc789def|niko/agent-platform-gitops
+```
 
-Jos tiedosto on jo halutussa versiossa (ei muutoksia), status saa descriptionin `Install to {env} {version} — no change`. Commit-pushia ei tehdä, GitOps-repo pysyy muuttumattomana.
+Pass it to `report-summary.yml` for the pipeline summary:
 
-- `{env}` parsitaan `INPUT_FILE`:stä (`dev/Chart.yaml` → `dev`)
-- `{repo}` parsitaan `SOURCE_REPO`:sta (`niko/gitea-ci-library` → `gitea-ci-library`)
-- `{GIT_TAG_PREFIX}` tulee env-varista (sama kuin `gitea-env.conf`:ssa)
+```yaml
+report-summary:
+  needs: [load-config, gitops-update]
+  if: always()
+  uses: niko/gitea-ci-library/.gitea/workflows/report-summary.yml@main
+  with:
+    env_json: ${{ needs.load-config.outputs.env_json }}
+    suites: bats cucumber
+    gitops: ${{ needs.gitops-update.outputs.summary }}
+```
 
-### `scripts/dispatch-workflow.sh`
+---
 
-Dispatchaa workflow_dispatchin kohderepoon ja pollaa valmistumista.
-Generoi automaattisesti `dispatch_id`-tunnisteen, lisää sen dispatch-
-inputteihin ja tunnistaa workflow-runin kohdereposta `display_title`-
-kentän perusteella. Toimii luotettavasti vaikka samassa repossa olisi
-useita samanaikaisia dispatch-attribuutioita.
+## 3. Token summary
 
-**Argumentit:**
+| Token | Where | Scope | Purpose |
+|---|---|---|---|
+| `GITOPS_DISPATCH_TOKEN` (manual) | Consumer secrets | write GitOps repo | Dispatches the GitOps workflow |
+| `GITHUB_TOKEN` (auto) | Consumer workflow | write consumer repo | Sets commit-status on consumer's commit |
+| `GITEA_TOKEN` (auto) | GitOps workflow | write GitOps repo | Clone, push, commit-status in GitOps repo |
 
-| # | Pakollinen | Kuvaus |
-|---|------------|--------|
-| 1 | Kyllä | Kohderepo (esim. `niko/agent-platform-gitops`) |
-| 2 | Kyllä | Workflow-tiedosto (esim. `ci-main.yml`) |
-| 3 | Kyllä | Branch/ref |
-| 4 | Kyllä | Inputs JSON |
-| 5 | Kyllä | Gitea API URL |
-| 6 | Kyllä | Gitea token |
-| 7 | Ei | Aikakatkaisu minuutteina (oletus 360) |
+---
 
-Kutsujan ei tarvitse välittää `dispatch_id`:tä — skripti generoi sen
-itse ja lisää inputteihin ennen dispatchia.
+## 4. What happens at runtime
 
-## [skip ci]
+1. Consumer's `gitops-dispatch.yml` generates a unique `dispatch_id` and POSTs it to the GitOps repo
+2. GitOps workflow clones its own repo, applies `yq`, commits + pushes
+3. Consumer polls the GitOps repo's runs until the workflow completes
+4. Consumer lists recent commits and finds the matching one by commit message `"gitops: update version to X.Y.Z"`
+5. Consumer sets commit-status `gitops/{repo}[/{prefix}]` on its own commit with a link to the exact GitOps commit
+6. If no matching commit is found (no change or error), the job fails
+7. On failure, `GITOPS_SUMMARY` still flows through `report-summary` with `status=failure`
 
-Commit-viestissä on `[skip ci]`, joka estää GitActions-runneria
-triggeröimästä uutta CI-ajoa GitOps-repoon pushista. Näin vältetään
-ääretön trigger-loop.
+---
 
-## Race condition
+## 5. GIT_TAG_PREFIX (optional)
 
-`dispatch-workflow.sh` tunnistaa jokaisen dispatchatun runin uniikilla
-`dispatch_id`-tunnisteella `display_title`-kentästä. Vaikka useampi
-artifakti dispatchaisi samaan aikaan ja useita workflow-runeja olisi
-käynnissä rinnakkain, jokainen skripti löytää oikean runinsa.
+If the same consumer repo dispatches updates for multiple components (e.g. Docker image + Helm chart), set `GIT_TAG_PREFIX` in your `gitea-env.conf`:
 
-## Sääntöjä
+```
+GIT_TAG_PREFIX=docker/
+```
 
-1. **Token ei kirjoita code repoon.** GitOps-repon workflow ei tarvitse
-   oikeuksia code repoon. Kaikki status-kutsut kohdistuvat vain
-   GitOps-repoon. Code repo asettaa oman statusnsa itse.
-2. **Ei provider-workflowta.** GitOps-päivitys ei ole reusable workflow.
-   GitOps-repo ajaa `scripts/gitops-update.sh`:n suoraan.
-3. **Vain `workflow_dispatch`.** GitOps-repon workflow:ta ei triggeröidä
-   pushista — se laukeaa vain dispatch-kutsusta.
-4. **Dispatch ei palauta tarkkaa SHA:**ta. Code repo ei tiedä GitOps-
-   commitin SHA:ta ennen dispatch-valmistumista. Status asetetaan
-   dispatchin exit-koodin perusteella, ei GitOps-commitin tiedoilla.
-5. **`dispatch_id` on pakollinen kohde-workflow'ssa** — ilman sitä
-   `dispatch-workflow.sh` ei löydä oikeaa runia moniajo-tilanteessa.
-6. **`[skip ci]` commit-viestissä.** Pakollinen trigger-loopin estoon.
+Each component gets its own commit-status context:
+
+| Prefix | Context |
+|---|---|
+| (empty) | `gitops/agent-platform` |
+| `docker/` | `gitops/agent-platform/docker` |
+| `helm/` | `gitops/agent-platform/helm` |
+
+This prevents status overwrites between parallel dispatch jobs.
+
+---
+
+## 6. What you do NOT need to know
+
+- How `gitops-update.sh` works internally
+- How the polling finds the run
+- How the commit SHA is extracted
+- Race condition handling
+- CI container plans
+
+All of that is handled by `gitops-dispatch.yml`. You just call it.