Featuer/gitops extra command (#47 )

Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #47
Fix/git pages rentetin create tests (#46 )
2026-06-27 05:20:09 +03:00 · 2026-06-26 08:07:02 +03:00 · 2026-06-25 09:19:01 +03:00 · 2026-06-23 12:45:42 +03:00 · 2026-06-22 14:24:25 +03:00 · 2026-06-22 13:57:14 +03:00
35 changed files with 2617 additions and 230 deletions
@@ -23,7 +23,7 @@ on:

 jobs:
  build-push:
-    runs-on: ubuntu-latest
+    runs-on: docker
    steps:
      - uses: actions/checkout@v4

@@ -32,7 +32,7 @@ concurrency:

 jobs:
  build-push:
-    runs-on: ubuntu-latest
+    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - uses: actions/checkout@v4
@@ -83,14 +83,15 @@ jobs:
          if [ -n "${DOCKER_UI_URL:-}" ] && [ -n "${VERSION:-}" ]; then
            CONTAINER_URL="${DOCKER_UI_URL}/${DOCKER_IMAGE_NAME}/${VERSION}"
          fi
-          bash .ci/scripts/report-status.sh success "Docker build & push ${VERSION} OK" ci-docker-build-push "" "$CONTAINER_URL"
-
-      - name: Report status FAILURE
-        if: failure()
-        run: bash .ci/scripts/report-status.sh failure "Docker build & push ${VERSION} FAILED" ci-docker-build-push
+          DIR=$(dirname "${DOCKERFILE}")
+          if [ "$DIR" != "." ]; then
+            bash .ci/scripts/report-status.sh success "${DIR}: Docker push ${VERSION}" "${DIR}-ci-docker-build-push" "" "$CONTAINER_URL"
+          else
+            bash .ci/scripts/report-status.sh success "Docker push ${VERSION}" ci-docker-build-push "" "$CONTAINER_URL"
+          fi

  tag-commit:
-    runs-on: ubuntu-latest
+    runs-on: docker
    needs: [build-push]
    steps:
      - uses: actions/checkout@v4
@@ -4,3 +4,4 @@ DOCKER_REGISTRY=gitea.app.keskikuja.site/niko
 DOCKER_IMAGE_NAME=gitea-ci-library-test-image
 DOCKER_UI_URL=https://gitea.app.keskikuja.site/niko/-/packages/container
 #DOCKERFILE=Dockerfile.platform
+
@@ -7,14 +7,14 @@ on:

 jobs:
  load-config:
-    name: Load example-gitea-env.conf to pipeline env
+    name: Config load
    uses: niko/gitea-ci-library/.gitea/workflows/config-provider.yml@main
    secrets: inherit
    with:
      config_path: .gitea/workflows/example-gitea-env.conf

  check-version:
-    name: Check existing artifact
+    name: Latest versio
    needs: [load-config]
    uses: niko/gitea-ci-library/.gitea/workflows/check-version.yml@main
    secrets: inherit
@@ -39,7 +39,7 @@ jobs:
    with:
      env_json: ${{ needs.load-config.outputs.env_json }}

-  build-push:
+  docker-build-push:
    name: Build & Push Docker
    needs: [load-config, check-version, bats, cucumber]
    if: needs.check-version.outputs.artifact_exists != 'true'
@@ -49,18 +49,32 @@ jobs:
      env_json: ${{ needs.load-config.outputs.env_json }}
      version: ${{ needs.check-version.outputs.version }}

+  docker-gitops:
+    name: GitOps
+    needs: [docker-build-push, load-config, check-version]
+    uses: niko/gitea-ci-library/.gitea/workflows/gitops-dispatch.yml@main
+    secrets: inherit
+    with:
+      env_json: ${{ needs.load-config.outputs.env_json }}
+      version: ${{ needs.check-version.outputs.version }}
+      GITOPS_FILE: dev/values.yaml
+      GITOPS_YQ_TPL: '.service.tag = "{{VERSION}}"'
+      GITOPS_REPO: niko/gitea-ci-gitops-tests
+
  report-summary:
    name: Report Summary
-    needs: [load-config, build-push]
+    needs: [load-config, check-version, docker-build-push, docker-gitops]
    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.docker-gitops.outputs.summary }}

  tag-maintenance:
    name: Move provider version tag
-    needs: [build-push]
+    needs: [docker-gitops]
    if: success()
    uses: niko/gitea-ci-library/.gitea/workflows/tag-maintenance.yml@main
    secrets: inherit
@@ -5,20 +5,19 @@ on:
      - main
    paths:
      - git-pages/**
-      - .gitea/workflows/helm-build-push.yml
      - .gitea/workflows/git-pages.*
  workflow_dispatch:

 jobs:
  load-config:
-    name: Load git-pages.gitea-env.conf to pipeline env
+    name: Config load
    uses: niko/gitea-ci-library/.gitea/workflows/config-provider.yml@main
    secrets: inherit
    with:
      config_path: .gitea/workflows/git-pages.gitea-env.conf

  check-version:
-    name: Check existing artifact
+    name: Latest version
    needs: [load-config]
    uses: niko/gitea-ci-library/.gitea/workflows/check-version.yml@main
    secrets: inherit
@@ -36,11 +35,25 @@ jobs:
      version: ${{ needs.check-version.outputs.version }}
      chart_path: git-pages

+  chart-gitops:
+    name: GitOps
+    needs: [helm-push, load-config, check-version]
+    uses: niko/gitea-ci-library/.gitea/workflows/gitops-dispatch.yml@main
+    secrets: inherit
+    with:
+      env_json: ${{ needs.load-config.outputs.env_json }}
+      version: ${{ needs.check-version.outputs.version }}
+      GITOPS_FILE: dev/Chart.yaml
+      GITOPS_YQ_TPL: '(.dependencies[] | select(.name == "git-pages") | .version) = "{{VERSION}}"'
+      GITOPS_REPO: niko/gitea-ci-gitops-tests
+
  report-summary:
    name: Report Summary
-    needs: [load-config, helm-push]
+    needs: [load-config, check-version, helm-push, chart-gitops]
    if: always()
    uses: niko/gitea-ci-library/.gitea/workflows/report-summary.yml@main
    with:
      env_json: ${{ needs.load-config.outputs.env_json }}
      suites: ""
+      gitops: |
+        ${{ needs.chart-gitops.outputs.summary }}
@@ -3,3 +3,4 @@ HELM_REGISTRY=gitea.app.keskikuja.site/niko
 HELM_UI_URL=https://gitea.app.keskikuja.site/niko/-/packages/container
 GIT_TAG_PREFIX=git-pages/
 VERSION_FILE=git-pages/Chart.yaml
+
@@ -0,0 +1,202 @@
+name: GitOps Dispatch
+on:
+  workflow_call:
+    inputs:
+      env_json:
+        required: true
+        type: string
+      version:
+        required: true
+        type: string
+      GITOPS_FILE:
+        required: true
+        type: string
+      GITOPS_YQ_TPL:
+        required: true
+        type: string
+      GITOPS_REPO:
+        required: true
+        type: string
+      GITOPS_EXTRA_CMD:
+        required: false
+        type: string
+    secrets:
+      GITOPS_DISPATCH_TOKEN:
+        required: true
+    outputs:
+      summary:
+        description: "Pipe-format: component|version|status|commit_sha|repo"
+        value: ${{ jobs.dispatch.outputs.summary }}
+
+env:
+  GITOPS_VERSION: ${{ inputs.version }}
+  GITOPS_FILE: ${{ inputs.GITOPS_FILE }}
+  GITOPS_YQ_TPL: ${{ inputs.GITOPS_YQ_TPL }}
+  GITOPS_REPO: ${{ inputs.GITOPS_REPO }}
+  GITOPS_SOURCE_REPO: ${{ github.repository }}
+  GITOPS_SOURCE_COMMIT: ${{ github.sha }}
+  GITEA_API_URL: ${{ fromJson(inputs.env_json).GITEA_API_URL }}
+  GITOPS_TAG_PREFIX: ${{ fromJson(inputs.env_json).GIT_TAG_PREFIX || '' }}
+  GITOPS_EXTRA_CMD: ${{ inputs.GITOPS_EXTRA_CMD || '' }}
+  GITOPS_WORKFLOW: gitops-service.yaml
+  GITOPS_DISPATCH_TIMEOUT: 30
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    outputs:
+      summary: ${{ steps.summary.outputs.GITOPS_SUMMARY }}
+    steps:
+      - name: Generate dispatch_id
+        id: gen
+        run: |
+          ID=$(date +%s | md5sum | head -c 8)
+          echo "dispatch_id=$ID" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve commit author
+        id: author
+        run: |
+          echo "name=$(git log -1 --format='%an')" >> "$GITHUB_OUTPUT"
+          echo "email=$(git log -1 --format='%ae')" >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch to GitOps repo
+        env:
+          GITEA_TOKEN: ${{ secrets.GITOPS_DISPATCH_TOKEN }}
+        run: |
+          INPUTS=$(jq -nc \
+            --arg dispatch_id "${{ steps.gen.outputs.dispatch_id }}" \
+            --arg author_name "${{ steps.author.outputs.name }}" \
+            --arg author_email "${{ steps.author.outputs.email }}" \
+            --arg file "$GITOPS_FILE" \
+            --arg yq_tpl "$GITOPS_YQ_TPL" \
+            --arg version "$GITOPS_VERSION" \
+            --arg source_repo "$GITOPS_SOURCE_REPO" \
+            --arg source_commit "$GITOPS_SOURCE_COMMIT" \
+            --arg git_tag_prefix "${GITOPS_TAG_PREFIX:-}" \
+            --arg extra_cmd "${GITOPS_EXTRA_CMD:-}" \
+            '{dispatch_id: $dispatch_id, author_name: $author_name, author_email: $author_email, file: $file, yq_tpl: $yq_tpl, version: $version, source_repo: $source_repo, source_commit: $source_commit, git_tag_prefix: $git_tag_prefix, extra_cmd: $extra_cmd}')
+          curl -s -X POST \
+            "${GITEA_API_URL}/api/v1/repos/${GITOPS_REPO}/actions/workflows/${GITOPS_WORKFLOW}/dispatches" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "$(jq -nc --arg ref "main" --argjson inputs "$INPUTS" '{ref: "main", inputs: $inputs}')"
+
+      - uses: actions/checkout@v4
+        with:
+          repository: niko/gitea-ci-library
+          path: .ci
+
+      - name: Poll for completion
+        id: poll
+        env:
+          GITEA_TOKEN: ${{ secrets.GITOPS_DISPATCH_TOKEN }}
+        run: |
+          ID="${{ steps.gen.outputs.dispatch_id }}"
+          TIMEOUT_MINUTES="${GITOPS_DISPATCH_TIMEOUT:-30}"
+          POLL_INTERVAL=10
+          START_TIME=$(date +%s)
+          TIMEOUT_SECONDS=$((TIMEOUT_MINUTES * 60))
+
+          echo "Polling for run with dispatch_id=$ID"
+
+          while [ -z "$RUN_ID" ]; do
+            NOW=$(date +%s)
+            ELAPSED=$((NOW - START_TIME))
+            if [ "$ELAPSED" -ge "$TIMEOUT_SECONDS" ]; then
+              echo "ERROR: Timeout waiting for run to appear" >&2
+              exit 124
+            fi
+
+            RUNS_RESP=$(curl -s --connect-timeout 5 --max-time 10 \
+              "${GITEA_API_URL}/api/v1/repos/${GITOPS_REPO}/actions/runs?event=workflow_dispatch&limit=10" \
+              -H "Authorization: token $GITEA_TOKEN")
+            RUN_ID=$(echo "$RUNS_RESP" | jq -r --arg id "$ID" \
+              '[.workflow_runs[] | select(.display_title | contains($id))] | .[0].id // empty')
+
+            [ -z "$RUN_ID" ] && sleep "$POLL_INTERVAL"
+          done
+
+          echo "Run found: id=$RUN_ID"
+
+          while true; do
+            NOW=$(date +%s)
+            ELAPSED=$((NOW - START_TIME))
+            if [ "$ELAPSED" -ge "$TIMEOUT_SECONDS" ]; then
+              echo "ERROR: Timeout waiting for completion" >&2
+              exit 124
+            fi
+
+            RUN_RESP=$(curl -s --connect-timeout 5 --max-time 10 \
+              "${GITEA_API_URL}/api/v1/repos/${GITOPS_REPO}/actions/runs/${RUN_ID}" \
+              -H "Authorization: token $GITEA_TOKEN")
+            STATUS=$(echo "$RUN_RESP" | jq -r '.status // "running"')
+            CONCLUSION=$(echo "$RUN_RESP" | jq -r '.conclusion // ""')
+
+            echo "  status=$STATUS conclusion=$CONCLUSION"
+
+            if [ "$STATUS" = "completed" ]; then
+              if [ "$CONCLUSION" = "success" ]; then
+                echo "GitOps workflow completed successfully"
+
+                # 1. List recent commits from GitOps repo
+                COMMITS=$(curl -s --connect-timeout 5 --max-time 10 \
+                  "${GITEA_API_URL}/api/v1/repos/${GITOPS_REPO}/commits?sha=main&limit=10" \
+                  -H "Authorization: token $GITEA_TOKEN")
+
+                # 2. Find commit by message: "gitops: update version to X.Y.Z"
+                SEARCH_MSG="gitops: update version to ${GITOPS_VERSION}"
+                GITOPS_COMMIT=$(echo "$COMMITS" | jq -r \
+                  --arg msg "$SEARCH_MSG" \
+                  '[.[] | select(.commit.message | contains($msg))] | .[0].sha // empty')
+
+                # 3. If not found → fail
+                if [ -z "$GITOPS_COMMIT" ]; then
+                  echo "ERROR: no matching GitOps commit found for version ${GITOPS_VERSION}" >&2
+                  exit 1
+                fi
+
+                echo "GITOPS_COMMIT=$GITOPS_COMMIT" >> "$GITHUB_OUTPUT"
+                echo "$GITOPS_COMMIT" > /tmp/gitops-commit
+                exit 0
+              else
+                echo "ERROR: GitOps workflow failed with conclusion=$CONCLUSION" >&2
+                exit 1
+              fi
+            fi
+
+            sleep "$POLL_INTERVAL"
+          done
+
+      - name: GitOps summary
+        id: summary
+        if: always()
+        run: |
+          STATUS="failure"
+          GITOPS_SHA=""
+          if [ -f /tmp/gitops-commit ]; then
+            STATUS="success"
+            GITOPS_SHA=$(cat /tmp/gitops-commit)
+          fi
+          COMPONENT="${GITOPS_TAG_PREFIX:-${GITOPS_FILE}}"
+          echo "GITOPS_SUMMARY=${COMPONENT}|${GITOPS_VERSION}|${STATUS}|${GITOPS_SHA}|${GITOPS_REPO}" >> "$GITHUB_OUTPUT"
+
+      - name: Set commit status
+        if: success()
+        env:
+          GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          GITOPS_SHA=$(cat /tmp/gitops-commit)
+
+          PREFIX="${GITOPS_TAG_PREFIX%/}"
+          if [ -n "$PREFIX" ]; then
+            CONTEXT="gitops/$(basename "${GITOPS_SOURCE_REPO}")/${PREFIX}"
+            DESCRIPTION="GitOps: ${PREFIX} ${GITOPS_VERSION}"
+          else
+            CONTEXT="gitops/$(basename "${GITOPS_SOURCE_REPO}")"
+            DESCRIPTION="GitOps: ${GITOPS_VERSION}"
+          fi
+
+          ROOT_REPO="${GITOPS_SOURCE_REPO}" ROOT_COMMIT="${GITOPS_SOURCE_COMMIT}" \
+            bash .ci/scripts/report-status.sh success \
+            "$DESCRIPTION" "$CONTEXT" "" \
+            "${GITEA_API_URL}/${GITOPS_REPO}/commit/${GITOPS_SHA}"
@@ -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}")
@@ -73,7 +86,11 @@ jobs:
        run: |
          CHART_NAME=$(grep '^name:' "${CHART_FILE}" | awk '{print $2}')
          UI_URL="${HELM_UI_URL}/${CHART_NAME}/${VERSION}"
-          bash .ci/scripts/report-status.sh success "Helm chart ${VERSION}" ci-helm-build-push "" "$UI_URL"
+          if [ "${CHART_PATH}" != "." ] && [ -n "${CHART_PATH}" ]; then
+            bash .ci/scripts/report-status.sh success "${CHART_PATH}: Helm push ${VERSION}" "${CHART_PATH}-ci-helm-build-push" "" "$UI_URL"
+          else
+            bash .ci/scripts/report-status.sh success "Helm push ${VERSION}" ci-helm-build-push "" "$UI_URL"
+          fi

  tag-commit:
    runs-on: ubuntu-latest
@@ -9,6 +9,10 @@ on:
        required: true
        type: string
        description: Space-separated suite names published to git-pages
+      gitops:
+        required: false
+        type: string
+        description: 'Pipe-separated rows: component|version|status|commit_sha|repo'

 env:
  GIT_PAGES_URL: ${{ fromJson(inputs.env_json).GIT_PAGES_URL }}
@@ -32,3 +36,22 @@ jobs:
              echo "| ${suite} | [View report](${BASE}/${suite}/) |"
            done
          } >> "${GITHUB_STEP_SUMMARY}"
+
+          if [ -n "${{ inputs.gitops }}" ]; then
+            GITEA_URL="${{ fromJson(inputs.env_json).GITEA_API_URL }}"
+            {
+              echo ""
+              echo "## GitOps updates"
+              echo ""
+              echo "| Component | Version | Status | GitOps commit |"
+              echo "|-----------|---------|--------|--------------|"
+              echo '${{ inputs.gitops }}' | while IFS='|' read -r comp ver status sha repo; do
+                [ -z "$comp" ] && continue
+                if [ -n "$sha" ]; then
+                  echo "| $comp | $ver | $status | [link]($GITEA_URL/$repo/commit/$sha) |"
+                else
+                  echo "| $comp | $ver | $status | — |"
+                fi
+              done
+            } >> "${GITHUB_STEP_SUMMARY}"
+          fi
@@ -4,6 +4,8 @@ Reusable workflow -kirjasto Gitea Actionsille. Lisätietoja: [docs/](docs/)

 **Consumer-käyttöönotto:** [skills/consumer-pipelines/SKILL.md](skills/consumer-pipelines/SKILL.md) — pipeline-standardit ja säännöt consumer-projekteille

+**GitOps-päivitys:** [skills/gitops-update/SKILL.md](skills/gitops-update/SKILL.md) — GitOps-repon job-template, dispatch ja token-ohjeet
+
 **Single repo & monorepo:** Kirjasto toimii molemmissa. Monorepo-tuki
 polkusuodatuksella, komponenttikohtaisilla versioilla ja git-tägien
 etuliitteillä — jokainen komponentti julkaistaan itsenäisesti omassa
@@ -149,58 +151,102 @@ ja sitä kautta Gitea ei tarvitse päivityksessä mitään temppuja.
 Päivityksen jälkeen muista tappaa pod (käynnistyy automaattisesti uudelleen), että lataa varmasti kaikki uudesta. Sillä ConfigMap tms eivät lataudu
 mikäli pod jatkaa ajamista.

+Klusterissa on kaksi StatefulSetiä, joilla on eri labelit:
+- **`act-runner`** — yleisrunneri (label `ubuntu-latest`). DinD-sidecar on olemassa mutta idle — `require_docker: false` estää runneria käyttämästä sitä.
+- **`act-runner-docker`** — Docker-buildien runneri (label `docker`). DinD on aktiivinen, `require_docker: true`.
+
+Vain `docker-build-push.yml` ja `ci-container-build-push.yml` käyttävät `docker`-labelia.
+Kaikki muut workflowt (testit, lintit, helm-publish, gitops-dispatch) ajetaan `ubuntu-latest`-runnerilla.
+Steppien suoritus ei mene Docker Daemonin läpi, joten konekielisiä kontteja luodaan suoraan K8s-runtimella.
+
 ```bash
 helm repo add gitea https://dl.gitea.com/charts
 helm repo update

+# 1. Yleisrunneri (DinD idle)
 helm upgrade --install act-runner gitea/actions \
  --set enabled=true \
  --set giteaRootURL="$GITEA_URL" \
  --set existingSecret=act-runner-token \
  --set existingSecretKey=token \
-  --set statefulset.replicas=3 \
+  --set statefulset.replicas=2 \
  --set statefulset.runner.tag=1.0.8 \
  --set statefulset.dind.tag=29.5.2-dind \
+  --set statefulset.dind.resources.requests.memory=250Mi \
+  --set statefulset.dind.resources.limits.memory=750Mi \
  --set-string 'statefulset.runner.config=log:
  level: info
 cache:
-  enabled: false
+  enabled: true
 container:
-  require_docker: true
-  docker_timeout: 300s' \
+  require_docker: false' \
  --namespace "$GITEA_ACTIONS_NAMESPACE" \
  --create-namespace
+
+# 2. Docker-runner (DinD)
+helm upgrade --install act-runner-docker gitea/actions \
+  --set enabled=true \
+  --set giteaRootURL="$GITEA_URL" \
+  --set existingSecret=act-runner-token \
+  --set existingSecretKey=token \
+  --set statefulset.replicas=1 \
+  --set statefulset.runner.tag=1.0.8 \
+  --set statefulset.dind.tag=29.5.2-dind \
+  --set statefulset.dind.resources.requests.memory=250Mi \
+  --set statefulset.dind.resources.limits.memory=750Mi \
+  --set-string 'statefulset.runner.config=log:
+  level: info
+cache:
+  enabled: true
+container:
+  require_docker: true
+  docker_timeout: 300s
+runner:
+  labels:
+    - "docker:docker://catthehacker/ubuntu:act-latest"' \
+  --namespace "$GITEA_ACTIONS_NAMESPACE"
 ``` 

-path escapes from parent -bugi korjattiin Docker 29.5.2:ssa. Tämän teko aikana default on 29.5.1 — juuri tämän alle jäävä versio.
+`path escapes from parent` -bugi korjattiin Docker 29.5.2:ssa. Tämän teko aikana default on 29.5.1 — juuri tämän alle jäävä versio.

 Oletus-lokitaso on `debug` — suositeltu `info`. Näkee jobien aloitukset ja valmistumiset ilman konttikerrosten purkua (Downloading/Extracting-spämmiä). `debug` on tarpeen vain vianselvityksessä.

+`cache.enabled: true` nappaa image-cachen käyttöön — ilman sitä jokainen ajo lataa konttikuvat uudestaan.
+
 #### Docker (DinD)

-Helm chart deployaa DinD:n init-sidecarina (`docker:dind` samassa podissa).
-`require_docker: true` kytkee jobit siihen — erillistä DinD-asennusta ei tarvita.
+> **Huomio:** Gitea 1.26.x ei tue vielä label-pohjaista runner-valintaa.
+> `runs-on: ubuntu-latest`-jobi saattaa päätyä `docker`-labeliselle runnerille.
+> Bugi on tunnettu Gitean FAQ:ssa — korjaus tulossa myöhemmässä versiossa.
+> Katso: [docs.gitea.com/usage/actions/faq](https://docs.gitea.com/usage/actions/faq)

-**DinD-tag pinottu:** `29.5.2-dind` (ei chart-oletusta). Docker 29.5.1 aiheuttaa act-runnerissa
-`path escapes from parent` -virheen job-kontin käynnistyksessä.
+Helm chart deployaa DinD:n init-sidecarina (`docker:dind` samassa podissa).
+Molemmissa StatefulSetissä on DinD-sidecar, mutta:
+- **`act-runner`**: `require_docker: false` → runner ei käytä DinD:tä lainkaan, steppien suoritus menee suoraan K8s-runtimella
+- **`act-runner-docker`**: `require_docker: true` → runner luo steppikontit DinD:n kautta (tarvitaan `docker build` -komentoja varten)
+
+**DinD-tag pinottu:** `29.5.2-dind` molemmissa (ei chart-oletusta `29.5.1-dind`). Docker 29.5.1 aiheuttaa act-runnerissa
+`path escapes from parent` -virheen job-kontin käynnistyksessä sekä `mkdirat var/run: file exists` -virheen tiedostojen kopioinnissa.

 Maven/npm-ajot käyttävät vain workflow'n `container:`-imagea; DinD tarvitaan vasta Docker-buildissä.

-### 3. Varmista
+### 5. Varmista

 ```bash
 kubectl get pods -n gitea-actions
 # → act-runner-runner-0  Running
+# → act-runner-docker-runner-0  Running

-kubectl exec -n gitea-actions act-runner-runner-0 -c dind -- docker version
+kubectl exec -n gitea-actions act-runner-docker-runner-0 -c dind -- docker version
 # → Server Version: 29.5.2 (tai uudempi)
 ```

-Gitean puolella runner ilmestyy Active-tilaan pienellä viiveellä:
+Gitean puolella runnerit ilmestyvät Active-tilaan pienellä viiveellä:

 ```
 Site Admin → Actions → Runners  (tai Org → Settings → Actions → Runners)
 # → act-runner-runner-0  Active  ubuntu-latest
+# → act-runner-docker-runner-0  Active  docker
 ```

 Tämän jälkeen `.gitea/workflows/ci.yml` triggeröityy automaattisesti pushista.
@@ -220,7 +266,9 @@ Consumer-repossa on oltava seuraavat asetukset:
 |--------|--------|
 | `GIT_PAGES_PUBLISH_TOKEN` | Git-pages-palvelimen BasicAuth-token. Nimi on lukittu — tämä tarkka nimi vaaditaan. |

-`GITEA_TOKEN` on Gitean sisäinen secret (`secrets.GITEA_TOKEN`), joka on automauttisesti saatavilla — sitä ei tarvitse erikseen luoda.
+`GITEA_TOKEN` on Gitean automaattisesti jokaiselle workflow-runille generoima token (`secrets.GITEA_TOKEN`). Se on scopeutettu **siihen repoon**, jossa workflow ajaa — ei toimi toiseen repoon dispatchaukseen eikä toisen repon commit-statusin asettamiseen. Ei tarvitse erikseen luoda.
+
+Jos workflow tarvitsee oikeuksia **toiseen** repoon (esim. dispatch GitOps-repoon), tarvitaan manuaalinen token. Katso [skills/gitops-update/SKILL.md](skills/gitops-update/SKILL.md).

 ### Config-tiedosto (`.gitea/workflows/gitea-env.conf`)

@@ -256,6 +304,17 @@ Jokaisen jobin alussa `ci-validate.sh` tarkistaa:

 Jos validointi epäonnistuu, job keskeytyy exit-koodilla 1 ja Gitean commit-status näyttää epäonnistumisen linkkinä lokiin.

+### GitOps-päivitys
+
+Artifact buildin jälkeen voidaan dispatchata GitOps-repoon, joka päivittää
+konfiguraatiotiedoston (esim. Chart.yaml version) ja pushaa muutoksen.
+
+Kaksi skriptiä:
+- `scripts/dispatch-workflow.sh` — lähettää workflow_dispatch-pyynnön ja pollaa valmistumista
+- `scripts/gitops-update.sh` — kloonaa, päivittää yq:llä, committaa ja pushaa
+
+Tarkka asennus: [skills/gitops-update/SKILL.md](skills/gitops-update/SKILL.md)
+
 ### Muuta

 | Muuttuja | Kuvaus |
@@ -264,4 +323,7 @@ Jos validointi epäonnistuu, job keskeytyy exit-koodilla 1 ja Gitean commit-stat
 | `existingSecret` | Kubernetes secretin nimi, jossa token |
 | `existingSecretKey` | Avain secretin sisällä |
 | `statefulset.dind.tag` | DinD-image tag (`29.5.2-dind` minimi) |
+| `statefulset.dind.resources.requests.memory` | DinD muistirequest (suositus `250Mi`) |
+| `statefulset.dind.resources.limits.memory` | DinD muistilimitti (suositus `750Mi`) |
 | `statefulset.runner.labels` | Mukautetut labelit |
+
@@ -60,9 +60,15 @@ Salaisuudet eivät ole `.conf`-tiedostossa. Ne määritellään Gitean
 organization/repository secrets -mekanismissa ja välitetään workflowlle
 `secrets: inherit` -direktiivillä.

+**`secrets.GITEA_TOKEN` on Gitean automaattisesti generoima token,
+scopeutuu siihen repoon jossa workflow ajaa.** Se ei oikeuta
+dispatchaamaan toiseen repoon eikä kirjoittamaan toisen repon
+commit-statusta. Cross-repo-operaatioihin tarvitaan manuaalinen
+org-tason token.
+
 | Secret | Pakollinen | Käyttäjä |
 |---|---|---|
-| `GITEA_TOKEN` | Kyllä | `report-status.sh`, `check-version.yml`, `docker-build-push.yml` |
+| `GITEA_TOKEN` | Kyllä | `report-status.sh`, `check-version.yml`, `docker-build-push.yml`, `gitops-update.sh` (GitOps-repossa) |
 | `GIT_PAGES_PUBLISH_TOKEN` | Kyllä | `publish-git-pages.sh`, `config-provider.yml` (validointi) |
 | `DOCKER_USERNAME` | Ei | `docker-build-push.yml` (oletus: `github.actor`, ei pakollinen kaikissa registryissä) |
 | `DOCKER_PASSWORD` | Kyllä | `docker-build-push.yml` |
@@ -113,17 +113,38 @@ Lukee tiedoston polun `CI_CONF_FILE`-env-muuttujasta (oletus: `.gitea/workflows/
 Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista synkronisesti.
 Käytetään GitOps-deploymentissa ja klusteritestien ketjutuksessa (tuleva).

+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 ajoja.
+
+**Kohde-workflow'ssa on oltava `dispatch_id`-input ja `run-name`-kenttä
+`display_title`-matchausta varten.** Katso `skills/gitops-update/SKILL.md`.
+
 ### Rajapinta

 ```bash
-dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> [timeout_minutes]
+dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> <gitea_api_url> <gitea_token> [timeout_minutes]
 ```

+| Parametri | Pakollinen | Kuvaus |
+|-----------|------------|--------|
+| `target_repo` | Kyllä | `owner/repo` |
+| `workflow_file` | Kyllä | Workflow-tiedosto (esim. `ci-main.yml`) |
+| `ref` | Kyllä | Branch |
+| `inputs_json` | Kyllä | JSON-objekti dispatch-inputteina |
+| `gitea_api_url` | Kyllä | Gitean API-URL |
+| `gitea_token` | Kyllä | Gitea API -token (write kohderepoon) |
+| `timeout_minutes` | Ei | Aikakatkaisu (oletus 360) |
+
 ### Toiminta

-1. **Dispatch:** `POST /api/v1/repos/{target_repo}/actions/workflows/{workflow_file}/dispatches`
-2. **Poll:** `GET /api/v1/repos/{target_repo}/actions/runs` → odota valmistumista
-3. **Palauta:** `conclusion` (`success`/`failure`/`timeout`)
+1. **Generoi `dispatch_id`** — 8-hex uniikki tunniste
+2. **Injektoi** `dispatch_id` inputteihin
+3. **Dispatch:** `POST /api/v1/repos/{target_repo}/actions/workflows/{workflow_file}/dispatches`
+4. **Etsi run:** pollaa rinnakkaisia `workflow_dispatch`-runeja, matchaa `display_title` sisältää `dispatch_id`:n
+5. **Poll:** `GET /api/v1/repos/{target_repo}/actions/runs/{run_id}` — odota valmistumista
+6. **Palauta:** exit 0 (success), exit 1 (failure), exit 124 (timeout)

 ---

@@ -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
@@ -136,6 +138,29 @@ eikä toimi air gap -ympäristössä. Korvaa tarvittaessa custom-kontilla

 ---

+### `gitops-dispatch.yml` — GitOps-päivityksen dispatch
+
+**Trigger:** `workflow_call`
+
+**Inputit:**
+
+| Parametri | Pakollinen | Kuvaus |
+|-----------|------------|--------|
+| `env_json` | Kyllä | Konffi, josta luetaan `GITOPS_FILE`, `GITOPS_YQ_TPL`, `GITOPS_REPO`, `GIT_TAG_PREFIX` |
+| `version` | Kyllä | Päivitettävä versio (check-version output) |
+| `component` | Kyllä | `chart` tai `container` — tunniste summary-riville |
+
+**Secretit:** `GITOPS_TOKEN`
+
+**Outputit:** `summary` — pipe-formaatti: `{component}|{version}|{status}|{commit_sha}|{repo}`
+
+**Steppi-kaavio:**
+```
+checkout → gitops-dispatch.sh → dispatch-workflow.sh → GITOPS_SUMMARY output
+```
+
+---
+
 ## Consumer-esimerkki (`example-*`)

 ### `example-feature.yml` — Feature-haaran CI
@@ -151,11 +176,23 @@ load-config → bats + cucumber → report-summary (always)
 **Trigger:** `push` [branches: main]

 ```
-load-config → check-version →
-  [artifact exists] → done
-  [no artifact]    → bats + cucumber → report-summary (always) → docker-build-push
+load-config ───────────────────────────────────────────────────────┐
+load-config-helm ───────────────────────────────────────────┐      │
+                                                            │      │
+check-version ←─────────────────────────────────────────────┘      │
+  │                                                                │
+  └→ bats + cucumber                                               │
+       ├─ docker-build-push → gitops-container ─┐                  │
+       └─ helm-build-push  → gitops-chart ──────┤                  │
+                                                ├→ report-summary ←┘
+       tag-maintenance ←────────────────────────┘
 ```

+GitOps-jobit (`gitops-chart`, `gitops-container`) käyttävät
+`gitops-dispatch.yml`-provider-workflowia. Kaksisuuntainen track:
+dispatch-workflow.sh → GITOPS_COMMIT + GITOPS_SUMMARY.
+Katso [skills/gitops-update/SKILL.md](../skills/gitops-update/SKILL.md).
+
 ### `example-bats-tests.yml` — Bats unit-testit

 **Trigger:** `workflow_call`
@@ -174,7 +211,12 @@ commit-statuksen linkillä raporttiin.

 **Trigger:** `workflow_call` — ajetaan `if: always()` testien jälkeen

-**Inputs:** `env_json`, `suites` (space-separated lista suite-nimistä)
+**Inputs:** `env_json`, `suites` (space-separated lista suite-nimistä), `gitops` (optional JSON array)
+
+**GitOps-tuki:** Jos `gitops` input on annettu (JSON array objekteilla
+`component`, `version`, `status`, `commit`, `repo`), workflow lisää
+GitOps-päivitystaulukon testiraporttien perään. Jokaiselle riville
+muodostuu linkki GitOps-repon committiin.

 Generoi Markdown-taulukon `GITHUB_STEP_SUMMARY`:yn kaikista julkaistuista
 raporteista. Renderöityy HTML:ksi Gitea 1.27+ Summary-välilehdellä.
@@ -182,7 +224,77 @@ Forward-compatibeli — ei haittaa vanhemmilla Gitea-versioilla.

 ---

-## Suunnitteilla
+## Provider-skriptit

- `deploy.yml` — GitOps-deployment (dispatch-workflow.sh-pohjainen)
- `test.yml` — Klusteritason test flow
+### `gitops-update.sh` — GitOps-version päivitys
+
+**Riippuvuudet:** `yq`, `scripts/report-status.sh`, `git`
+
+Päivittää GitOps-repon konfiguraatiotiedoston versionumeron `yq`:lla,
+committaa muutoksen ja asettaa commit-statuksen molempiin repoihin
+(kaksisuuntainen track):
+
+| Status | Mihin repo | Context | Linkki |
+|---|---|---|---|
+| ✅ | **GitOps-repo** | `source/{repo}` | Code-repon committiin |
+| ✅ | **Code-repo** (dispatchin jälkeen) | `gitops/{repo} {RUN_ID}` | GitOps-repon committiin |
+
+**Input-ympäristömuuttujat (ajetaan GitOps-repon workflow'ssa):**
+
+| Muuttuja | Pakollinen | Kuvaus |
+|---|---|---|
+| `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ä | Lähdekoodirepo (esim. `org/app`) |
+| `SOURCE_COMMIT` | Kyllä | Lähdekoodin 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 | GitOps-repon branch (oletus `main`) |
+| `GIT_TAG_PREFIX` | Ei | Komponentin tag-prefix status-nimeämiseen |
+
+**Commit-status (GitOps-repoon):**
+| Kenttä | Formaatti | Esimerkki |
+|--------|-----------|-----------|
+| Context | `source/{repo}` | `source/gitea-ci-library` |
+| Description | `Install to {env} {version}` | `Install to dev 0.2.0` |
+| Target URL | Linkki code-repon committiin | `/org/repo/commit/sha` |
+
+`{env}` parsitaan `INPUT_FILE`:stä (`dev/Chart.yaml` → `dev`).
+
+**Steppikuvaus:**
+1. Korvaa `YQ_TPL`:n `{{VERSION}}` versiolla
+2. Muodostaa `CLONE_URL` tokenilla ja hostilla
+3. Kloonaa GitOps-repon
+4. Ajaa `yq eval -i` päivittääkseen tiedoston
+5. Jos muutoksia: commit + push `[skip ci]`, muuten status `— no change`
+6. Asettaa commit-statuksen GitOps-repoon (source-konteksti, linkki code-repoon)
+
+**Scriptiä ei ajeta code reposta.** Se ajaa GitOps-repon workflow'ssa.
+
+### Code-repon commit-status (dispatchin jälkeen)
+
+GitOps-päivityksen valmistuttua `dispatch-workflow.sh` tulostaa
+`GITOPS_COMMIT=<sha>` (GitOps-repon commitin SHA). Code repo asettaa
+oman commit-statusinsa linkillä GitOps-committiin:
+
+| Kenttä | Formaatti | Esimerkki |
+|--------|-----------|-----------|
+| Context | `gitops/{repo} {RUN_ID}` | `gitops/gitea-ci-library 473` |
+| Description | `Install to {env} {version}` | `Install to dev 0.2.0` |
+| Target URL | Linkki GitOps-repon committiin | `/niko/gitea-ci-gitops-tests/commit/def456` |
+
+### Loppuraportti (GITHUB_STEP_SUMMARY)
+
+`report-summary.yml` (optio `gitops`-inputti) lisää GitOps-rivit
+GITHUB_STEP_SUMMARYyn:
+
+| Component | Version | Status | GitOps commit |
+|---|---|---|---|
+| helm | 0.2.0 | success | [link](...) |
+
+Kokonainen esimerkki molemmista puolista: [skills/gitops-update/SKILL.md](../skills/gitops-update/SKILL.md)
+ja [.gitea/workflows/example-main.yml](../.gitea/workflows/example-main.yml).
+
+---
@@ -149,3 +149,42 @@ curl -X PATCH https://ci-reports.helm-dev.keskikuja.site/owner/repo/commit/sha8/
 - `git-pages-publish-token` = plaintext (luetaan Giteaan viedessä)

 Tarkemmat secret-ohjeet: [docs/secrets.md](docs/secrets.md).
+
+---
+
+## Testaus
+
+Retention-logiikalle on unit-testit, jotka testaa funktiot ja Phase 3 -säännöt
+erikseen ilman ulkoisia riippuvuuksia.
+
+```bash
+cd git-pages
+bats tests/retention.bats
+```
+
+Testit käyttävät `<root>/files/retention-lib.sh` -jaettua kirjastoa, jota myös
+`retention-cleanup.sh` sourceaa. Uutta testiä kirjoittaessa:
+
+1. Luo config `write_config`-helperilla
+2. Täytä `KEEP`-array testidatalla (muoto: `dir|owner|repo|branch|days`)
+3. Kutsu `apply_retention "$CONFIG"`
+4. Tarkista `TO_DELETE`-array ja `$output`
+
+**Vaatimukset:** `bats`, `jq`, `date` (GNU date tai BSD date ISO 8601 -tuella).
+
+---
+
+## Retention
+
+Ylläpitoscripti, joka poistaa vanhat raportit git-pagesista retention‑sääntöjen mukaan.
+Ajetaan sidecar‑ tai cronjob‑tilassa Kubernetesissa.
+
+### Air gap -yhteensopimattomuus
+
+Retention‑kontti asentaa tarvitsemansa työkalut (`curl`, `jq`) ajon aikana
+packagemanagerilla (`apt-get` / `apk`). Tämä **ei toimi air gap -ympäristössä**,
+jossa konttirekisteriin tai pakettivarastoihin ei ole verkkoyhteyttä.
+
+**TODO:** Rakenna custom Docker‑image, jossa deps on valmiina:
+`FROM alpine:latest && apk add --no-cache curl jq`.
+Pushaa omaan rekisteriin ja päivitä `values.yaml`:n `retention.image`.
@@ -13,75 +13,11 @@ curl_with_host() {

 [ -f "$CONFIG" ] || { echo "ERROR: config missing: $CONFIG" >&2; exit 1; }

-declare -A BRANCH_CACHE
-branch_exists() {
-  local owner="$1" repo="$2" branch="$3" key="${owner}/${repo}/${branch}"
-  local status attempt
+declare -A REPO_BRANCHES_CACHE
+declare -A REPO_STATUS

-  [ -z "$GITEA_API_URL" ] && return 0
-  [ -z "$GITEA_TOKEN" ] && return 0
-  
-  if [ "${BRANCH_CACHE[$key]:-}" = "1" ]; then
-    return 0
-  fi
-  
-  # Retry up to 2 times on API errors (hardcoded)
-  for attempt in 1 2 3; do
-    status=$(curl -sS -o /dev/null -w "%{http_code}" \
-      -H "Authorization: token ${GITEA_TOKEN}" \
-      "${GITEA_API_URL}/api/v1/repos/${owner}/${repo}/branches/${branch}" 2>/dev/null || echo "000")
-    
-    if [ "$status" = "200" ]; then
-      BRANCH_CACHE[$key]=1
-      return 0
-    fi
-    
-    if [ "$status" = "404" ]; then
-      return 1
-    fi
-    
-    # API error - retry if not last attempt
-    if [ "$attempt" -lt 3 ]; then
-      sleep 10
-      continue
-    fi
-  done
-  
-  # All retries failed - keep report (fail-safe)
-  echo "  WARN: Gitea API error for ${owner}/${repo}/${branch} (status ${status}) after 3 attempts - KEEPING report"
-  BRANCH_CACHE[$key]=1
-  return 0
-}
-
-default_max_age=$(jq -r '.branches.default.maxAgeDays // 90' "$CONFIG")
-default_keep_min=$(jq -r '.branches.default.keepMin // 5' "$CONFIG")
-
-rule_max_age() {
-  local branch="$1" v
-  v=$(jq -r --arg b "$branch" '.branches[$b].maxAgeDays // empty' "$CONFIG")
-  [ -n "$v" ] && echo "$v" || echo "$default_max_age"
-}
-
-rule_keep_min() {
-  local branch="$1" v
-  v=$(jq -r --arg b "$branch" '.branches[$b].keepMin // empty' "$CONFIG")
-  [ -n "$v" ] && echo "$v" || echo "$default_keep_min"
-}
-
-age_days() {
-  local published="$1" epoch_pub now
-  epoch_pub=$(date -u -d "$published" +%s 2>/dev/null || echo 0)
-  [ "$epoch_pub" -eq 0 ] && echo 99999 && return
-  now=$(date -u +%s)
-  echo $(( (now - epoch_pub) / 86400 ))
-}
-
-parse_path() {
-  local rel="$1"
-  OWNER="${rel%%/*}"
-  rest="${rel#*/}"
-  REPO="${rest%%/*}"
-}
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/retention-lib.sh"

 echo "Fetching manifest from ${PAGES_URL}/.git-pages/manifest.json"
 MANIFEST=$(curl_with_host "${PAGES_URL}/.git-pages/manifest.json")
@@ -97,6 +33,7 @@ fi
 echo ""
 echo "=== Phase 1: collect reports ==="
 declare -A SEEN_REPORTS
+declare -A SEEN_ECHO_COMMITS
 declare -a REPORTS
 while IFS= read -r meta_path; do
  report_dir=$(dirname "$meta_path")
@@ -117,58 +54,105 @@ while IFS= read -r meta_path; do

  days=$(age_days "$published")
  REPORTS+=("${report_dir}|${OWNER}|${REPO}|${branch}|${days}")
-  echo "  ${OWNER}/${REPO} branch=${branch} age=${days}d"
+
+  commit_dir=$(dirname "$report_dir")
+  if [ -z "${SEEN_ECHO_COMMITS[$commit_dir]:-}" ]; then
+    SEEN_ECHO_COMMITS[$commit_dir]=1
+    echo "  ${commit_dir} branch=${branch} age=${days}d"
+  fi
 done <<< "$META_PATHS"

 [ "${#REPORTS[@]}" -eq 0 ] && { echo "No actionable reports"; exit 0; }

 echo ""
-echo "=== Phase 2: check branches in Gitea ==="
+echo "=== Phase 2: check branches/repos in Gitea ==="
+if [ -z "$GITEA_API_URL" ] || [ -z "$GITEA_TOKEN" ]; then
+  echo "ERROR: GITEA_API_URL and GITEA_TOKEN must be set" >&2
+  exit 1
+fi
 declare -a TO_DELETE
 declare -a KEEP
+declare -A SEEN_ECHO_BRANCHES
+declare -A SEEN_ECHO_REPO_DELETED
+declare -A UNIQUE_BRANCHES
+declare -A REASON_MAP
+declare -A COMMIT_BRANCH_MAP
+
+# Build commit→branch mapping
+for entry in "${REPORTS[@]}"; do
+  IFS='|' read -r dir _ _ branch _ <<< "$entry"
+  commit_dir=$(dirname "$dir")
+  [ -n "${COMMIT_BRANCH_MAP[$commit_dir]:-}" ] || COMMIT_BRANCH_MAP["$commit_dir"]=$branch
+done
+for entry in "${REPORTS[@]}"; do
+  IFS='|' read -r _ owner repo branch _ <<< "$entry"
+  UNIQUE_BRANCHES["${owner}/${repo}/${branch}"]=1
+done
+TOTAL_BRANCHES=${#UNIQUE_BRANCHES[@]}
+BRANCHES_EXISTING=0
+BRANCH_DELETED_COUNT=0
+REPO_DELETED_COUNT=0
+MAXAGE_DELETED=0
+KEEPMIN_DELETED=0
 for entry in "${REPORTS[@]}"; do
  IFS='|' read -r dir owner repo branch days <<< "$entry"

-  if [ -n "$GITEA_API_URL" ] && [ -n "$GITEA_TOKEN" ]; then
+  branch_key="${owner}/${repo}/${branch}"
  if branch_exists "$owner" "$repo" "$branch"; then
-      echo "  BRANCH EXISTS: ${owner}/${repo}/${branch}"
-      KEEP+=("${dir}|${owner}|${repo}|${branch}|${days}")
-    else
-      echo "  BRANCH DELETED: ${owner}/${repo}/${branch} -> DELETE"
-      TO_DELETE+=("$dir")
+    if [ -z "${SEEN_ECHO_BRANCHES[$branch_key]:-}" ]; then
+      SEEN_ECHO_BRANCHES[$branch_key]=1
+      BRANCHES_EXISTING=$((BRANCHES_EXISTING + 1))
+      echo "  BRANCH EXISTS: ${branch_key}"
    fi
-  else
    KEEP+=("${dir}|${owner}|${repo}|${branch}|${days}")
+  else
+    if [ -z "${SEEN_ECHO_BRANCHES[$branch_key]:-}" ]; then
+      SEEN_ECHO_BRANCHES[$branch_key]=1
+      repo_key="${owner}/${repo}"
+      if [ "${REPO_STATUS[$repo_key]:-}" = "deleted" ]; then
+        REPO_DELETED_COUNT=$((REPO_DELETED_COUNT + 1))
+        if [ -z "${SEEN_ECHO_REPO_DELETED[$repo_key]:-}" ]; then
+          SEEN_ECHO_REPO_DELETED[$repo_key]=1
+          echo "  REPO DELETED: ${repo_key} -> DELETE ALL"
+        fi
+        reason="repo deleted"
+      else
+        BRANCH_DELETED_COUNT=$((BRANCH_DELETED_COUNT + 1))
+        echo "  BRANCH DELETED: ${branch_key} -> DELETE"
+        reason="branch deleted"
+      fi
+    fi
+    REASON_MAP["$dir"]="$reason"
+    TO_DELETE+=("$dir")
  fi
 done

 echo ""
 echo "=== Phase 3: apply retention rules to remaining reports ==="
-declare -A BRANCH_COUNTS
-if [ "${#KEEP[@]}" -gt 0 ]; then
-  IFS=$'\n'
-  for entry in $(printf '%s\n' "${KEEP[@]}" | sort -t'|' -k4,4 -k5,5rn); do
-    IFS='|' read -r dir owner repo branch days <<< "$entry"
-    max_age=$(rule_max_age "$branch")
-    keep_min=$(rule_keep_min "$branch")
+PHASE2_DELETED=${#TO_DELETE[@]}
+apply_retention "$CONFIG"
+PHASE3_DELETED=$(( ${#TO_DELETE[@]} - PHASE2_DELETED ))

-    if [ "$days" -gt "$max_age" ]; then
-      echo "  DELETE: ${dir} (age ${days}d > maxAge ${max_age}d, branch ${branch})"
-      TO_DELETE+=("$dir")
-      continue
-    fi
-
-    key="${branch}"
-    count="${BRANCH_COUNTS[$key]:-0}"
-    count=$((count + 1))
-    BRANCH_COUNTS["$key"]=$count
-    if [ "$count" -gt "$keep_min" ]; then
-      echo "  DELETE: ${dir} (kept ${keep_min}/${count}, exceeds keepMin, branch ${branch})"
-      TO_DELETE+=("$dir")
-    fi
+fmt_num() {
+  local n="$1" out=""
+  [ -z "$n" ] && { echo "?"; return; }
+  n="${n##0}"  # strip leading zeros
+  while [ "${#n}" -gt 3 ]; do
+    out=" ${n: -3}$out"
+    n="${n:0:${#n}-3}"
  done
-  unset IFS
-fi
+  echo "${n}${out}"
+}
+
+echo ""
+echo "=== Summary ==="
+echo "  Branches:"
+echo "    existing:          $(fmt_num $BRANCHES_EXISTING)"
+echo "    deleted:           $(fmt_num $BRANCH_DELETED_COUNT)"
+echo "    repo gone:         $(fmt_num $REPO_DELETED_COUNT)"
+echo "  Commits:"
+echo "    deleted by maxAge: $(fmt_num $MAXAGE_DELETED)"
+echo "    deleted by keepMin:$(fmt_num $KEEPMIN_DELETED)"

 if [ "${#TO_DELETE[@]}" -eq 0 ]; then
  echo "Nothing to delete"
@@ -176,46 +160,117 @@ if [ "${#TO_DELETE[@]}" -eq 0 ]; then
 fi

 echo ""
-echo "=== Phase 4: whiteout deletion ==="
-echo "Creating whiteout tar for ${#TO_DELETE[@]} report(s)..."
+echo "=== Phase 4: full site rebuild ==="
+echo "Rebuilding site (${#TO_DELETE[@]} report(s) to delete)..."

-WHITEOUT_TAR=$(mktemp)
-trap 'rm -f "$WHITEOUT_TAR"' EXIT
+ARCHIVE_FILE=$(mktemp)
+SITE_DIR=$(mktemp -d)
+NEW_TAR=$(mktemp)
+cleanup_phase4() {
+  rm -f "$ARCHIVE_FILE" "$NEW_TAR"
+  rm -rf "$SITE_DIR"
+}
+trap cleanup_phase4 EXIT

-python3 -c "
-import tarfile, sys
+# Try archive.tar first
+echo "Downloading archive.tar..."
+HTTP_CODE=$(curl_with_host -o "$ARCHIVE_FILE" -w "%{http_code}" -sS "${PAGES_URL}/.git-pages/archive.tar")

-tar = tarfile.open(name='${WHITEOUT_TAR}', mode='w')
+if [ "$HTTP_CODE" = "200" ] && tar -tf "$ARCHIVE_FILE" >/dev/null 2>&1; then
+  OLD_KB=$(du -sk "$ARCHIVE_FILE" 2>/dev/null | awk '{print $1}')
+  echo "Extracting archive (${OLD_KB}kB)..."
+  tar -xf "$ARCHIVE_FILE" -C "$SITE_DIR"

-dirs = set()
-for d in sys.argv[1:]:
-    dirs.add(d.strip())
+  declare -A GROUP_SEEN
+  declare -A GROUP_LINES
+  for del in "${TO_DELETE[@]}"; do
+    if [ ! -d "$SITE_DIR/$del" ]; then
+      continue
+    fi

-tarinfo = tarfile.TarInfo()
-tarinfo.type = tarfile.CHRTYPE
-tarinfo.devmajor = 0
-tarinfo.devminor = 0
+    commit_dir=$(dirname "$del")
+    branch="${COMMIT_BRANCH_MAP[$commit_dir]:-?}"
+    reason="${REASON_MAP[$del]:-?}"
+    repo_path="${del%%/reports/*}"
+    commit_hash="${commit_dir##*/}"
+    key="${repo_path}/${branch} | Reason: ${reason}"
+    seen_key="${key}|${commit_hash}"

-for d in sorted(dirs, key=len, reverse=True):
-    info = tarinfo
-    info.name = d
-    tar.addfile(info)
+    if [ -z "${GROUP_SEEN[$seen_key]:-}" ]; then
+      GROUP_SEEN[$seen_key]=1
+      GROUP_LINES["$key"]="${GROUP_LINES[$key]:-} $commit_hash"
+    fi

-tar.close()
-" "${TO_DELETE[@]}"
+    rm -rf "$SITE_DIR/$del"
+  done
+  for key in "${!GROUP_LINES[@]}"; do
+    echo "  Removing: ${key}"
+    for hash in ${GROUP_LINES[$key]}; do
+      echo "    commit: ${hash}"
+    done
+  done
+else
+  echo "archive.tar failed (HTTP ${HTTP_CODE}) - falling back to manifest-based rebuild"

-echo "Patching ${PAGES_URL}/ with whiteout tar..."
-HTTP_CODE=$(curl_with_host -X PATCH "${PAGES_URL}/" \
+  ALL_PATHS=$(echo "$MANIFEST" | jq -r '.contents | keys[]' 2>/dev/null || true)
+
+  if [ -z "$ALL_PATHS" ]; then
+    echo "ERROR: no files in manifest - cannot rebuild" >&2
+    exit 1
+  fi
+
+  EXCLUDE_GREP=""
+  for dir in "${TO_DELETE[@]}"; do
+    EXCLUDE_GREP="${EXCLUDE_GREP}${EXCLUDE_GREP:+|}^${dir}/"
+  done
+
+  if [ -n "$EXCLUDE_GREP" ]; then
+    KEEP_PATHS=$(echo "$ALL_PATHS" | grep -v -E "$EXCLUDE_GREP" || true)
+  else
+    KEEP_PATHS="$ALL_PATHS"
+  fi
+
+  if [ -z "$KEEP_PATHS" ]; then
+    echo "No files to keep - site will be empty"
+    mkdir -p "$SITE_DIR/__placeholder__"
+    echo "placeholder" > "$SITE_DIR/__placeholder__/index.html"
+  else
+    FILE_COUNT=$(echo "$KEEP_PATHS" | wc -l | tr -d ' ')
+    echo "Downloading ${FILE_COUNT} file(s)..."
+    while IFS= read -r path; do
+      [ -z "$path" ] && continue
+      dir=$(dirname "$SITE_DIR/$path")
+      mkdir -p "$dir"
+      curl_with_host -o "$SITE_DIR/$path" -sS "${PAGES_URL}/${path}" || {
+        echo "  WARN: failed to download ${path}"
+      }
+    done <<< "$KEEP_PATHS"
+  fi
+fi
+
+if [ -z "$(ls -A "$SITE_DIR" 2>/dev/null)" ]; then
+  echo "Site is empty - creating placeholder"
+  mkdir -p "$SITE_DIR/__placeholder__"
+  echo "placeholder" > "$SITE_DIR/__placeholder__/index.html"
+fi
+
+tar -cf "$NEW_TAR" -C "$SITE_DIR" .
+NEW_KB=$(du -sk "$NEW_TAR" 2>/dev/null | awk '{print $1}')
+
+echo "PUT: replacing site contents..."
+HTTP_CODE=$(curl_with_host -X PUT "${PAGES_URL}/" \
  -H "Content-Type: application/x-tar" \
-  -H "Atomic: no" \
-  --data-binary @"${WHITEOUT_TAR}" \
+  --data-binary @"${NEW_TAR}" \
  -w "%{http_code}" \
  -o /dev/null)

-echo "HTTP $HTTP_CODE"
-if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "204" ]; then
-  echo "Retention cleanup finished."
+echo "HTTP ${HTTP_CODE}"
+if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "204" ]; then
+  echo "Site rebuild completed."
+  if [ -n "${OLD_KB:-}" ]; then
+    echo "  archive size: $(fmt_num $OLD_KB)kB → $(fmt_num $NEW_KB)kB"
+  fi
 else
-  echo "ERROR: retention HTTP ${HTTP_CODE}" >&2
+  echo "ERROR: PUT HTTP ${HTTP_CODE}" >&2
  exit 1
 fi
@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Shared functions for retention-cleanup.sh
+# Can be sourced by tests for unit testing
+
+age_days() {
+  local published="$1" epoch_pub now
+  epoch_pub=$(date -d "$published" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$published" +%s 2>/dev/null || echo 0)
+  [ "$epoch_pub" -eq 0 ] && echo 99999 && return
+  now=$(date -u +%s)
+  echo $(( (now - epoch_pub) / 86400 ))
+}
+
+parse_path() {
+  local rel="$1"
+  OWNER="${rel%%/*}"
+  rest="${rel#*/}"
+  REPO="${rest%%/*}"
+}
+
+read_rule() {
+  local config="$1" branch="$2" key="$3" default="$4"
+  v=$(jq -r --arg b "$branch" --arg k "$key" '.branches[$b][$k] // empty' "$config")
+  [ -n "$v" ] && echo "$v" || echo "$default"
+}
+
+# ---------------------------------------------------------------------------
+# Gitea branch/repo checking via git ls-remote
+# Uses global: GITEA_API_URL, GITEA_TOKEN
+# Sets global: REPO_BRANCHES_CACHE, REPO_STATUS
+# ---------------------------------------------------------------------------
+
+# Fetch all branches for a repo (one git ls-remote call per repo).
+# Sets REPO_STATUS[owner/repo].
+# Echos branch list on success.
+# Returns: 0=ok, 1=deleted, 2=cert_error, 3=error (fail-safe keep)
+repo_branches() {
+  local owner="$1" repo="$2" key="${owner}/${repo}"
+  local attempt output
+
+  [ -z "$GITEA_API_URL" ] && return 0
+  [ -z "$GITEA_TOKEN" ] && return 0
+
+  # Check cached status first (avoids re-running git on every report)
+  case "${REPO_STATUS[$key]:-}" in
+    deleted)    return 1 ;;
+    cert_error) return 2 ;;
+    error)      echo "${REPO_BRANCHES_CACHE[$key]:-}"; return 3 ;;
+  esac
+
+  # Cache hit (success with branch list)
+  [ -n "${REPO_BRANCHES_CACHE[$key]:-}" ] && { echo "${REPO_BRANCHES_CACHE[$key]}"; return 0; }
+
+  local git_host
+  git_host=$(echo "$GITEA_API_URL" | sed -E 's|^https?://||' | sed 's|/.*$||')
+  local git_url="https://token:${GITEA_TOKEN}@${git_host}/${owner}/${repo}.git"
+
+  for attempt in 1 2 3; do
+    output=$(git ls-remote --heads "$git_url" 2>&1) && {
+      local branches
+      branches=$(echo "$output" | sed -n 's|.*refs/heads/||p')
+      REPO_BRANCHES_CACHE[$key]="$branches"
+      REPO_STATUS[$key]="ok"
+      echo "$branches"
+      return 0
+    }
+
+    # Repo deleted → no retry
+    if echo "$output" | grep -qiE "fatal:.*(not found|repository.*not|could not read)"; then
+      REPO_BRANCHES_CACHE[$key]="__REPO_DELETED__"
+      REPO_STATUS[$key]="deleted"
+      echo "  REPO DELETED: ${owner}/${repo}" >&2
+      return 1
+    fi
+
+    [ "$attempt" -lt 3 ] && sleep 10
+  done
+
+  # Certificate verification failure → configuration error, stop
+  if echo "$output" | grep -qi "server certificate verification failed"; then
+    REPO_STATUS[$key]="cert_error"
+    echo "[ERROR] git-pages.retention: certificate verification failed for ${owner}/${repo}" >&2
+    echo "[ERROR] git-pages.retention:   check CA certificates or set GIT_SSL_NO_VERIFY=1" >&2
+    echo "[ERROR] git-pages.retention:   git output:" >&2
+    echo "$output" >&2
+    return 2
+  fi
+
+  # Other network errors → fail-safe keep, continue
+  REPO_BRANCHES_CACHE[$key]="__REPO_ERROR__"
+  REPO_STATUS[$key]="error"
+  echo "[WARN] git-pages.retention: cannot reach Gitea for ${owner}/${repo} — keeping all reports" >&2
+  echo "[WARN] git-pages.retention:   git output:" >&2
+  echo "$output" >&2
+  return 3
+}
+
+# Check if a specific branch exists in a repo.
+# Returns 0 (exists), 1 (not found/deleted).
+# Returns 2 (cert error), 3 (network error).
+branch_exists() {
+  local owner="$1" repo="$2" branch="$3"
+  local branches rc
+
+  [ -z "$GITEA_API_URL" ] && return 0
+  [ -z "$GITEA_TOKEN" ] && return 0
+
+  branches=$(repo_branches "$owner" "$repo")
+  rc=$?
+
+  # Return codes from repo_branches propagate through $() subshell:
+  # 0=ok, 1=deleted, 2=cert_error, 3=error
+  case $rc in
+    2) echo "[FATAL] git-pages.retention: cannot reach Gitea (${owner}/${repo}) — check configuration" >&2
+       exit 1 ;;
+    3) return 0 ;;  # network error → fail-safe keep
+    1) return 1 ;;  # repo/branch gone
+  esac
+
+  echo "$branches" | grep -qxF "$branch"
+}
+
+# Phase 3: apply retention rules to KEEP array, populate TO_DELETE
+# Reads from global KEEP array
+# Populates global TO_DELETE array
+# Usage: apply_retention <config_path>
+apply_retention() {
+  local config="$1"
+  local default_max_age default_keep_min
+  local max_age keep_min key count seen_key commit_dir
+  local entry dir owner repo branch days
+
+  default_max_age=$(jq -r '.branches.default.maxAgeDays // 90' "$config")
+  default_keep_min=$(jq -r '.branches.default.keepMin // 5' "$config")
+
+  declare -A BRANCH_COUNTS
+  declare -A SEEN_COMMITS
+  declare -A DELETED_COMMITS
+
+  if [ "${#KEEP[@]}" -eq 0 ]; then
+    return
+  fi
+
+  IFS=$'\n'
+  for entry in $(printf '%s\n' "${KEEP[@]}" | sort -t'|' -k4,4 -k5,5n); do
+    IFS='|' read -r dir owner repo branch days <<< "$entry"
+
+    max_age=$(read_rule "$config" "$branch" "maxAgeDays" "$default_max_age")
+    keep_min=$(read_rule "$config" "$branch" "keepMin" "$default_keep_min")
+
+    # Age check — per-report-type deletion
+    if [ "$days" -gt "$max_age" ]; then
+      echo "  DELETE: ${dir} (age ${days}d > maxAge ${max_age}d, branch ${branch})"
+      TO_DELETE+=("$dir")
+      REASON_MAP["$dir"]="maxAgeDays exceed"
+      MAXAGE_DELETED=$((MAXAGE_DELETED + 1))
+      continue
+    fi
+
+    # keepMin — per-commit counting
+    commit_dir=$(dirname "$dir")
+    key="$branch"
+    seen_key="${key}|${commit_dir}"
+
+    if [ -z "${SEEN_COMMITS[$seen_key]:-}" ]; then
+      SEEN_COMMITS["$seen_key"]=1
+      count="${BRANCH_COUNTS[$key]:-0}"
+      count=$((count + 1))
+      BRANCH_COUNTS["$key"]=$count
+    else
+      count="${BRANCH_COUNTS[$key]:-0}"
+    fi
+
+    if [ "$count" -gt "$keep_min" ]; then
+      if [ -z "${DELETED_COMMITS[$commit_dir]:-}" ]; then
+        DELETED_COMMITS[$commit_dir]=1
+        echo "  DELETE: ${commit_dir} (kept ${keep_min}/${count} commits, exceeds keepMin, branch ${branch})"
+        TO_DELETE+=("$commit_dir")
+        REASON_MAP["$commit_dir"]="keepMin exceed"
+        KEEPMIN_DELETED=$((KEEPMIN_DELETED + 1))
+      fi
+    fi
+  done
+  unset IFS
+}
@@ -70,8 +70,15 @@ spec:
              set -euo pipefail
              echo "Retention sidecar: installing deps..."
              apt-get update -qq
-              apt-get install -y --no-install-recommends curl jq python3 >/dev/null
+              apt-get install -y --no-install-recommends curl jq git ca-certificates >/dev/null
              echo "Retention sidecar: ready"
+              # Sleep until 01:00 so retention runs at night
+              now_epoch=$(date +%s)
+              target_epoch=$(date -d "today 01:00:00" +%s)
+              [ "$target_epoch" -le "$now_epoch" ] && target_epoch=$((target_epoch + 86400))
+              sleep_sec=$((target_epoch - now_epoch))
+              echo "Retention sidecar: next run in $((sleep_sec / 3600))h (at 01:00)"
+              sleep $sleep_sec
              while true; do
                /scripts/retention-cleanup.sh
                echo "Retention sidecar: next run in 24h"
@@ -6,7 +6,7 @@ metadata:
  labels:
    {{- include "git-pages.componentLabels" . | nindent 4 }}
  annotations:
-    "helm.sh/hook": post-install, post-upgrade
+    "helm.sh/hook": post-install
    "helm.sh/hook-delete-policy": hook-succeeded,before-hook-creation
 spec:
  backoffLimit: 5
@@ -32,6 +32,16 @@ spec:
                -H "Host: {{ .Values.ingress.host }}" \
                -o /dev/null "http://git-pages:3000/.git-pages/health"
              do sleep 2; done
+              echo "Init: checking if site already exists..."
+              MANIFEST=$(curl -sf \
+                -H "Host: {{ .Values.ingress.host }}" \
+                "http://git-pages:3000/.git-pages/manifest.json" 2>/dev/null || echo "")
+
+              if echo "$MANIFEST" | grep -q '"contents"'; then
+                echo "Init: site already initialized, skipping"
+                exit 0
+              fi
+
              echo "Init: creating placeholder site..."
              WORK=$(mktemp -d)
              mkdir -p "$WORK/__init__"
@@ -8,6 +8,8 @@ metadata:
 data:
  retention.json: |
    {{- .Values.retention.rules | toJson | nindent 4 }}
+  retention-lib.sh: |
+    {{- .Files.Get "files/retention-lib.sh" | nindent 4 }}
  retention-cleanup.sh: |
    {{- .Files.Get "files/retention-cleanup.sh" | nindent 4 }}
  retention-run.sh: |
@@ -33,7 +33,7 @@ spec:
                - |
                  set -euo pipefail
                  apt-get update -qq
-                  apt-get install -y --no-install-recommends curl jq >/dev/null
+                  apt-get install -y --no-install-recommends curl jq git >/dev/null
                  chmod +x /scripts/retention-run.sh /scripts/retention-cleanup.sh
                  /scripts/retention-run.sh
              env:
@@ -0,0 +1,623 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "$(dirname "$BATS_TEST_DIRNAME")/files/retention-lib.sh"
+  declare -gA REPO_BRANCHES_CACHE
+  declare -gA REPO_STATUS
+  declare -gA REASON_MAP
+  MAXAGE_DELETED=0
+  KEEPMIN_DELETED=0
+  CONFIG=$(mktemp)
+}
+
+teardown() {
+  rm -f "$CONFIG"
+}
+
+write_config() {
+  cat > "$CONFIG"
+}
+
+# ---------------------------------------------------------------------------
+# read_rule
+# ---------------------------------------------------------------------------
+
+@test "read_rule returns default when branch has no override" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":5}}}
+EOF
+  result=$(read_rule "$CONFIG" "nonexistent" "maxAgeDays" 90)
+  [ "$result" = "90" ]
+}
+
+@test "read_rule returns branch-specific value" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":5},"main":{"maxAgeDays":365,"keepMin":20}}}
+EOF
+  result=$(read_rule "$CONFIG" "main" "keepMin" 5)
+  [ "$result" = "20" ]
+}
+
+@test "read_rule returns default for undefined key even if branch exists" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":5},"main":{"maxAgeDays":365}}}
+EOF
+  result=$(read_rule "$CONFIG" "main" "keepMin" 5)
+  [ "$result" = "5" ]
+}
+
+# ---------------------------------------------------------------------------
+# parse_path
+# ---------------------------------------------------------------------------
+
+@test "parse_path extracts owner and repo" {
+  parse_path "my-owner/my-repo/reports/abc123/go-test-unit"
+  [ "$OWNER" = "my-owner" ]
+  [ "$REPO" = "my-repo" ]
+}
+
+@test "parse_path handles owner with hyphens" {
+  parse_path "niko/agent-platform/reports/abc1234/go-test-bdd"
+  [ "$OWNER" = "niko" ]
+  [ "$REPO" = "agent-platform" ]
+}
+
+# ---------------------------------------------------------------------------
+# apply_retention — keepMin per commit
+# ---------------------------------------------------------------------------
+
+@test "keepMin: 6 commits × 4 types, keepMin=10 → all kept (6 commits < 10)" {
+  # With old per-file counting, 24 files > 10 keepMin would delete 14.
+  # With per-commit counting, 6 commits < 10 keepMin keeps everything.
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":365,"keepMin":10}}}
+EOF
+
+  KEEP=()
+  local -a commits=(c1 c2 c3 c4 c5 c6)
+  local -a ages=(100 80 60 40 20 5)
+  local -a types=(go-test-bdd go-test-unit helm-lint helm-kubeconform)
+  for i in "${!commits[@]}"; do
+    for t in "${types[@]}"; do
+      KEEP+=("niko/agent-platform/reports/${commits[$i]}/$t|niko|agent-platform|main|${ages[$i]}")
+    done
+  done
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  [ "${#TO_DELETE[@]}" -eq 0 ]
+}
+
+@test "keepMin: 8 commits × 1 type, keepMin=5 → deletes 3 oldest" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":365,"keepMin":5}}}
+EOF
+
+  KEEP=()
+  local -a ages=(80 70 60 50 40 30 20 10)
+  for i in "${!ages[@]}"; do
+    KEEP+=("niko/r/reports/c$((i+1))/test|niko|r|main|${ages[$i]}")
+  done
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # 5 newest (c8-c4) kept, 3 oldest (c3,c2,c1) deleted
+  [ "${#TO_DELETE[@]}" -eq 3 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/c3" ]]
+  [[ "${TO_DELETE[1]}" == "niko/r/reports/c2" ]]
+  [[ "${TO_DELETE[2]}" == "niko/r/reports/c1" ]]
+}
+
+@test "keepMin: 12 commits × 1 type, keepMin=5 → keeps 5 newest, deletes 7 oldest" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":5}}}
+EOF
+
+  KEEP=()
+  for i in $(seq 1 12); do
+    KEEP+=("niko/r/reports/c${i}/test|niko|r|feature/foo|$(( 13 - i ))")
+  done
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # 7 oldest commits deleted (12 - 5 = 7)
+  [ "${#TO_DELETE[@]}" -eq 7 ]
+  # Oldest 7 should be c1..c7 (highest days = oldest = processed last after sort)
+  # Sort is ascending by days, so processed as c12(1d), c11(2d), ..., c1(12d)
+  # keepMin=5: c12-c8 kept, c7-c1 deleted
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/c7" ]]
+  [[ "${TO_DELETE[6]}" == "niko/r/reports/c1" ]]
+}
+
+@test "keepMin: 2 commits × 3 types, keepMin=5 → all kept (2 < 5)" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":5}}}
+EOF
+
+  KEEP=()
+  KEEP+=("niko/r/reports/c1/test-a|niko|r|main|30")
+  KEEP+=("niko/r/reports/c1/test-b|niko|r|main|30")
+  KEEP+=("niko/r/reports/c1/test-c|niko|r|main|30")
+  KEEP+=("niko/r/reports/c2/test-a|niko|r|main|10")
+  KEEP+=("niko/r/reports/c2/test-b|niko|r|main|10")
+  KEEP+=("niko/r/reports/c2/test-c|niko|r|main|10")
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  [ "${#TO_DELETE[@]}" -eq 0 ]
+}
+
+@test "keepMin: 6 commits × 2 types, keepMin=3 → keeps 3 newest, deletes 3 oldest" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":365,"keepMin":3}}}
+EOF
+
+  KEEP=()
+  local -a commits=(c1 c2 c3 c4 c5 c6)
+  local -a ages=(60 50 40 30 20 10)
+  local -a types=(jest pytest)
+  for i in "${!commits[@]}"; do
+    for t in "${types[@]}"; do
+      KEEP+=("niko/r/reports/${commits[$i]}/$t|niko|r|feature/x|${ages[$i]}")
+    done
+  done
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # Sort by days ascending: c6(10d), c5(20d), c4(30d), c3(40d), c2(50d), c1(60d)
+  # keepMin=3: c6,c5,c4 kept; c3,c2,c1 deleted
+  [ "${#TO_DELETE[@]}" -eq 3 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/c3" ]]
+  [[ "${TO_DELETE[1]}" == "niko/r/reports/c2" ]]
+  [[ "${TO_DELETE[2]}" == "niko/r/reports/c1" ]]
+}
+
+# ---------------------------------------------------------------------------
+# apply_retention — maxAge
+# ---------------------------------------------------------------------------
+
+@test "maxAge: report exceeding maxAge is deleted" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":5}}}
+EOF
+
+  KEEP=(
+    "niko/r/reports/c1/test|niko|r|main|100"
+    "niko/r/reports/c2/test|niko|r|main|50"
+  )
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # c1 (100d) > 90, deleted; c2 (50d) < 90, kept
+  [ "${#TO_DELETE[@]}" -eq 1 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/c1/test" ]]
+}
+
+@test "maxAge deletes report-level dir, not commit-level" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":30,"keepMin":5}}}
+EOF
+
+  KEEP=(
+    "niko/r/reports/c1/test-a|niko|r|main|100"
+    "niko/r/reports/c1/test-b|niko|r|main|20"
+    "niko/r/reports/c2/test-a|niko|r|main|10"
+  )
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # Only test-a for c1 is old; test-b for c1 is young, c2 is young
+  [ "${#TO_DELETE[@]}" -eq 1 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/c1/test-a" ]]
+}
+
+# ---------------------------------------------------------------------------
+# apply_retention — maxAge + keepMin interaction
+# ---------------------------------------------------------------------------
+
+@test "maxAge takes precedence over keepMin — aged report deleted, not counted in keepMin" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":30,"keepMin":2}}}
+EOF
+
+  # 3 commits, 1 type each. c1 is old (100d), c2 and c3 are young.
+  # With keepMin=2: c1 should be deleted by maxAge, c2 and c3 kept.
+  # Without the continue after maxAge check, c1 would consume a keepMin slot.
+  KEEP=(
+    "niko/r/reports/c1/test|niko|r|main|100"
+    "niko/r/reports/c2/test|niko|r|main|10"
+    "niko/r/reports/c3/test|niko|r|main|5"
+  )
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # c1 deleted by maxAge, c2 and c3 within keepMin=2
+  [ "${#TO_DELETE[@]}" -eq 1 ]
+}
+
+# ---------------------------------------------------------------------------
+# apply_retention — sorting (newest first)
+# ---------------------------------------------------------------------------
+
+@test "sort order: newest commits processed first within same branch" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":365,"keepMin":2}}}
+EOF
+
+  KEEP=(
+    "niko/r/reports/c1/test|niko|r|main|100"
+    "niko/r/reports/c2/test|niko|r|main|50"
+    "niko/r/reports/c3/test|niko|r|main|10"
+  )
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # Sort by days ascending: c3(10d) 1st, c2(50d) 2nd, c1(100d) 3rd
+  # keepMin=2: c3 and c2 kept, c1 deleted
+  [ "${#TO_DELETE[@]}" -eq 1 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/c1" ]]
+}
+
+@test "sort order: branches sorted alphabetically" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":365,"keepMin":1}}}
+EOF
+
+  KEEP=(
+    "niko/r/reports/c1/test|niko|r|z-branch|50"
+    "niko/r/reports/c2/test|niko|r|a-branch|60"
+    "niko/r/reports/c3/test|niko|r|m-branch|10"
+  )
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+
+  # Alphabetical: a-branch, m-branch, z-branch
+  # Each has 1 commit, keepMin=1 → nothing deleted
+  [ "${#TO_DELETE[@]}" -eq 0 ]
+}
+
+@test "multi-branch: each branch has own keepMin counter" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":2}}}
+EOF
+
+  KEEP=(
+    "niko/r/reports/c1/test|niko|r|branch-a|30"
+    "niko/r/reports/c2/test|niko|r|branch-a|20"
+    "niko/r/reports/c3/test|niko|r|branch-a|10"
+    "niko/r/reports/c4/test|niko|r|branch-b|60"
+    "niko/r/reports/c5/test|niko|r|branch-b|50"
+    "niko/r/reports/c6/test|niko|r|branch-b|40"
+    "niko/r/reports/c7/test|niko|r|branch-b|30"
+  )
+
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+ 
+  # branch-a: 3 reports → keep 2 newest (c2,c3), delete 1 oldest (c1)
+  # branch-b: 4 reports → keep 2 newest (c6,c7), delete 2 oldest (c4,c5)
+  # Actually: Sort is by branch, then by days ascending
+  # branch-a processed first: c3(10d) 1st, c2(20d) 2nd (keep), c1(30d) 3rd (delete)
+  # branch-b processed next: c7(30d) 1st, c6(40d) 2nd (keep), c5(50d) 3rd (delete), c4(60d) 4th (delete)
+  [ "${#TO_DELETE[@]}" -eq 3 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/c1" ]]
+  [[ "${TO_DELETE[1]}" == "niko/r/reports/c5" ]]
+  [[ "${TO_DELETE[2]}" == "niko/r/reports/c4" ]]
+}
+
+# ---------------------------------------------------------------------------
+# apply_retention — empty / edge cases
+# ---------------------------------------------------------------------------
+
+@test "empty KEEP array → nothing deleted" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":90,"keepMin":5}}}
+EOF
+
+  KEEP=()
+  TO_DELETE=()
+  apply_retention "$CONFIG"
+  [ "${#TO_DELETE[@]}" -eq 0 ]
+}
+
+@test "TO_DELETE preserves Phase 2 entries after apply_retention (no new deletions)" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":365,"keepMin":10}}}
+EOF
+
+  KEEP=(
+    "niko/r/reports/c1/test|niko|r|main|10"
+    "niko/r/reports/c2/test|niko|r|main|5"
+  )
+  TO_DELETE=(
+    "niko/r/reports/abc/branch-gone"
+    "niko/r/reports/def/repo-gone"
+  )
+
+  apply_retention "$CONFIG"
+
+  [ "${#TO_DELETE[@]}" -eq 2 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/abc/branch-gone" ]]
+  [[ "${TO_DELETE[1]}" == "niko/r/reports/def/repo-gone" ]]
+}
+
+@test "TO_DELETE preserves Phase 2 entries AND adds retention deletions" {
+  write_config <<'EOF'
+{"branches":{"default":{"maxAgeDays":365,"keepMin":3}}}
+EOF
+
+  KEEP=(
+    "niko/r/reports/c1/test|niko|r|main|40"
+    "niko/r/reports/c2/test|niko|r|main|30"
+    "niko/r/reports/c3/test|niko|r|main|20"
+    "niko/r/reports/c4/test|niko|r|main|10"
+  )
+  TO_DELETE=(
+    "niko/r/reports/abc/branch-gone"
+  )
+
+  apply_retention "$CONFIG"
+
+  # 1 pre-existing + 1 commit deleted (c1, oldest of 4, keepMin=3)
+  [ "${#TO_DELETE[@]}" -eq 2 ]
+  [[ "${TO_DELETE[0]}" == "niko/r/reports/abc/branch-gone" ]]
+}
+
+# ---------------------------------------------------------------------------
+# branch_exists — mocking REPO_STATUS / REPO_BRANCHES_CACHE
+# ---------------------------------------------------------------------------
+
+@test "branch_exists: branch in list → return 0" {
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test-token"
+
+  REPO_BRANCHES_CACHE["owner/repo"]=$'main\nfeature/x'
+  REPO_STATUS["owner/repo"]="ok"
+
+  run branch_exists "owner" "repo" "main"
+  [ "$status" -eq 0 ]
+}
+
+@test "branch_exists: branch not in list → return 1" {
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test-token"
+
+  REPO_BRANCHES_CACHE["owner/repo"]=$'main\nfeature/x'
+  REPO_STATUS["owner/repo"]="ok"
+
+  run branch_exists "owner" "repo" "nonexistent"
+  [ "$status" -eq 1 ]
+}
+
+@test "branch_exists: cert error → exit 1 with [FATAL]" {
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test"
+
+  REPO_STATUS["owner/repo"]="cert_error"
+
+  run branch_exists "owner" "repo" "any-branch"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"[FATAL]"* ]]
+}
+
+@test "branch_exists: repo deleted → return 1" {
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test-token"
+
+  REPO_BRANCHES_CACHE["owner/repo"]="__REPO_DELETED__"
+  REPO_STATUS["owner/repo"]="deleted"
+
+  run branch_exists "owner" "repo" "any-branch"
+  [ "$status" -eq 1 ]
+}
+
+@test "branch_exists: network error → return 0 (fail-safe keep)" {
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test-token"
+
+  REPO_BRANCHES_CACHE["owner/repo"]="__REPO_ERROR__"
+  REPO_STATUS["owner/repo"]="error"
+
+  run branch_exists "owner" "repo" "any-branch"
+  [ "$status" -eq 0 ]
+}
+
+@test "branch_exists: empty GITEA_API_URL → return 0 (skip)" {
+  GITEA_API_URL=""
+  GITEA_TOKEN="test-token"
+
+  run branch_exists "owner" "repo" "any-branch"
+  [ "$status" -eq 0 ]
+}
+
+@test "branch_exists: empty GITEA_TOKEN → return 0 (skip)" {
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN=""
+
+  run branch_exists "owner" "repo" "any-branch"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# repo_branches — git ls-remote error detection patterns
+# ---------------------------------------------------------------------------
+
+@test "error detection: 'command not found' does NOT trigger repo deleted" {
+  # This must NOT match — "bash: git: command not found" is NOT a repo deletion
+  local msg="bash: git: command not found"
+  run grep -qiE "fatal:.*(not found|repository.*not|could not read)" <<< "$msg"
+  [ "$status" -eq 1 ]
+}
+
+@test "error detection: 'fatal: repo not found' triggers repo deleted" {
+  # This MUST match — genuine git error for deleted/missing repo
+  local msg="fatal: repository 'https://gitea.app/owner/repo.git' not found"
+  run grep -qiE "fatal:.*(not found|repository.*not|could not read)" <<< "$msg"
+  [ "$status" -eq 0 ]
+}
+
+@test "error detection: 'could not read from remote' triggers repo deleted" {
+  local msg="fatal: could not read from remote repository"
+  run grep -qiE "fatal:.*(not found|repository.*not|could not read)" <<< "$msg"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# git ls-remote integration (real git, temp repo)
+# ---------------------------------------------------------------------------
+
+@test "git ls-remote parsing: lists branches correctly" {
+  local tmpdir=$(mktemp -d)
+
+  git -C "$tmpdir" init -b main source >/dev/null 2>&1
+  git -C "$tmpdir/source" config user.email "test@test"
+  git -C "$tmpdir/source" config user.name "test"
+  git -C "$tmpdir/source" commit --allow-empty -m "init" >/dev/null 2>&1
+  git -C "$tmpdir/source" branch feature/x >/dev/null 2>&1
+  git clone --bare "$tmpdir/source" "$tmpdir/repo.git" >/dev/null 2>&1
+
+  local url="file://$tmpdir/repo.git"
+  local output
+  output=$(git ls-remote --heads "$url" 2>&1)
+  local branches
+  branches=$(echo "$output" | sed -n 's|.*refs/heads/||p')
+
+  echo "$branches" | grep -qxF "main"
+  [ "$?" -eq 0 ]
+
+  echo "$branches" | grep -qxF "feature/x"
+  [ "$?" -eq 0 ]
+
+  ! echo "$branches" | grep -qxF "nonexistent"
+
+  rm -rf "$tmpdir"
+}
+
+# ---------------------------------------------------------------------------
+# repo_branches — retry + error output (using git mock)
+# ---------------------------------------------------------------------------
+
+@test "repo_branches: success returns branches immediately" {
+  local mockdir=$(mktemp -d)
+  cat > "$mockdir/git" << 'SCRIPT'
+#!/usr/bin/env bash
+echo "abc123	refs/heads/main"
+echo "def456	refs/heads/feature/x"
+SCRIPT
+  chmod +x "$mockdir/git"
+  local save_PATH="$PATH"
+  export PATH="$mockdir:$PATH"
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test"
+  REPO_BRANCHES_CACHE=()
+  REPO_STATUS=()
+
+  run repo_branches "owner" "repo"
+
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"main"* ]]
+  [[ "$output" == *"feature/x"* ]]
+
+  export PATH="$save_PATH"
+  rm -rf "$mockdir"
+}
+
+@test "repo_branches: retries 3 times on transient error" {
+  local mockdir=$(mktemp -d)
+  cat > "$mockdir/git" << 'SCRIPT'
+#!/usr/bin/env bash
+echo "call" >> "$MOCKDIR/count"
+echo "fatal: unable to access 'https://...'" >&2
+exit 1
+SCRIPT
+  chmod +x "$mockdir/git"
+  # Inject mockdir path into mock script via env var
+  sed -i '' "s|\$MOCKDIR|$mockdir|g" "$mockdir/git"
+  local save_PATH="$PATH"
+  export PATH="$mockdir:$PATH"
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test"
+  REPO_BRANCHES_CACHE=()
+  REPO_STATUS=()
+
+  local start=$SECONDS
+  run repo_branches "owner" "repo"
+
+  [ "$status" -eq 3 ]
+  [[ "$output" == *"[WARN] git-pages.retention"* ]]
+  [[ "$output" == *"keeping all reports"* ]]
+  [[ "$output" == *"git output:"* ]]
+  [[ "$output" == *"unable to access"* ]]
+  [ $(cat "$mockdir/count" | wc -l) -eq 3 ]
+  [ $(( SECONDS - start )) -ge 18 ]
+
+  export PATH="$save_PATH"
+  rm -rf "$mockdir"
+}
+
+@test "repo_branches: certificate error → [ERROR] + return 1" {
+  local mockdir=$(mktemp -d)
+  cat > "$mockdir/git" << 'SCRIPT'
+#!/usr/bin/env bash
+echo "call" >> "$MOCKDIR/count"
+echo "fatal: unable to access 'https://gitea.app/owner/repo.git/': server certificate verification failed. CAfile: none CRLfile: none" >&2
+exit 1
+SCRIPT
+  chmod +x "$mockdir/git"
+  sed -i '' "s|\$MOCKDIR|$mockdir|g" "$mockdir/git"
+  local save_PATH="$PATH"
+  export PATH="$mockdir:$PATH"
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test"
+  REPO_BRANCHES_CACHE=()
+  REPO_STATUS=()
+
+  run repo_branches "owner" "repo"
+
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"[ERROR]"* ]]
+  [[ "$output" == *"certificate verification"* ]]
+  [[ "$output" == *"git output:"* ]]
+  [[ "$output" == *"unable to access"* ]]
+
+  export PATH="$save_PATH"
+  rm -rf "$mockdir"
+}
+
+@test "repo_branches: repo not found returns immediately (no retry)" {
+  local mockdir=$(mktemp -d)
+  cat > "$mockdir/git" << 'SCRIPT'
+#!/usr/bin/env bash
+echo "call" >> "$MOCKDIR/count"
+echo "fatal: repository 'https://gitea.app/owner/repo.git' not found" >&2
+exit 1
+SCRIPT
+  chmod +x "$mockdir/git"
+  sed -i '' "s|\$MOCKDIR|$mockdir|g" "$mockdir/git"
+  local save_PATH="$PATH"
+  export PATH="$mockdir:$PATH"
+  GITEA_API_URL="https://gitea.example.com"
+  GITEA_TOKEN="test"
+  REPO_BRANCHES_CACHE=()
+  REPO_STATUS=()
+
+  run repo_branches "owner" "repo"
+
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"REPO DELETED"* ]]
+  [[ "$output" != *"[WARN]"* ]]
+  [ $(cat "$mockdir/count" | wc -l) -eq 1 ]
+
+  export PATH="$save_PATH"
+  rm -rf "$mockdir"
+}
@@ -17,6 +17,11 @@ POLL_INTERVAL="${DISPATCH_POLL_INTERVAL:-10}"
 [ -z "$GITEA_API_URL" ] && echo "ERROR: gitea_api_url argument is required" >&2 && exit 1
 [ -z "$GITEA_TOKEN" ] && echo "ERROR: gitea_token argument is required" >&2 && exit 1

+# Generate unique dispatch_id for display_title matching
+# Can be overridden via DISPATCH_ID env var (for tests)
+DISPATCH_ID="${DISPATCH_ID:-$(xxd -l 4 -p /dev/urandom 2>/dev/null || openssl rand -hex 4 2>/dev/null || od -An -N4 -tx1 /dev/urandom | tr -d ' \n')}"
+INPUTS_JSON=$(echo "$INPUTS_JSON" | jq --arg id "$DISPATCH_ID" '. + {dispatch_id: $id}')
+
 DISPATCH_URL="$GITEA_API_URL/api/v1/repos/$TARGET_REPO/actions/workflows/$WORKFLOW_FILE/dispatches"
 DISPATCH_BODY=$(jq -nc --arg ref "$REF" --argjson inputs "$INPUTS_JSON" '{ref: $ref, inputs: $inputs}')

@@ -32,19 +37,30 @@ if [ "$DISPATCH_CODE" != "201" ]; then
  exit 1
 fi

-RUNS_URL="$GITEA_API_URL/api/v1/repos/$TARGET_REPO/actions/runs?status=running"
-RUNS_RESP=$(curl -s --connect-timeout 5 --max-time 10 \
-  -H "Authorization: token $GITEA_TOKEN" "$RUNS_URL")
-
-RUN_ID=$(echo "$RUNS_RESP" | jq -r '.workflow_runs[0].id // empty')
-if [ -z "$RUN_ID" ] || [ "$RUN_ID" = "null" ]; then
-  echo "ERROR: Could not find dispatched workflow run" >&2
-  exit 1
-fi
-
+# Poll: find dispatched run by display_title matching
+RUN_ID=""
 TIMEOUT_SECONDS=$(awk "BEGIN {printf \"%.3f\", $TIMEOUT_MINUTES * 60}")
 START_TIME=$(date +%s)

+while [ -z "$RUN_ID" ]; do
+  NOW=$(date +%s)
+  ELAPSED=$((NOW - START_TIME))
+  if awk -v e="$ELAPSED" -v t="$TIMEOUT_SECONDS" 'BEGIN { exit !(e >= t) }'; then
+    echo "ERROR: Timeout after ${TIMEOUT_MINUTES} minutes — run not found" >&2
+    exit 124
+  fi
+
+  RUNS_RESP=$(curl -s --connect-timeout 5 --max-time 10 \
+    "$GITEA_API_URL/api/v1/repos/$TARGET_REPO/actions/runs?event=workflow_dispatch&limit=10" \
+    -H "Authorization: token $GITEA_TOKEN")
+
+  RUN_ID=$(echo "$RUNS_RESP" | jq -r --arg id "$DISPATCH_ID" \
+    '[.workflow_runs[] | select(.display_title | contains($id))] | .[0].id // empty')
+
+  [ -z "$RUN_ID" ] && sleep "$POLL_INTERVAL"
+done
+
+# Poll: wait for run to complete
 while true; do
  NOW=$(date +%s)
  ELAPSED=$((NOW - START_TIME))
@@ -61,6 +77,12 @@ while true; do
  if [ "$STATUS" = "completed" ]; then
    CONCLUSION=$(echo "$RUN_RESP" | jq -r '.conclusion // "failure"')
    if [ "$CONCLUSION" = "success" ]; then
+      GITOPS_COMMIT=""
+      BRANCH_RESP=$(curl -s --connect-timeout 5 --max-time 10 \
+        "$GITEA_API_URL/api/v1/repos/$TARGET_REPO/branches/$REF" \
+        -H "Authorization: token $GITEA_TOKEN") || true
+      GITOPS_COMMIT=$(echo "$BRANCH_RESP" | jq -r '.commit.id // empty')
+      echo "GITOPS_COMMIT=$GITOPS_COMMIT"
      exit 0
    fi
    echo "ERROR: Workflow completed with conclusion: $CONCLUSION" >&2
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "gitops-dispatch: validating env vars..."
+: "${GITOPS_FILE:?}"
+: "${GITOPS_YQ_TPL:?}"
+: "${GITOPS_VERSION:?}"
+: "${GITOPS_SOURCE_REPO:?}"
+: "${GITOPS_SOURCE_COMMIT:?}"
+: "${GITOPS_REPO:?}"
+: "${GITOPS_WORKFLOW:?}"
+: "${GITEA_API_URL:?}"
+: "${GITEA_TOKEN:?}"
+
+TIMEOUT="${GITOPS_DISPATCH_TIMEOUT:-30}"
+
+echo "gitops-dispatch: constructing inputs..."
+INPUTS=$(jq -nc \
+  --arg file "$GITOPS_FILE" \
+  --arg yq_tpl "$GITOPS_YQ_TPL" \
+  --arg version "$GITOPS_VERSION" \
+  --arg source_repo "$GITOPS_SOURCE_REPO" \
+  --arg source_commit "$GITOPS_SOURCE_COMMIT" \
+  --arg git_tag_prefix "${GITOPS_TAG_PREFIX:-}" \
+  --arg extra_cmd "${GITOPS_EXTRA_CMD:-}" \
+  --arg author_name "${GIT_USER_NAME:-}" \
+  --arg author_email "${GIT_USER_EMAIL:-}" \
+  '{file: $file, yq_tpl: $yq_tpl, version: $version, source_repo: $source_repo, source_commit: $source_commit, git_tag_prefix: $git_tag_prefix, extra_cmd: $extra_cmd, author_name: $author_name, author_email: $author_email}')
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "gitops-dispatch: dispatching to $GITOPS_REPO/$GITOPS_WORKFLOW..."
+set +e
+OUTPUT=$(bash "$DIR/dispatch-workflow.sh" \
+  "$GITOPS_REPO" "$GITOPS_WORKFLOW" "main" \
+  "$INPUTS" "$GITEA_API_URL" "$GITEA_TOKEN" "$TIMEOUT" 2>&1)
+EXIT=$?
+set -e
+
+echo "=== DISPATCH OUTPUT (exit=$EXIT) ==="
+echo "$OUTPUT"
+echo "=== END DISPATCH ==="
+
+STATUS="failure"
+GITOPS_SHA=""
+if [ "$EXIT" = "0" ]; then
+  STATUS="success"
+  GITOPS_SHA=$(echo "$OUTPUT" | grep '^GITOPS_COMMIT=' | cut -d= -f2)
+fi
+
+COMPONENT="${GITOPS_TAG_PREFIX:-${GITOPS_FILE}}"
+echo "GITOPS_SUMMARY=${COMPONENT}|${GITOPS_VERSION}|${STATUS}|${GITOPS_SHA}|${GITOPS_REPO}"
+exit "$EXIT"
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+_gitops_fail() {
+  local MSG="${1:-GitOps update failed}"
+  echo "[ERROR] ${MSG}" >&2
+
+  if [ -n "${GITOPS_REPO:-}" ] && [ -n "${GITOPS_SHA:-}" ] && \
+     [ -n "${SOURCE_REPO:-}" ] && [ -n "${SOURCE_COMMIT:-}" ] && \
+     [ -n "${GITEA_API_URL:-}" ] && [ -n "${GITEA_TOKEN:-}" ]; then
+    local env repo context
+    env=$(dirname "${INPUT_FILE}")
+    repo=$(basename "${SOURCE_REPO}")
+    context="${repo} ${GITHUB_RUN_ID:-unknown}"
+    [ -n "${GIT_TAG_PREFIX:-}" ] && context="${repo}/${GIT_TAG_PREFIX} ${GITHUB_RUN_ID:-unknown}"
+
+    local SOURCE_URL="${GITEA_API_URL}/${SOURCE_REPO}/commit/${SOURCE_COMMIT}"
+    ROOT_REPO="${GITOPS_REPO}" ROOT_COMMIT="${GITOPS_SHA}" \
+      GITEA_API_URL="${GITEA_API_URL}" GITEA_TOKEN="${GITEA_TOKEN}" \
+      bash "${SCRIPT_DIR}/report-status.sh" failure "Install to ${env} ${VERSION}" \
+      "${context}" "" "${SOURCE_URL}" 2>/dev/null || true
+  fi
+
+  exit 1
+}
+
+_gitops_validate() {
+  [ -n "${INPUT_FILE:-}" ] || _gitops_fail "INPUT_FILE is required"
+  [ -n "${YQ_TPL:-}" ] || _gitops_fail "YQ_TPL is required"
+  [ -n "${VERSION:-}" ] || _gitops_fail "VERSION is required"
+  [ -n "${SOURCE_REPO:-}" ] || _gitops_fail "SOURCE_REPO is required"
+  [ -n "${SOURCE_COMMIT:-}" ] || _gitops_fail "SOURCE_COMMIT is required"
+  [ -n "${GITOPS_REPO:-}" ] || _gitops_fail "GITOPS_REPO is required"
+  [ -n "${GITEA_TOKEN:-}" ] || _gitops_fail "GITEA_TOKEN is required"
+  [ -n "${GITEA_API_URL:-}" ] || _gitops_fail "GITEA_API_URL is required"
+}
+
+_gitops_success() {
+  local env repo context
+  env=$(dirname "${INPUT_FILE}")
+  repo=$(basename "${SOURCE_REPO}")
+  context="${repo} ${GITHUB_RUN_ID:-unknown}"
+  [ -n "${GIT_TAG_PREFIX:-}" ] && context="${repo}/${GIT_TAG_PREFIX} ${GITHUB_RUN_ID:-unknown}"
+
+  local SOURCE_URL="${GITEA_API_URL}/${SOURCE_REPO}/commit/${SOURCE_COMMIT}"
+
+  ROOT_REPO="${GITOPS_REPO}" ROOT_COMMIT="${GITOPS_SHA}" \
+    GITEA_API_URL="${GITEA_API_URL}" GITEA_TOKEN="${GITEA_TOKEN}" \
+    bash "${SCRIPT_DIR}/report-status.sh" success \
+    "Install to ${env} ${VERSION}" \
+    "${context}" "" "${SOURCE_URL}"
+}
+
+_gitops_nochange() {
+  local env repo context
+  env=$(dirname "${INPUT_FILE}")
+  repo=$(basename "${SOURCE_REPO}")
+  context="${repo} ${GITHUB_RUN_ID:-unknown}"
+  [ -n "${GIT_TAG_PREFIX:-}" ] && context="${repo}/${GIT_TAG_PREFIX} ${GITHUB_RUN_ID:-unknown}"
+
+  local SOURCE_URL="${GITEA_API_URL}/${SOURCE_REPO}/commit/${SOURCE_COMMIT}"
+
+  ROOT_REPO="${GITOPS_REPO}" ROOT_COMMIT="${GITOPS_SHA}" \
+    GITEA_API_URL="${GITEA_API_URL}" GITEA_TOKEN="${GITEA_TOKEN}" \
+    bash "${SCRIPT_DIR}/report-status.sh" success \
+    "Install to ${env} ${VERSION} — no change" \
+    "${context}" "" "${SOURCE_URL}"
+}
+
+_gitops_substitute() {
+  echo "$1" | sed "s/{{VERSION}}/$2/g"
+}
+
+_gitops_update() {
+  local CLONE_DIR="${GITOPS_TARGET_DIR:-$(mktemp -d)}"
+
+  if [ -n "${GITOPS_CLONE_URL:-}" ]; then
+    git clone "${GITOPS_CLONE_URL}" "${CLONE_DIR}" || _gitops_fail "Failed to clone GitOps repo"
+  else
+    git clone "${CLONE_URL}" "${CLONE_DIR}" || _gitops_fail "Failed to clone GitOps repo"
+  fi
+
+  cd "${CLONE_DIR}" || _gitops_fail "Failed to enter clone directory"
+  yq eval -i "${YQ_EXPR}" "${INPUT_FILE}" || _gitops_fail "Failed to update ${INPUT_FILE}"
+  if [ -n "${GITOPS_EXTRA_CMD:-}" ]; then
+    eval "${GITOPS_EXTRA_CMD}" || _gitops_fail "Extra command failed: ${GITOPS_EXTRA_CMD}"
+    git add -A || _gitops_fail "Failed to stage all changes"
+  else
+    git add "${INPUT_FILE}" || _gitops_fail "Failed to stage ${INPUT_FILE}"
+  fi
+
+  if git diff --cached --quiet; then
+    echo "No changes — ${INPUT_FILE} already at ${VERSION}"
+    GITOPS_SHA="$(git rev-parse HEAD)"
+    _gitops_nochange
+    exit 0
+  fi
+
+  git -c user.name="${GIT_USER_NAME:-gitea-ci-bot}" \
+      -c user.email="${GIT_USER_EMAIL:-ci@keskikuja.site}" \
+      commit -m "[skip ci] gitops: update version to ${VERSION}" || _gitops_fail "Failed to commit"
+  GITOPS_SHA="$(git rev-parse HEAD)"
+  git push || _gitops_fail "Failed to push"
+
+  _gitops_success
+}
+
+_gitops_validate
+
+YQ_EXPR=$(_gitops_substitute "${YQ_TPL}" "${VERSION}")
+
+GITEA_HOST=$(echo "${GITEA_API_URL}" | sed 's|https://||' | sed 's|http://||')
+CLONE_URL="${GITOPS_CLONE_URL:-https://${GITEA_TOKEN}@${GITEA_HOST}/${GITOPS_REPO}.git}"
+
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  _gitops_update
+fi
@@ -202,7 +202,16 @@ jobs:

      - name: Report
        if: always()
-        run: bash .ci/scripts/ci-report.sh "<kuvaus>" <context> <suite> ${{ job.status }}
+        run: |
+          bash .ci/scripts/ci-report.sh "<Test type> test report" <context> <suite> ${{ job.status }}
+```
+
+Monorepossa context ja description sisältävät komponentin nimen:
+```yaml
+      - name: Report
+        if: always()
+        run: |
+          bash .ci/scripts/ci-report.sh "<Komponentti>: <Test type> test report" <komponentti>.<context> <suite> ${{ job.status }}
 ```

 **Usean runnerin cache-ongelma:** Jos eri kerroilla käynnistyy eri runnereita,
@@ -218,6 +227,7 @@ niillä voi olla eri versio `latest`-imagen digesteistä. Ratkaisuja:

 ### Taso 1: Ei jälkikäsittelyä

+Single repo:
 ```yaml
 - name: Run tests
  shell: bash
@@ -227,11 +237,27 @@ niillä voi olla eri versio `latest`-imagen digesteistä. Ratkaisuja:

 - name: Report
  if: always()
-  run: bash .ci/scripts/ci-report.sh "<kuvaus>" <context> <suite> ${{ job.status }}
+  run: |
+    bash .ci/scripts/ci-report.sh "<Test type> test report" <context> <suite> ${{ job.status }}
+```
+
+Monorepo:
+```yaml
+- name: Run tests
+  shell: bash
+  run: |
+    mkdir -p "reports/<suite>"
+    <testikomento>
+
+- name: Report
+  if: always()
+  run: |
+    bash .ci/scripts/ci-report.sh "<Komponentti>: <Test type> test report" <komponentti>.<context> <suite> ${{ job.status }}
 ```

 ### Taso 2: Jälkikäsittely tarvitaan

+Single repo:
 ```yaml
 - name: Run tests
  shell: bash
@@ -249,7 +275,30 @@ niillä voi olla eri versio `latest`-imagen digesteistä. Ratkaisuja:

 - name: Report
  if: always()
-  run: bash .ci/scripts/ci-report.sh "<kuvaus>" <context> <suite> ${{ job.status }}
+  run: |
+    bash .ci/scripts/ci-report.sh "<Test type> test report" <context> <suite> ${{ job.status }}
+```
+
+Monorepo:
+```yaml
+- name: Run tests
+  shell: bash
+  run: |
+    mkdir -p "reports/<suite>"
+    <testikomento> > "reports/<suite>/results.txt" 2>&1
+
+- name: Post-process coverage
+  if: always()
+  run: <siirrä coverage-data reports/<suite>/coverage/-hakemistoon>
+
+- name: Post-process test report
+  if: always()
+  run: <HTML-generointi raa'asta outputista>
+
+- name: Report
+  if: always()
+  run: |
+    bash .ci/scripts/ci-report.sh "<Komponentti>: <Test type> test report" <komponentti>.<context> <suite> ${{ job.status }}
 ```

 ### Väärin vs oikein — yksi asia per step
@@ -273,7 +322,16 @@ niillä voi olla eri versio `latest`-imagen digesteistä. Ratkaisuja:

 - name: Report
  if: always()
-  run: bash .ci/scripts/ci-report.sh "Helm kubeconform" helm-test kubeconform ${{ job.status }}
+  run: |
+    bash .ci/scripts/ci-report.sh "Helm kubeconform" helm-test kubeconform ${{ job.status }}
+```
+
+Monorepossa:
+```yaml
+- name: Report
+  if: always()
+  run: |
+    bash .ci/scripts/ci-report.sh "<Komponentti>: Helm kubeconform" <komponentti>.helm-test kubeconform ${{ job.status }}
 ```

 ### Väärin vs oikein — post-process
@@ -509,6 +567,15 @@ jobs:
      suites: '<suite-1> <suite-2>'
 ```

+**Commit status -kontekstit monorepossa:** Testiraporttien `ci-report.sh`-kutsussa
+context ja description sisältävät komponentin nimen:
+```yaml
+      - name: Report
+        if: always()
+        run: |
+          bash .ci/scripts/ci-report.sh "<Komponentti>: Unit test report" <komponentti>.unit-tests bats ${{ job.status }}
+```
+
 ### Version elinkaari per komponentti

 `GIT_TAG_PREFIX` takaa että eri komponenttien versiohistoria pysyy erillään.
@@ -240,6 +240,35 @@ Tiedostonimet `.gitea/workflows/`-kansiossa noudattavat yhtenäistä rakennetta:
 Single repossa `<komponentti>` jätetään pois.
 Monorepossa prefiksi pitää komponentin tiedostot yhdessä.

+### 6.1 Commit status -nimeäminen
+
+`ci-report.sh`-kutsun `description` (2. argumentti) ja `context` (3. argumentti)
+noudattavat seuraavaa kaavaa:
+
+**Single repo:**
+```
+context:     <testityyppi>            (esim. unit-tests, acc-tests)
+description: <Test type> test report  (esim. Unit test report)
+```
+
+**Monorepo:**
+```
+context:     <komponentti>.<testityyppi>            (esim. library.unit-tests)
+description: <Komponentti>: <Test type> test report (esim. Library: Unit test report)
+```
+
+> Gitea YAML: `run:` laita lainausmerkeillä `run: |`-blockiin — Gitea ei tue lainausmerkkejä yhden rivin `run:`-komennoissa.
+>
+> ```yaml
+>       - name: Report
+>         if: always()
+>         run: |
+>           bash .ci/scripts/ci-report.sh "<Komponentti>: <Test type> test report" <komponentti>.<context> <suite> ${{ job.status }}
+> ```
+
+Build/push-status (Docker, Helm) on providerin hallussa — consumer ei vaikuta
+niiden nimeämiseen.
+
 ## 7. Artifact-kuri

 Gitea Actionsin `upload-artifact` jättää pysyvän tiedoston. Artifakteja ei käytetä
@@ -339,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
@@ -353,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
@@ -0,0 +1,251 @@
+---
+name: gitops-update
+description: |
+  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
+  config repo.
+category: ci
+impact: high
+---
+
+# GitOps Update — consumer setup
+
+## What you need
+
+- **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
+
+Two repos, isolated access. The consumer never writes to GitOps directly;
+it dispatches a workflow that clones, updates, commits, and pushes.
+
+---
+
+## 1. GitOps-repo setup
+
+Create `.gitea/workflows/gitops-service.yaml`:
+
+```yaml
+name: GitOps Update
+run-name: "GitOps (${{ inputs.dispatch_id || 'manual' }})"
+on:
+  workflow_dispatch:
+    inputs:
+      file:
+        required: true
+        type: string
+      yq_tpl:
+        required: true
+        type: string
+      version:
+        required: true
+        type: string
+      source_repo:
+        required: true
+        type: string
+      source_commit:
+        required: true
+        type: string
+      dispatch_id:
+        required: false
+        type: string
+      git_tag_prefix:
+        required: false
+        type: string
+      extra_cmd:
+        required: false
+        type: string
+      author_name:
+        required: false
+        type: string
+      author_email:
+        required: false
+        type: string
+
+env:
+  INPUT_FILE: ${{ inputs.file }}
+  YQ_TPL: ${{ inputs.yq_tpl }}
+  VERSION: ${{ inputs.version }}
+  SOURCE_REPO: ${{ inputs.source_repo }}
+  SOURCE_COMMIT: ${{ inputs.source_commit }}
+  GITOPS_REPO: ${{ github.repository }}
+  GITEA_API_URL: ${{ gitea.server_url }}
+  GIT_TAG_PREFIX: ${{ inputs.git_tag_prefix || '' }}
+  GITOPS_EXTRA_CMD: ${{ inputs.extra_cmd || '' }}
+  GIT_USER_NAME: ${{ inputs.author_name || '' }}
+  GIT_USER_EMAIL: ${{ inputs.author_email || '' }}
+
+jobs:
+  update:
+    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 }}
+        run: |
+          bash .ci/scripts/gitops-update.sh
+```
+
+> **⚠️ 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`. 
+
+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
+
+---
+
+## 2. Consumer-repo setup
+
+### 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: [build-push]
+  if: success()
+  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
+```
+
+This single job handles: dispatch → poll → find commit SHA → set commit-status on your commit → produce `GITOPS_SUMMARY` output.
+
+To run extra commands (e.g. `helm dependency update`) after the version bump and before the commit:
+
+```yaml
+gitops-update:
+  needs: [load-config, check-version, helm-build-push]
+  if: success()
+  uses: niko/gitea-ci-library/.gitea/workflows/gitops-dispatch.yml@v1
+  secrets: inherit
+  with:
+    env_json: ${{ needs.load-config.outputs.env_json }}
+    version: ${{ needs.check-version.outputs.version }}
+    GITOPS_FILE: Chart.yaml
+    GITOPS_YQ_TPL: '(.dependencies[] | select(.name == "agent-platform-helm") | .version) = "{{VERSION}}"'
+    GITOPS_REPO: niko/agent-platform-gitops
+    GITOPS_EXTRA_CMD: helm dependency update
+```
+
+When `GITOPS_EXTRA_CMD` is set, the script runs it after `yq` and stages all changes (`git add -A`) instead of only the input file — so any files generated by the extra command (e.g. `Chart.lock`, `charts/`) are included in the commit.
+
+By default the GitOps commit is made as `gitea-ci-bot`. To use the original commit author instead, the dispatch workflow resolves it automatically from the consumer repo — no extra config needed. Just ensure the GitOps repo's `gitops-service.yaml` template has the `author_name` and `author_email` inputs and env mappings.
+
+### 2.3 Parameters
+
+| Input | Required | Description |
+|---|---|---|---|
+| `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`) |
+| `GITOPS_EXTRA_CMD` | No | Shell command to run after yq update, before git commit (e.g. `helm dependency update`) |
+
+### 2.4 Output
+
+The workflow produces a `summary` output in pipe format:
+
+```
+component|version|status|commit_sha|repo
+agent-platform-helm|0.2.3|success|abc789def|niko/agent-platform-gitops
+```
+
+Pass it to `report-summary.yml` for the pipeline summary:
+
+```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 }}
+```
+
+---
+
+## 3. Token summary
+
+| 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 |
+
+---
+
+## 4. What happens at runtime
+
+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`, runs `GITOPS_EXTRA_CMD` if set, then 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`
+
+---
+
+## 5. GIT_TAG_PREFIX (optional)
+
+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`:
+
+```
+GIT_TAG_PREFIX=docker/
+```
+
+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.
@@ -3,6 +3,7 @@
 setup() {
  source tests/helpers/mock-api.sh
  export DISPATCH_POLL_INTERVAL="0.1"
+  export DISPATCH_ID="test123"
 }

 teardown() {
@@ -12,8 +13,7 @@ teardown() {
@test "dispatch succeeds: POST 201, poll running x3 then success → exit 0" {
  mock_set_sequence '[
    {"code":201},
-    {"code":200,"body":{"workflow_runs":[{"id":1,"status":"running"}]}},
-    {"code":200,"body":{"id":1,"status":"running"}},
+    {"code":200,"body":{"workflow_runs":[{"id":1,"display_title":"POC (test123)","run_number":42,"status":"running"}]}},
    {"code":200,"body":{"id":1,"status":"running"}},
    {"code":200,"body":{"id":1,"status":"running"}},
    {"code":200,"body":{"id":1,"status":"completed","conclusion":"success"}}
@@ -26,7 +26,7 @@ teardown() {
@test "dispatch: poll returns failure conclusion → exit 1" {
  mock_set_sequence '[
    {"code":201},
-    {"code":200,"body":{"workflow_runs":[{"id":1,"status":"running"}]}},
+    {"code":200,"body":{"workflow_runs":[{"id":1,"display_title":"POC (test123)","run_number":42,"status":"running"}]}},
    {"code":200,"body":{"id":1,"status":"running"}},
    {"code":200,"body":{"id":1,"status":"completed","conclusion":"failure"}}
  ]'
@@ -38,7 +38,7 @@ teardown() {
@test "dispatch: poll returns cancelled conclusion → exit 1" {
  mock_set_sequence '[
    {"code":201},
-    {"code":200,"body":{"workflow_runs":[{"id":1,"status":"running"}]}},
+    {"code":200,"body":{"workflow_runs":[{"id":1,"display_title":"POC (test123)","run_number":42,"status":"running"}]}},
    {"code":200,"body":{"id":1,"status":"running"}},
    {"code":200,"body":{"id":1,"status":"completed","conclusion":"cancelled"}}
  ]'
@@ -47,18 +47,18 @@ teardown() {
  [ "$status" -eq 1 ]
 }

-@test "timeout: poll never completes, exceeds timeout_minutes → exit 124" {
+@test "timeout: no matching run found, exceeds timeout_minutes → exit 124" {
  mock_set_sequence '[
    {"code":201},
-    {"code":200,"body":{"workflow_runs":[{"id":1,"status":"running"}]}},
-    {"code":200,"body":{"id":1,"status":"running"}},
-    {"code":200,"body":{"id":1,"status":"running"}},
-    {"code":200,"body":{"id":1,"status":"running"}},
-    {"code":200,"body":{"id":1,"status":"running"}},
-    {"code":200,"body":{"id":1,"status":"running"}},
-    {"code":200,"body":{"id":1,"status":"running"}},
-    {"code":200,"body":{"id":1,"status":"running"}},
-    {"code":200,"body":{"id":1,"status":"running"}}
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}},
+    {"code":200,"body":{"workflow_runs":[]}}
  ]'
  mock_start
  run bash scripts/dispatch-workflow.sh "test-owner/test-repo" "test.yml" "main" '{"version":"1.2.3"}' "http://localhost:18080" "test-token-abc123" "0.001"
@@ -77,7 +77,7 @@ teardown() {
@test "POST dispatch is called with correct URL and payload" {
  mock_set_sequence '[
    {"code":201},
-    {"code":200,"body":{"workflow_runs":[{"id":1,"status":"running"}]}},
+    {"code":200,"body":{"workflow_runs":[{"id":1,"display_title":"POC (test123)","run_number":42,"status":"running"}]}},
    {"code":200,"body":{"id":1,"status":"completed","conclusion":"success"}}
  ]'
  mock_start
@@ -91,6 +91,7 @@ teardown() {
  [[ "$body" == *'"ref":"main"'* ]]
  [[ "$body" == *'"inputs"'* ]]
  [[ "$body" == *'"version":"1.2.3"'* ]]
+  [[ "$body" == *'"dispatch_id":"test123"'* ]]
 }

@test "missing gitea_api_url argument → exit 1 with error message" {
@@ -120,15 +121,15 @@ teardown() {
  [ "$status" -eq 1 ]
 }

-@test "dispatch: no workflow run found after dispatch → exit 1" {
+@test "dispatch: no workflow run found after dispatch → exit 124 (timeout)" {
  mock_set_sequence '[
    {"code":201},
    {"code":200,"body":{"workflow_runs":[]}}
  ]'
  mock_start
-  run bash scripts/dispatch-workflow.sh "test-owner/test-repo" "test.yml" "main" '{}' "http://localhost:18080" "test-token-abc123"
-  [ "$status" -eq 1 ]
-  [[ "$output" == *"ERROR"* ]]
+  run bash scripts/dispatch-workflow.sh "test-owner/test-repo" "test.yml" "main" '{}' "http://localhost:18080" "test-token-abc123" "0.001"
+  [ "$status" -eq 124 ]
+  [[ "$output" == *"ERROR"* || "$output" == *"Timeout"* ]]
 }

@test "missing inputs_json argument → exit 1" {
@@ -0,0 +1,42 @@
+Feature: GitOps update
+  As a GitOps repository
+  I want to update version references and report results to the caller
+  So that the deployment chain is traceable from source to GitOps commit
+
+  Background:
+    Given a project repository exists in Gitea
+    And a commit has been pushed to the repository
+
+  @mock
+  Scenario: Not enough env vars — script fails, no status set
+    Given insufficient environment variables are provided for the GitOps update
+    When the GitOps update script runs
+    Then the script exits with error
+
+  @mock
+  Scenario: GitOps job fails — no status set (SHA not yet known)
+    Given the GitOps repository clone will fail
+    When the GitOps update script runs
+    Then the script exits with error
+
+  @mock
+  Scenario: Everything succeeds — GitOps repo gets success status with link to caller
+    Given a valid GitOps update dispatch
+    When the GitOps update script runs
+    Then the script exits successfully
+    And the GitOps repo commit shows a success status with a link to the caller commit
+
+  @mock
+  Scenario: GitOps push fails — GitOps repo gets failure status
+    Given the GitOps repo push will fail after the version is committed
+    When the GitOps update script runs
+    Then the script exits with error
+    And the GitOps repo commit shows a failure status linking to the caller commit
+
+  @mock
+  Scenario: No changes — GitOps repo gets "no change" status
+    Given the version file already has the target version
+    When the GitOps update script runs
+    Then the script exits successfully
+    And the GitOps repo commit shows a "no change" status
+    And no Git commit or push was performed
@@ -0,0 +1,172 @@
+const { spawnSync, execSync } = require('child_process');
+const { Before, After, Given, When, Then } = require('@cucumber/cucumber');
+const path = require('path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..', '..');
+const MOCK_SCRIPT = path.join(PROJECT_ROOT, 'tests', 'helpers', 'mock-api.sh');
+const GITOPS_SCRIPT = path.join(PROJECT_ROOT, 'scripts', 'gitops-update.sh');
+const MOCK_HELPERS = path.join(PROJECT_ROOT, 'tests', 'helpers');
+const REQ_FILE = '/tmp/gitops-mock-requests.log';
+
+const BASE_ENV = {
+  INPUT_FILE: 'dev/Chart.yaml',
+  YQ_TPL: '(.version) = "{{VERSION}}"',
+  VERSION: '0.2.3',
+  SOURCE_REPO: 'niko/app',
+  SOURCE_COMMIT: 'abc123def456',
+  GITOPS_REPO: 'niko/app-gitops',
+  GITEA_API_URL: 'http://localhost:18080',
+  GITEA_TOKEN: 'test-token',
+};
+
+Before({ tags: '@mock' }, function () {
+  process.env.PATH = `${MOCK_HELPERS}:${process.env.PATH}`;
+  try { execSync('rm -f /tmp/gitops-mock-requests.log', { stdio: 'ignore' }); } catch (_) {}
+  // Restart mock with known request file path
+  const result = spawnSync('bash', ['-c', `
+    source "${MOCK_SCRIPT}"
+    mock_stop 2>/dev/null
+    MOCK_REQUEST_FILE="${REQ_FILE}"
+    mock_start
+    sleep 0.5
+    curl -s -o /dev/null -w "%{http_code}" --max-time 3 http://localhost:18080/api/v1/repos/health
+  `], {
+    cwd: PROJECT_ROOT, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+  });
+  const code = result.stdout.trim();
+  if (!code.startsWith('2') && !code.startsWith('4')) {
+    throw new Error(`GitOps mock restart failed: ${result.stderr.substring(0,200)}`);
+  }
+});
+
+After({ tags: '@mock' }, function () {
+  spawnSync('bash', ['-c', `source "${MOCK_SCRIPT}" && mock_stop 2>/dev/null`], { stdio: 'ignore' });
+  try { execSync('rm -f /tmp/gitops-mock-requests.log /tmp/gitops-git-calls.log', { stdio: 'ignore' }); } catch (_) {}
+});
+
+function bash(cmd) {
+  const result = spawnSync('bash', ['-c', cmd], {
+    cwd: PROJECT_ROOT,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return { status: result.status, stdout: result.stdout || '', stderr: result.stderr || '' };
+}
+
+function getFirstBody() {
+  return bash(`grep -A1 '^POST ' "${REQ_FILE}" 2>/dev/null | head -2 | tail -1 || echo ""`).stdout.trim();
+}
+
+function getFirstPath() {
+  return bash(`grep '^POST ' "${REQ_FILE}" 2>/dev/null | head -1 | awk '{print $2}' || echo ""`).stdout.trim();
+}
+
+function getLastBody() {
+  return bash(`grep -A1 '^POST ' "${REQ_FILE}" 2>/dev/null | grep -v '^POST ' | tail -1 || echo ""`).stdout.trim();
+}
+
+function getLastPath() {
+  return bash(`grep '^POST ' "${REQ_FILE}" 2>/dev/null | tail -1 | awk '{print $2}' || echo ""`).stdout.trim();
+}
+
+function requestCount() {
+  return parseInt(bash(`grep -c '^POST ' "${REQ_FILE}" 2>/dev/null || echo 0`).stdout.trim(), 10) || 0;
+}
+
+function gitCalls() {
+  const callsFile = process.env.GIT_CALLS_FILE || '/dev/null';
+  const out = bash(`cat "${callsFile}" 2>/dev/null || echo ""`).stdout;
+  return out.split('\n').filter(l => l.length > 0);
+}
+
+function runScript(envOverrides) {
+  const env = { ...BASE_ENV, ...envOverrides };
+  const scriptPath = `/tmp/gitops-run-${Date.now()}.sh`;
+  const exports = Object.entries(env)
+    .map(([k, v]) => `export ${k}="${v.replace(/"/g, '\\"')}"`)
+    .join('\n');
+  require('fs').writeFileSync(scriptPath, `${exports}\nexport PATH="${MOCK_HELPERS}:$PATH"\nset -euo pipefail\nbash "${GITOPS_SCRIPT}"\nsync\n`, 'utf8');
+  try {
+    return bash(`bash "${scriptPath}"`);
+  } finally {
+    require('fs').unlinkSync(scriptPath);
+  }
+}
+
+Given('insufficient environment variables are provided for the GitOps update', function () {
+  this.envOverrides = { INPUT_FILE: '' };
+});
+
+Given('the GitOps repository clone will fail', function () {
+  this.envOverrides = { GIT_MOCK_FAIL: '1' };
+});
+
+Given('a valid GitOps update dispatch', function () {
+  this.envOverrides = {};
+});
+
+Given('the GitOps repo push will fail after the version is committed', function () {
+  this.envOverrides = { GIT_MOCK_FAIL_PUSH: '1' };
+});
+
+Given('the version file already has the target version', function () {
+  this.envOverrides = {
+    GIT_MOCK_DIFF_NO_CHANGES: '1',
+    GIT_CALLS_FILE: '/tmp/gitops-git-calls.log',
+  };
+});
+
+When('the GitOps update script runs', function () {
+  this.result = runScript(this.envOverrides || {});
+});
+
+Then('the script exits with error', function () {
+  if (this.result.status === 0) throw new Error(`Expected non-zero exit, got 0. stderr: ${this.result.stderr.substring(0,200)}`);
+});
+
+Then('the script exits successfully', function () {
+  if (this.result.status !== 0) throw new Error(`Expected exit 0, got ${this.result.status}: ${this.result.stderr.substring(0,200)}`);
+});
+
+Then('the GitOps repo commit shows a success status with a link to the caller commit', function () {
+  const count = requestCount();
+  if (count < 1) throw new Error(`Expected at least 1 request, got ${count}`);
+  const body = getFirstBody();
+  if (!body.includes('"state":"success"')) throw new Error(`Expected success state, body: ${body.substring(0,200)}`);
+  if (!body.includes('"context":"app ')) throw new Error(`Expected context "app unknown", body: ${body.substring(0,200)}`);
+  if (!body.includes('"description":"Install to dev 0.2.3"')) throw new Error(`Expected description, body: ${body.substring(0,200)}`);
+  if (!body.includes('niko/app/commit/abc123def456')) throw new Error(`Expected link to caller commit, body: ${body.substring(0,200)}`);
+  const pathStr = getFirstPath();
+  if (!pathStr.includes('/repos/niko/app-gitops/statuses/')) throw new Error(`Expected gitops repo path, got: ${pathStr}`);
+});
+
+Then('the GitOps repo commit shows a failure status linking to the caller commit', function () {
+  const count = requestCount();
+  if (count < 1) throw new Error(`Expected at least 1 request, got ${count}`);
+  const body = getFirstBody();
+  if (!body.includes('"state":"failure"')) throw new Error(`Expected failure state, body: ${body.substring(0,200)}`);
+  if (!body.includes('"context":"app ')) throw new Error(`Expected context "app unknown", body: ${body.substring(0,200)}`);
+  if (!body.includes('"description":"Install to dev 0.2.3"')) throw new Error(`Expected description, body: ${body.substring(0,200)}`);
+  if (!body.includes('niko/app/commit/abc123def456')) throw new Error(`Expected link to caller commit, body: ${body.substring(0,200)}`);
+  const pathStr = getFirstPath();
+  if (!pathStr.includes('/repos/niko/app-gitops/statuses/')) throw new Error(`Expected gitops repo path, got: ${pathStr}`);
+});
+
+Then('the GitOps repo commit shows a "no change" status', function () {
+  const count = requestCount();
+  if (count < 1) throw new Error(`Expected at least 1 request, got ${count}`);
+  const body = getFirstBody();
+  if (!body.includes('"state":"success"')) throw new Error(`Expected success state, body: ${body.substring(0,200)}`);
+  if (!body.includes('"description":"Install to dev 0.2.3 \u2014 no change"')) {
+    throw new Error(`Expected "no change" description, body: ${body.substring(0,200)}`);
+  }
+  const pathStr = getFirstPath();
+  if (!pathStr.includes('/repos/niko/app-gitops/statuses/')) throw new Error(`Expected gitops repo path, got: ${pathStr}`);
+});
+
+Then('no Git commit or push was performed', function () {
+  const calls = gitCalls();
+  if (calls.some(l => l.includes(' commit ') || l.includes(' push '))) {
+    throw new Error(`Expected no commit or push, got: ${calls.join(', ')}`);
+  }
+});
@@ -15,7 +15,7 @@ function bash(cmd) {
      encoding: 'utf-8',
      stdio: ['pipe', 'pipe', 'pipe'],
    });
-    return { status: 0, stdout: out };
+    return { status: 0, stdout: out, stderr: '' };
  } catch (e) {
    return { status: e.status, stdout: e.stdout || '', stderr: e.stderr || '' };
  }
@@ -54,7 +54,7 @@ function setupMock(seqJson) {
 }

 function runDispatch(args) {
-  return bash(`export DISPATCH_POLL_INTERVAL="0.1"; bash "${DISPATCH_SCRIPT}" ${args}`);
+  return bash(`export DISPATCH_ID="test123"; export DISPATCH_POLL_INTERVAL="0.1"; bash "${DISPATCH_SCRIPT}" ${args}`);
 }

 Given('a deployment has completed in the target environment', function () {
@@ -66,7 +66,7 @@ Given('the test project repository exists with test definitions', function () {
 When('a test workflow is dispatched to a test project', function () {
  setupMock(JSON.stringify([
    { code: 201 },
-    { code: 200, body: { workflow_runs: [{ id: 1, status: 'running' }] } },
+    { code: 200, body: { workflow_runs: [{ id: 1, display_title: 'Workflow (test123)', run_number: 42, status: 'running' }] } },
    { code: 200, body: { id: 1, status: 'completed', conclusion: 'success' } },
  ]));
  const r = runDispatch('"test-owner/test-repo" "test.yml" "main" \'{"version":"1.2.3"}\' "http://localhost:18080" "test-token-abc123"');
@@ -84,7 +84,7 @@ Then('the pipeline continues only after receiving a success result', function ()
 When('a test workflow is dispatched and the tests fail', function () {
  setupMock(JSON.stringify([
    { code: 201 },
-    { code: 200, body: { workflow_runs: [{ id: 1, status: 'running' }] } },
+    { code: 200, body: { workflow_runs: [{ id: 1, display_title: 'Workflow (test123)', run_number: 42, status: 'running' }] } },
    { code: 200, body: { id: 1, status: 'completed', conclusion: 'failure' } },
  ]));
  const r = runDispatch('"test-owner/test-repo" "test.yml" "main" \'{"version":"1.2.3"}\' "http://localhost:18080" "test-token-abc123"');
@@ -98,15 +98,19 @@ Then('the calling pipeline reports failure', function () {
 When('a test workflow is dispatched but does not finish within the allowed time', function () {
  setupMock(JSON.stringify([
    { code: 201 },
-    { code: 200, body: { workflow_runs: [{ id: 1, status: 'running' }] } },
-    { code: 200, body: { id: 1, status: 'running' } },
-    { code: 200, body: { id: 1, status: 'running' } },
-    { code: 200, body: { id: 1, status: 'running' } },
+    { code: 200, body: { workflow_runs: [] } },
+    { code: 200, body: { workflow_runs: [] } },
+    { code: 200, body: { workflow_runs: [] } },
+    { code: 200, body: { workflow_runs: [] } },
+    { code: 200, body: { workflow_runs: [] } },
  ]));
-  const r = runDispatch('"test-owner/test-repo" "test.yml" "main" \'{"version":"1.2.3"}\' "http://localhost:18080" "test-token-abc123" "0.001"');
+  const r = runDispatch('"test-owner/test-repo" "test.yml" "main" \'{"version":"1.2.3"}\' "http://localhost:18080" "test-token-abc123" "0.05"');
  this.dispatchResult = r.status;
+  this.dispatchStderr = r.stderr;
 });

 Then('the calling pipeline reports a timeout error', function () {
-  if (this.dispatchResult !== 124) throw new Error(`Expected timeout exit 124, got ${this.dispatchResult}`);
+  if (this.dispatchResult !== 124) {
+    throw new Error(`Expected timeout exit 124, got ${this.dispatchResult}. stderr: ${(this.dispatchStderr || '').substring(0,300)}`);
+  }
 });
@@ -0,0 +1,176 @@
+#!/usr/bin/env bats
+
+setup() {
+  export INPUT_FILE=dev/Chart.yaml
+  export YQ_TPL='version = "{{VERSION}}"'
+  export VERSION=1.0.0
+  export SOURCE_REPO=niko/app
+  export SOURCE_COMMIT=abc123def456
+  export GITOPS_REPO=niko/app-gitops
+  export GITEA_TOKEN=test-token
+  export GITEA_API_URL=http://localhost:18080
+}
+
+teardown() {
+  if type mock_stop &>/dev/null 2>&1; then
+    mock_stop 2>/dev/null || true
+  fi
+}
+
+@test "missing GITEA_API_URL causes exit 1" {
+  unset GITEA_API_URL
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"GITEA_API_URL"* ]]
+}
+
+@test "missing GITEA_TOKEN causes exit 1" {
+  unset GITEA_TOKEN
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"GITEA_TOKEN"* ]]
+}
+
+@test "missing INPUT_FILE causes exit 1" {
+  unset INPUT_FILE
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"INPUT_FILE"* ]]
+}
+
+@test "missing YQ_TPL causes exit 1" {
+  unset YQ_TPL
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"YQ_TPL"* ]]
+}
+
+@test "missing VERSION causes exit 1" {
+  unset VERSION
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"VERSION"* ]]
+}
+
+@test "missing SOURCE_REPO causes exit 1" {
+  unset SOURCE_REPO
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"SOURCE_REPO"* ]]
+}
+
+@test "missing SOURCE_COMMIT causes exit 1" {
+  unset SOURCE_COMMIT
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"SOURCE_COMMIT"* ]]
+}
+
+@test "_gitops_substitute replaces {{VERSION}}" {
+  run bash -c '
+    source scripts/gitops-update.sh >/dev/null 2>&1
+    _gitops_substitute "(.version) = \"{{VERSION}}\"" "0.2.3"
+  '
+  [ "$status" -eq 0 ]
+  [[ "$output" == '(.version) = "0.2.3"' ]]
+}
+
+@test "CLONE_URL is constructed correctly from GITEA_API_URL" {
+  export GITEA_API_URL=https://gitea.app.keskikuja.site
+  export GITEA_TOKEN=secret123
+  export GITOPS_REPO=niko/app-gitops
+  run bash -c '
+    source scripts/gitops-update.sh >/dev/null 2>&1
+    echo "$CLONE_URL"
+  '
+  [ "$status" -eq 0 ]
+  [ "$output" = "https://secret123@gitea.app.keskikuja.site/niko/app-gitops.git" ]
+}
+
+@test "CLONE_URL works with http:// URL" {
+  export GITEA_API_URL=http://localhost:18080
+  export GITEA_TOKEN=token
+  export GITOPS_REPO=owner/repo
+  run bash -c '
+    source scripts/gitops-update.sh >/dev/null 2>&1
+    echo "$CLONE_URL"
+  '
+  [ "$status" -eq 0 ]
+  [ "$output" = "https://token@localhost:18080/owner/repo.git" ]
+}
+
+@test "_gitops_substitute handles multiple {{VERSION}} occurrences" {
+  run bash -c '
+    source scripts/gitops-update.sh >/dev/null 2>&1
+    _gitops_substitute "version = \"{{VERSION}}\"; tag = \"v{{VERSION}}\"" "1.2.3"
+  '
+  [ "$status" -eq 0 ]
+  [[ "$output" == 'version = "1.2.3"; tag = "v1.2.3"' ]]
+}
+
+@test "git flow: clone yq add commit push" {
+  source tests/helpers/mock-api.sh
+  mock_set_sequence '[
+    {"code":201},
+    {"code":201}
+  ]'
+  mock_start
+  export GIT_CALLS_FILE=$(mktemp)
+  export YQ_CALLS_FILE=$(mktemp)
+  export PATH="${BATS_TEST_DIRNAME}/helpers:$PATH"
+  export INPUT_FILE=dev/Chart.yaml
+  export YQ_TPL='(.version) = "{{VERSION}}"'
+  export VERSION=0.2.3
+  export SOURCE_REPO=niko/app
+  export SOURCE_COMMIT=abc123def456
+  export GITOPS_REPO=niko/app-gitops
+  export GITEA_API_URL=http://localhost:18080
+  export GITEA_TOKEN=test-token
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 0 ]
+  git_calls=$(cat "$GIT_CALLS_FILE")
+  [[ "$git_calls" == *"clone"* ]]
+  [[ "$git_calls" == *"add"* ]]
+  [[ "$git_calls" == *"commit"* ]]
+  [[ "$git_calls" == *"push"* ]]
+  yq_calls=$(cat "$YQ_CALLS_FILE")
+  [[ "$yq_calls" == *"eval -i"* ]]
+  rm -f "$GIT_CALLS_FILE" "$YQ_CALLS_FILE"
+  mock_stop
+}
+
+@test "one commit-status call: gitops-repo only" {
+  source tests/helpers/mock-api.sh
+  mock_set_sequence '[
+    {"code":201}
+  ]'
+  mock_start
+  export GIT_CALLS_FILE=$(mktemp)
+  export YQ_CALLS_FILE=$(mktemp)
+  export PATH="${BATS_TEST_DIRNAME}/helpers:$PATH"
+  export INPUT_FILE=dev/Chart.yaml
+  export YQ_TPL='(.version) = "{{VERSION}}"'
+  export VERSION=0.2.3
+  export SOURCE_REPO=niko/app
+  export SOURCE_COMMIT=abc123def456
+  export GITOPS_REPO=niko/app-gitops
+  export GITEA_API_URL=http://localhost:18080
+  export GITEA_TOKEN=test-token
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 0 ]
+  path=$(mock_get_first_request_path)
+  body=$(mock_get_first_request_body)
+  [[ "$path" == *"/repos/niko/app-gitops/statuses/"* ]]
+  [[ "$body" == *'"context":"app '* ]]
+  [[ "$body" == *'"description":"Install to dev 0.2.3"'* ]]
+  [[ "$body" == *'"state":"success"'* ]]
+  rm -f "$GIT_CALLS_FILE" "$YQ_CALLS_FILE"
+  mock_stop
+}
+
+@test "missing GITOPS_REPO causes exit 1" {
+  unset GITOPS_REPO
+  run bash scripts/gitops-update.sh
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"GITOPS_REPO"* ]]
+}
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+echo "git $*" >> "${GIT_CALLS_FILE:-/dev/null}"
+
+[ -z "${GIT_MOCK_FAIL:-}" ] || { echo "git: mock forced failure" >&2; exit 1; }
+
+if [ "${1:-}" = "push" ] && [ -n "${GIT_MOCK_FAIL_PUSH:-}" ]; then
+  echo "git: mock push failure" >&2
+  exit 1
+fi
+
+# Skip -c config arguments
+while [ "${1:-}" = "-c" ]; do
+  shift 2
+done
+
+case "$1" in
+  clone)
+    TARGET_DIR="${@: -1}"
+    mkdir -p "${TARGET_DIR}/$(dirname "$INPUT_FILE")"
+    echo 'version: 0.1.0' > "${TARGET_DIR}/${INPUT_FILE}"
+    echo "Cloning into '$TARGET_DIR'..."
+    ;;
+  add|commit|push|config|init)
+    ;;
+  diff)
+    # Default: exit 1 = has changes → proceed to commit
+    # GIT_MOCK_DIFF_NO_CHANGES=1 → exit 0 = no changes → "no change" path
+    if [ -n "${GIT_MOCK_DIFF_NO_CHANGES:-}" ]; then
+      exit 0
+    fi
+    exit 1
+    ;;
+  rev-parse)
+    echo "mock-sha-9876543210fedcba9876543210fedcba98765432"
+    ;;
+  *)
+    echo "git: unknown command: $*" >&2
+    exit 1
+    ;;
+esac
@@ -46,7 +46,7 @@ mock_clear_sequence() {

 mock_start() {
  MOCK_RESPONSE_CODE="${MOCK_RESPONSE_CODE:-201}"
-  MOCK_REQUEST_FILE=$(mktemp)
+  MOCK_REQUEST_FILE="${MOCK_REQUEST_FILE:-$(mktemp)}"
  echo "$MOCK_REQUEST_FILE" > "$MOCK_STATE_FILE"
  MOCK_CONFIG_FILE=$(mktemp)

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+echo "yq $*" >> "${YQ_CALLS_FILE:-/dev/null}"
Author	SHA1	Message	Date
niko	dd9cdf70b6	Featuer/gitops extra command (#47 ) CI Main / Config load (push) Successful in 1m48s Details CI Main / Latest versio (push) Successful in 1m38s Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 2m15s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 2m46s Details ci-docker-build-push Docker push 0.2.35 Details CI Main / Build & Push Docker (push) Successful in 40s Details gitops/gitea-ci-library GitOps: 0.2.35 Details CI Main / GitOps (push) Successful in 1m34s Details CI Main / Report Summary (push) Successful in 3s Details CI Main / Move provider version tag (push) Successful in 11s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #47	2026-06-27 05:20:09 +03:00
niko	848ba723e4	Fix/git pages rentetin create tests (#46 ) CI Main / Config load (push) Successful in 3m12s Details CI Git-Pages Main / Config load (push) Successful in 3m4s Details CI Main / Latest versio (push) Successful in 30s Details CI Git-Pages Main / Latest version (push) Successful in 27s Details ci-helm-build-push Helm push 0.1.9 Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 1m56s Details CI Git-Pages Main / Build & Push Helm chart (push) Successful in 1m19s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 3m47s Details ci-docker-build-push Docker push 0.2.34 Details CI Main / Build & Push Docker (push) Successful in 1m14s Details gitops/gitea-ci-library/git-pages GitOps: git-pages 0.1.9 Details CI Git-Pages Main / GitOps (push) Successful in 3m37s Details gitops/gitea-ci-library GitOps: 0.2.34 Details CI Main / GitOps (push) Successful in 40s Details CI Main / Report Summary (push) Successful in 4s Details CI Main / Move provider version tag (push) Successful in 12s Details CI Git-Pages Main / Report Summary (push) Successful in 4s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #46	2026-06-26 08:07:02 +03:00
niko	1978a995a8	Update README.md (#45 ) CI Main / Config load (push) Successful in 23s Details CI Main / Latest versio (push) Successful in 21s Details CI Main / Bats tests (push) Successful in 1m34s Details CI Main / Cucumber tests (push) Successful in 1m33s Details ci-docker-build-push Docker push 0.2.33 Details CI Main / Build & Push Docker (push) Successful in 50s Details gitops/gitea-ci-library GitOps: 0.2.33 Details CI Main / GitOps (push) Successful in 47s Details CI Main / Report Summary (push) Successful in 7s Details CI Main / Move provider version tag (push) Successful in 14s Details CI Feature / Load example-gitea-env.conf to pipeline env (push) Successful in 1m5s Details unit-tests Bats test report Details CI Feature / Bats tests (push) Successful in 2m9s Details acc-tests Cucumber test report Details CI Feature / Cucumber tests (push) Successful in 2m53s Details CI Feature / Report Summary (push) Successful in 7s Details Reviewed-on: #45	2026-06-25 09:19:01 +03:00
niko	d6343438a3	Feture/gitops7 (#44 ) unit-tests Bats test report Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m44s Details ci-docker-build-push Docker push 0.2.32 Details gitops/gitea-ci-library GitOps: 0.2.32 Details CI Main / Config load (push) Successful in 26s Details CI Main / Latest versio (push) Successful in 21s Details CI Main / Build & Push Docker (push) Has been skipped Details CI Main / GitOps (push) Has been skipped Details CI Main / Move provider version tag (push) Has been skipped Details CI Main / Report Summary (push) Successful in 5s Details CI Main / Bats tests (push) Has been skipped Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #44	2026-06-23 12:45:42 +03:00
niko	ed2703b7d7	commit status kutsujalle gitops repoon (#43 ) CI Main / Config load (push) Successful in 19s Details CI Main / Latest versio (push) Successful in 19s Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 1m33s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m45s Details ci-docker-build-push Docker push 0.2.31 Details CI Main / Build & Push Docker (push) Successful in 44s Details gitops/gitea-ci-library GitOps: 0.2.31 Details CI Main / GitOps (push) Successful in 35s Details CI Main / Report Summary (push) Successful in 7s Details CI Main / Move provider version tag (push) Successful in 13s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #43	2026-06-22 14:24:25 +03:00
niko	dc4b331ea1	kutsujalle gitops commit (#42 ) CI Main / Config load (push) Successful in 26s Details CI Git-Pages Main / Latest version (push) Successful in 22s Details CI Git-Pages Main / Config load (push) Successful in 25s Details CI Main / Latest versio (push) Successful in 21s Details ci-helm-build-push Helm push 0.1.8 Details CI Main / Bats tests (push) Successful in 1m38s Details CI Git-Pages Main / GitOps (push) Successful in 1m24s Details CI Git-Pages Main / Build & Push Helm chart (push) Successful in 46s Details unit-tests Bats test report Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m59s Details CI Git-Pages Main / Report Summary (push) Successful in 9s Details ci-docker-build-push Docker push 0.2.30 Details CI Main / Build & Push Docker (push) Successful in 50s Details CI Main / Move provider version tag (push) Successful in 14s Details CI Main / GitOps (push) Successful in 41s Details CI Main / Report Summary (push) Successful in 6s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #42	2026-06-22 13:57:14 +03:00
niko	c06015cd9f	poc logiikka takaisin (#41 ) CI Main / Config load (push) Successful in 19s Details CI Main / Latest versio (push) Successful in 17s Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 1m30s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m43s Details ci-docker-build-push Docker push 0.2.29 Details CI Main / Build & Push Docker (push) Successful in 44s Details CI Main / GitOps (push) Successful in 39s Details CI Main / Report Summary (push) Successful in 6s Details CI Main / Move provider version tag (push) Successful in 15s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #41	2026-06-22 13:24:09 +03:00
niko	4c73433eab	Update scripts/gitops-dispatch.sh (#40 ) CI Main / Config load (push) Successful in 21s Details CI Main / Latest versio (push) Successful in 19s Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 1m23s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m43s Details ci-docker-build-push Docker push 0.2.28 Details CI Main / Build & Push Docker (push) Successful in 33s Details CI Main / GitOps (push) Failing after 18s Details CI Main / Move provider version tag (push) Has been skipped Details CI Main / Report Summary (push) Successful in 7s Details Reviewed-on: #40	2026-06-22 11:19:56 +03:00
niko	b9de1da855	testiä (#39 ) ci-helm-build-push Helm push 0.1.7 Details CI Git-Pages Main / Build & Push Helm chart (push) Successful in 51s Details CI Git-Pages Main / Report Summary (push) Successful in 6s Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 1m40s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m48s Details CI Git-Pages Main / Config load (push) Successful in 22s Details CI Main / Config load (push) Successful in 24s Details CI Main / Latest versio (push) Successful in 25s Details CI Git-Pages Main / Latest version (push) Successful in 24s Details CI Git-Pages Main / GitOps (push) Failing after 20s Details ci-docker-build-push Docker push 0.2.27 Details CI Main / Build & Push Docker (push) Successful in 41s Details CI Main / GitOps (push) Failing after 18s Details CI Main / Move provider version tag (push) Has been skipped Details CI Main / Report Summary (push) Successful in 6s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #39	2026-06-22 11:14:50 +03:00
niko	9f9af398cc	clean (#38 ) CI Git-Pages Main / Config load (push) Successful in 24s Details CI Main / Config load (push) Successful in 26s Details CI Git-Pages Main / Latest version (push) Successful in 22s Details CI Main / Latest versio (push) Successful in 23s Details ci-helm-build-push Helm push 0.1.6 Details CI Git-Pages Main / Build & Push Helm chart (push) Successful in 50s Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 1m44s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m58s Details ci-docker-build-push Docker push 0.2.26 Details CI Main / Build & Push Docker (push) Successful in 43s Details CI Main / GitOps (push) Failing after 21s Details CI Main / Move provider version tag (push) Has been skipped Details CI Main / Report Summary (push) Successful in 6s Details CI Git-Pages Main / GitOps (push) Failing after 18s Details CI Git-Pages Main / Report Summary (push) Successful in 5s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #38	2026-06-22 10:55:58 +03:00
niko	bc6bb78973	Feature/gitops (#37 ) CI Main / Load example-gitea-env.conf to pipeline env (push) Successful in 34s Details CI Git-Pages Main / Load git-pages.gitea-env.conf to pipeline env (push) Successful in 34s Details CI Main / Check existing artifact (push) Successful in 22s Details CI Git-Pages Main / Check existing artifact (push) Successful in 21s Details ci-helm-build-push Helm push 0.1.5 Details CI Git-Pages Main / Build & Push Helm chart (push) Successful in 48s Details unit-tests Bats test report Details CI Main / Bats tests (push) Successful in 1m34s Details acc-tests Cucumber test report Details CI Main / Cucumber tests (push) Successful in 1m45s Details CI Git-Pages Main / Update chart to the cluster (push) Failing after 0s Details ci-docker-build-push Docker push 0.2.25 Details CI Git-Pages Main / Report Summary (push) Successful in 7s Details CI Main / Build & Push Docker (push) Successful in 44s Details CI Main / GitOps (push) Failing after 22s Details CI Main / Move provider version tag (push) Has been skipped Details CI Main / Report Summary (push) Successful in 6s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #37	2026-06-22 10:37:15 +03:00
niko	a5947551d4	Fix/gitea commit status naming (#36 ) CI Main / Load example-gitea-env.conf to pipeline env (push) Successful in 22s Details CI Main / Check existing artifact (push) Successful in 20s Details CI Git-Pages Main / Load git-pages.gitea-env.conf to pipeline env (push) Successful in 45s Details CI Git-Pages Main / Check existing artifact (push) Successful in 31s Details ci-helm-build-push Helm push 0.1.4 Details CI Main / Cucumber tests (push) Successful in 1m10s Details CI Git-Pages Main / Build & Push Helm chart (push) Successful in 49s Details CI Git-Pages Main / Report Summary (push) Successful in 5s Details CI Main / Bats tests (push) Successful in 1m34s Details ci-docker-build-push Docker push 0.2.21 Details CI Main / Build & Push Docker (push) Successful in 48s Details CI Main / Report Summary (push) Successful in 6s Details CI Main / Move provider version tag (push) Successful in 14s Details CI Feature / Load example-gitea-env.conf to pipeline env (push) Successful in 33s Details acc-tests Cucumber test report Details CI Feature / Cucumber tests (push) Successful in 1m23s Details unit-tests Bats test report Details CI Feature / Bats tests (push) Successful in 1m34s Details CI Feature / Report Summary (push) Successful in 5s Details Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #36	2026-06-21 08:43:32 +03:00