POC: test reusable workflow job visibility in Gitea Actions (#5)

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

tmp/0006-ci-feature-example/roles-and-files.md

@@ -0,0 +1,449 @@
+# ci-engine.yml — moottori ja consumerin job-tiedostot
+
+> **Tila:** DRAFT — työstettävä esimerkki, ei lopullinen suunnitelma.
+> **Liittyy:** ticket 0006, [analysis/ci-flow-values-vs-native-config.md](../../docs/analysis/ci-flow-values-vs-native-config.md)
+
+Esimerkkiprojekti: `temperature-store` (Java/Maven-mikropalvelu)
+
+Provider (`gitea-ci-library`) tarjoaa **vain yhden tiedoston**: `ci-engine.yml`.
+Consumer tuo omat job-tiedostonsa ja datansa. Moottori päättelee itse mitä ajaa.
+
+---
+
+## Tiedostot ja roolit
+
+```
+temperature-store/                          ← CONSUMER
+├── .gitea/workflows/
+│   └── ci.yml                              ← [A] Kutsuja: molemmat jobit (feature + master) yhdessä
+├── ci-flow-values.yaml                     ← [B] Projektin data — uniikki per projekti
+└── pom.xml
+
+gitea-ci-library/                           ← PROVIDER (= MOOTTORI)
+├── .gitea/workflows/
+│   └── ci-engine.yml                       ← [C] AINOA workflow — kaikki pipelinetyypit
+├── scripts/
+│   ├── report-status.sh
+│   ├── dispatch-workflow.sh
+│   ├── push-reports.sh
+│   └── tag-commit.sh
+└── ci-flow-values.yaml                     ← Provider-testaus (dogfood — kirjasto testaa itsensä)
+```
+
+**Roolit:**
+
+| Tiedosto | Omistaja | Rooli |
+|----------|----------|-------|
+| `ci-engine.yml` | **Provider** | Moottori: build-logiikka, konffaus, komennot |
+| `ci.yml` | **Consumer** | Kutsuja: molemmat jobit yhdessä tiedostossa, `if:` valitsee |
+| `ci-flow-values.yaml` | **Consumer** | Data: ekosysteemi, docker-nimi, test-flow jne |
+| `scripts/*.sh` | **Provider** | Jaetut työkalut |
+
+---
+
+## [A] Consumerin `.gitea/workflows/ci.yml` — rooli: **kutsuja**
+
+```yaml
+# temperature-store/.gitea/workflows/ci.yml
+#
+# Rooli: KUTSUJA.
+# - Valitsee branchin perusteella oikean jobin (feature / master)
+# - Välittää KONTIT moottorille (moottori ei tunne yhtään konttia)
+# - Välittää config-filen polun moottorille
+
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  workflow_dispatch:
+
+jobs:
+  feature:
+    if: github.ref != 'refs/heads/master'
+    uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
+    secrets: inherit
+    with:
+      config-file: ci-flow-values.yaml
+      maven-image: maven:3.9-eclipse-temurin-21   # ← Consumer omistaa kontit
+
+  master:
+    if: github.ref == 'refs/heads/master'
+    uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
+    secrets: inherit
+    with:
+      config-file: ci-flow-values.yaml
+      maven-image: maven:3.9-eclipse-temurin-21
+      dind-image: docker:26-dind                   # ← Master tarvitsee DinD:n
+```
+
+**Mitä tässä tapahtuu:**
+1. Push mihin tahansa branchiin → `ci.yml` triggeröityy
+2. `if: github.ref != 'refs/heads/master'` → `feature`-job
+3. `if: github.ref == 'refs/heads/master'` → `master`-job
+4. Molemmat kutsuvat samaa moottoria (`ci-engine.yml@v1`) samoilla parametreilla
+5. Moottori päättelee itse branchista mitä pipelinea ajaa
+
+**Miksi yksi tiedosto, kaksi jobia:**
+- Yksi paikka katsoa mitä CI tekee — `ci.yml` on koko projektin CI-määrittely
+- `if:`-ehto on riittävä erottelemaan featuren ja masterin
+- Kopioitavissa sellaisenaan — consumer ei muokkaa mitään
+
+---
+
+## [B] Consumerin `ci-flow-values.yaml` — rooli: **projektidata**
+
+```yaml
+# temperature-store/ci-flow-values.yaml
+#
+# Rooli: DATA ("mikä tämä projekti on, mitä se tarvitsee")
+# Tämä tiedosto on jokaisessa projektissa ERI.
+# Kaikki non-secret-arvot tänne. Tokenit → Gitea org secrets.
+
+build:
+  ecosystem: maven           # maven | gradle | npm — moottori valitsee kontin ja komennot
+
+docker:
+  registry: gitea
+  imageName: temperature-store
+
+sonarqube:
+  url: https://sonar.example.com
+  projectKey: temperature-store
+
+deployment:
+  projectFolder: microservices
+  fileName: values-{.environment}.yaml
+  property: container.version
+
+test-flow:
+  - deploy: development
+    wait: true
+  - test:
+      name: "integration fast"
+      environment: integration
+      repo: tests/integration
+      workflow: test.yml
+      ref: main
+      tags: "@temperature and not @slow"
+```
+
+**Mitä `ci-engine.yml` lukee tästä (MVP, tiketti 0006):**
+- `build.ecosystem` — määrittää kontin ja komennot
+
+**Non-secret vs secret:**
+- Tänne: ekosysteemi, image-nimi, URL:t, test-flow — versioitavaa
+- Gitea org secrets: `GITEA_TOKEN`, `SONAR_TOKEN`, `DEPLOY_TOKEN` — salaisuudet
+
+---
+
+## [C] Providerin `ci-engine.yml` — rooli: **moottori**
+
+Providerin **ainoa** workflow. Moottori koostuu kolmesta kerroksesta:
+
+| Kerros | Mistä tulee | Sisältö |
+|--------|-------------|---------|
+| **Kontit** | `with:` parametrit consumerilta | `maven-image`, `dind-image`, … — moottori ei tunne yhtään konttia |
+| **Pipeline runko** | `ci-engine.yml` sisäinen | Feature-skeleton: start → test → coverage → end<br>Master-skeleton: start → build → deploy → [test-flow] → end |
+| **Test plan + data** | `ci-flow-values.yaml` | `build.ecosystem` → komennot<br>`test-flow[]` → test plan (vain master)<br>`docker.*`, `deployment.*` (vain master) |
+
+```yaml
+# gitea-ci-library/.gitea/workflows/ci-engine.yml
+#
+# MOOTTORI — kolme kerrosta:
+#   1. Kontit:         ${{ inputs.maven-image }} jne (consumerilta)
+#   2. Pipeline runko: job-graafi erikseen featurelle ja masterille (täällä)
+#   3. Data:           ci-flow-values.yaml → ekosysteemi, test plan, docker (consumerilta)
+
+name: CI Engine
+
+on:
+  workflow_call:
+    inputs:
+      config-file:
+        required: true
+        type: string                            # ← Polku ci-flow-values.yaml:aan
+      maven-image:                              # ← KONTTI: consumerilta
+        required: false
+        type: string
+      dind-image:                               # ← KONTTI: consumerilta (vain master)
+        required: false
+        type: string
+      node-image:                               # ← KONTTI: consumerilta (vain npm)
+        required: false
+        type: string
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ═══════════════════════════════════════════════════════════════
+  #  YHTEINEN: konfiguraation luku (data-kerros)
+  #  Raportoi: pending → config luettu → success
+  # ═══════════════════════════════════════════════════════════════
+  start:
+    runs-on: ubuntu-latest
+    outputs:
+      ecosystem: ${{ steps.read-config.outputs.ecosystem }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Report pipeline start
+        run: |
+          bash scripts/report-status.sh \
+            "pending" "Pipeline starting" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/start"
+
+      - name: Read project config
+        id: read-config
+        run: |
+          ECOSYSTEM=$(yq '.build.ecosystem' "${{ inputs.config-file }}")
+          [ -z "$ECOSYSTEM" ] || [ "$ECOSYSTEM" = "null" ] && \
+            echo "ERROR: build.ecosystem not set" >&2 && exit 1
+          echo "ecosystem=$ECOSYSTEM" >> $GITHUB_OUTPUT
+
+      - name: Report pipeline started
+        if: success()
+        run: |
+          bash scripts/report-status.sh \
+            "success" "Pipeline started" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/start"
+
+      - name: Report start failure
+        if: failure()
+        run: |
+          bash scripts/report-status.sh \
+            "failure" "Pipeline start failed" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/start"
+
+  # ═══════════════════════════════════════════════════════════════
+  #  FEATURE-SKELETON: testit + coverage
+  #  Ajetaan kun github.ref != refs/heads/master
+  #  Jokainen steppi raportoi: alussa pending, lopussa success/failure
+  # ═══════════════════════════════════════════════════════════════
+  unit-test:
+    needs: start
+    if: github.ref != 'refs/heads/master'
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ inputs.maven-image }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Report unit-test start
+        run: |
+          bash scripts/report-status.sh \
+            "pending" "Unit tests running" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/unit-test"
+
+      - name: Run unit tests
+        id: test
+        env:
+          ECOSYSTEM: ${{ needs.start.outputs.ecosystem }}
+        run: |
+          case "$ECOSYSTEM" in
+            maven|gradle) mvn test ;;
+            npm)          npm test ;;
+          esac
+
+      - name: Report unit-test success
+        if: success()
+        run: |
+          bash scripts/report-status.sh \
+            "success" "Unit tests passed" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/unit-test"
+
+      - name: Report unit-test failure
+        if: failure()
+        run: |
+          bash scripts/report-status.sh \
+            "failure" "Unit tests failed" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/unit-test"
+
+  code-coverage:
+    needs: [start, unit-test]
+    if: github.ref != 'refs/heads/master'
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ inputs.maven-image }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Report coverage start
+        run: |
+          bash scripts/report-status.sh \
+            "pending" "Coverage running" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/code-coverage"
+
+      - name: Run coverage
+        id: coverage
+        env:
+          ECOSYSTEM: ${{ needs.start.outputs.ecosystem }}
+        run: |
+          case "$ECOSYSTEM" in
+            maven)  mvn jacoco:report ;;
+            gradle) gradle jacocoTestReport ;;
+            npm)    npm run coverage ;;
+          esac
+
+      - name: Report coverage success
+        if: success()
+        run: |
+          bash scripts/report-status.sh \
+            "success" "Coverage report generated" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/code-coverage"
+
+      - name: Report coverage failure
+        if: failure()
+        run: |
+          bash scripts/report-status.sh \
+            "failure" "Coverage failed" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/code-coverage"
+
+  # ═══════════════════════════════════════════════════════════════
+  #  MASTER-SKELETON: build + deploy + test plan (tiketti 0009)
+  #  github.ref == refs/heads/master
+  #  Kontti: ${{ inputs.maven-image }} + ${{ inputs.dind-image }}
+  #  Test plan: ci-flow-values.yaml → test-flow[]
+  # ═══════════════════════════════════════════════════════════════
+  # build-container:
+  #   needs: start
+  #   if: github.ref == 'refs/heads/master'
+  #   container:
+  #     image: ${{ inputs.dind-image }}           ← KONTTI consumerilta
+  #   ...
+  #
+  # deploy:
+  #   needs: build-container
+  #   if: github.ref == 'refs/heads/master'
+  #   ...lukee deployment.* configista...
+  #
+  # test-flow:
+  #   needs: deploy
+  #   if: github.ref == 'refs/heads/master'
+  #   ...lukee test-flow[] configista...          ← TEST PLAN configista
+
+  # ═══════════════════════════════════════════════════════════════
+  #  LOPETUS: kaikille yhteinen
+  #  Raportoi: pending → aggregoi tulokset → success/failure
+  # ═══════════════════════════════════════════════════════════════
+  end:
+    needs: [unit-test, code-coverage]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Report pipeline ending
+        run: |
+          bash scripts/report-status.sh \
+            "pending" "Pipeline finishing" \
+            "$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER" \
+            "ci/end"
+
+      - name: Report final status
+        run: |
+          BUILD_URL="$GITEA_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_NUMBER"
+          if [ "${{ needs.unit-test.result }}" = "success" ] && \
+             [ "${{ needs.code-coverage.result }}" = "success" ]; then
+            STATE="success"; DESC="All checks passed"
+          else
+            STATE="failure"; DESC="Some checks failed"
+          fi
+          bash scripts/report-status.sh "$STATE" "$DESC" "$BUILD_URL" "ci/end"
+```
+
+**Moottorin kolme kerrosta käytännössä:**
+
+1. **Kontit** (consumerilta `with:` → moottori `inputs:` → job `container.image`)
+   - Moottori ei sisällä yhtään kontti-imagea
+   - Consumer päättää versiot: `maven:3.9-eclipse-temurin-21`
+
+2. **Pipeline runko** (moottorin sisäinen job-graafi)
+   - `if: github.ref != 'refs/heads/master'` → feature-skeleton
+   - `if: github.ref == 'refs/heads/master'` → master-skeleton (myöhemmät tiketit)
+
+3. **Data** (`ci-flow-values.yaml`)
+   - `build.ecosystem` → mitä komentoja ajetaan
+   - `test-flow[]` → test plan (vain master, tiketti 0009)
+
+**Mitä tässä EI ole (myöhemmät tiketit):**
+- `push-reports.sh` — raporttien julkaisu MinIO:hon (tiketti 0013)
+- `isContainerBuild()` / kontin buildaus (tiketti 0009)
+- SonarQube quality gate (tiketti 0009)
+- Test flow -ketjutus `test-flow[]`:sta (tiketti 0008)
+
+---
+
+## Yhteenveto
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ CONSUMER: temperature-store                                          │
+│                                                                      │
+│  ci.yml                         ci-flow-values.yaml                  │
+│  ┌──────────────────────────┐   ┌────────────────────────┐           │
+│  │ jobs:                    │   │ build:                 │           │
+│  │  feature (if !master) ───┼─┐ │   ecosystem: maven     │           │
+│  │   with:                  │ │ │ docker:                │           │
+│  │    config-file + kontit  │ │ │   imageName: ...       │           │
+│  │                          │ │ │ test-flow: [...]       │           │
+│  │  master  (if master) ────┼─┤ └────────────────────────┘           │
+│  │   with:                  │ │                                       │
+│  │    config-file + kontit  │ │                                       │
+│  └──────────────────────────┘ │                                       │
+└───────────────────────────────┼───────────────────────────────────────┘
+                                │ with: kontit + config-file
+                                ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│ PROVIDER: gitea-ci-library  (ci-engine.yml)                          │
+│                                                                      │
+│  Kerros 1: KONTIT (consumerilta)                                     │
+│  ┌──────────────────────────────────────────┐                        │
+│  │ inputs: maven-image, dind-image, ...     │                        │
+│  └──────────────────────────────────────────┘                        │
+│                                                                      │
+│  Kerros 2: PIPELINE RUNKO (moottorin sisäinen)                       │
+│  ┌──────────────────────────────────────────┐                        │
+│  │ FEATURE-SKELETON         MASTER-SKELETON │                        │
+│  │ start ──────────────────── start         │                        │
+│  │   ↓                          ↓           │                        │
+│  │ unit-test                 build-container│                        │
+│  │   ↓                          ↓           │                        │
+│  │ code-coverage             deploy         │                        │
+│  │   ↓                          ↓           │                        │
+│  │ end                       test-flow[] ───│── Kerros 3: TEST PLAN  │
+│  │                             ↓            │                        │
+│  │                           end            │                        │
+│  └──────────────────────────────────────────┘                        │
+│                                                                      │
+│  Kerros 3: DATA (ci-flow-values.yaml)                                │
+│  ┌──────────────────────────────────────────┐                        │
+│  │ ecosystem → komennot                     │                        │
+│  │ test-flow[] → test plan (vain master)    │                        │
+│  │ docker.*, deployment.*  (vain master)    │                        │
+│  └──────────────────────────────────────────┘                        │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Päätöstaulukko
+
+| Asia | Sijainti | Kerros |
+|------|----------|:--:|
+| Kontit (`maven-image`, `dind-image`) | Consumer (`ci.yml` `with:`) | 1 |
+| Pipeline runko (job-graafi) | Provider (`ci-engine.yml`) | 2 |
+| `build.ecosystem` → komennot | Consumer (`ci-flow-values.yaml`) | 3 |
+| `test-flow[]` → test plan | Consumer (`ci-flow-values.yaml`) | 3 |
+| `docker.*`, `deployment.*` | Consumer (`ci-flow-values.yaml`) | 3 |
+| Skriptit | Provider (`scripts/`) | — |
+| Tokenit, salasanat | Gitea org secrets | — |

tmp/data-flow-design.md

@@ -0,0 +1,282 @@
+# Data flow — periaatetaso
+
+> Tila: DRAFT — kevyt suunnitteludokumentti, muokataan tarpeen mukaan.
+> Ei ADR. Ei normatiivinen. Kuvaa periaatteen, ei implementaatiota.
+>
+> Lähde: [docs/design-rationale.md](../docs/design-rationale.md) — erityisesti periaatteet 1 (commit-status), 3 (konfiguraatio repossa), 5 (raportit MinIO:ssa) ja 7 (cross-repo traceability).
+
+## Tarkoitus
+
+Selventää **kuka omistaa mitä datan** ja **miten se liikkuu** consumer → provider → Gitea -ketjussa.
+
+**Ydinperiaate:** Branch-päätös on consumerin vastuulla. Provider on branch-agnostinen — se saa polun config-tiedostoon ja suorittaa sen määrittämän pipelinen. Consumer valitsee kumman jobin ja minkä pipeline-as-conf -tiedoston ajetaan; engine lukee vain sen mitä `with:` välittää.
+
+---
+
+## Roolit ja tiedostot
+
+| Rooli | Tiedosto(t) | Mitä tietää / mitä tekee |
+|-------|-------------|--------------------------|
+| **Consumer** | `ci.yml` | Trigger, branch (`if:`), valitsee pipeline-as-conf -tiedoston ja kontit, kutsuu engineä `uses:` |
+| **Consumer** | `*-conf.yaml` (pipeline-as-conf) | Projektin data: mitä pipeline ajaa (ekosysteemi, test-flow, docker jne.) — versioitu repossa |
+| **Provider** | `ci-engine.yml` | Gitea workflow (`.gitea/workflows/`); `workflow_call` only; pipeline-määrittely |
+| **Provider** | jaettu suorituskoodi | Uudelleenkäytettävä logiikka — **ei** Gitea workflow; engine kutsuu steppien sisällä |
+| **Gitea org** | secrets | Tokenit, salasanat — ei koskaan repoon; `secrets: inherit` |
+| **Gitea org** | variables (kapea poikkeus) | Org-laajuiset infra-endpointit (esim. `MINIO_BASE_URL`, `GITEA_SERVER_URL`) — valinnainen shortcut |
+
+### Secrets vs. variables vs. conf
+
+Kolmitasoinen jako — helppo sääntö kehittäjälle:
+
+| Tyyppi | Missä | Esimerkkejä |
+|--------|-------|-------------|
+| **Secrets** | Gitea org secrets | `GITEA_TOKEN`, `SONAR_TOKEN`, `DEPLOY_TOKEN` |
+| **Projektidata** | Consumer `*-conf.yaml` | `build.ecosystem`, `docker.imageName`, `sonarqube.*`, `test-flow`, `deployment.*` |
+| **Org-infra** | Gitea org variables (valinnainen) | `MINIO_BASE_URL`, `GITEA_SERVER_URL` — sama kaikille, harvoin muuttuu |
+
+1. Salainen? → org secret
+2. Projektin asia? → conf-tiedosto (periaate 3)
+3. Koko orgin sama infra-endpoint? → org variable, vain jos et halua toistaa sitä jokaisessa confissa
+
+Org variables on **kapea poikkeus** infra-endpointeille — ei korvike conf-tiedostolle. Projektikohtaiset arvot (docker-nimi, test-flow, Sonar projectKey) kuuluvat aina confiin.
+
+### Pipeline vs. jaettu suorituskoodi
+
+Kaksi eri artefaktityyppiä provider-puolella:
+
+```
+Provider (gitea-ci-library)
+├── .gitea/workflows/ci-engine.yml   ← pipeline (Gitea workflow, consumer kutsuu uses:)
+└── jaettu suorituskoodi             ← uudelleenkäytettävä logiikka (EI .gitea/workflows/:ssa)
+
+Consumer (mikropalvelu)
+├── .gitea/workflows/ci.yml          ← ohut kutsuja (Gitea workflow)
+└── ci-feature.yaml                  ← data (ei suoritettavaa koodia)
+```
+
+- **Pipeline-tiedosto** (`ci-engine.yml`) on Gitean workflow — sen täytyy olla `.gitea/workflows/`:ssa, jotta `uses:` löytää sen.
+- **Jaettu suorituskoodi** on providerin omistamaa logiikkaa (status-raportointi, raporttien julkaisu, dispatch jne.). Consumer ei kopioi sitä — korjaus provider-repoon, kaikki consumerit hyötyvät `@v1`:stä.
+- **Toteutus** (kieli, tiedostomuoto, sijainti repossa) ei kuulu tähän dokumenttiin.
+
+### Binding: consumer → provider
+
+Ei dynaamista löytämistä — consumer kovakoodaa `uses:`-polun:
+
+```
+org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
+```
+
+| Vaihe | Mitä tapahtuu |
+|-------|---------------|
+| 1 | Push consumer-repoon → Gitea lukee consumerin `ci.yml` |
+| 2 | `if:` valitsee jobin |
+| 3 | `uses:` → Gitea hakee provider-reposta `ci-engine.yml` annetulla `@ref`:llä |
+| 4 | Provider vaatii `on: workflow_call` |
+| 5 | `with:` → providerin `inputs`; checkout = **consumer-repo** (lähdekoodi + config-file) |
+| 6 | Engine tuo provider-artefaktit runnerille tagilla `@v1` |
+
+**`@ref`:** `@v1` (tag providerin main-haarassa). Pinnaa engine-version — consumer ei seuraa providerin kehityshaaraa.
+
+### Dogfood-erikoistapaus
+
+`gitea-ci-library` sisältää sekä consumer- että provider-tiedostot samassa repossa. **Roolit eivät muutu** — vain fyysinen sijainti on poikkeuksellinen.
+
+**Dogfood-sääntö:** Consumerin `ci.yml` viittaa provideriin **samalla `uses:`-polulla** kuin mikä tahansa ulkoinen mikropalvelu. Ei suhteellista polkua (`./.gitea/workflows/...`).
+
+```
+Ulkoinen mikropalvelu (puhdas consumer)     gitea-ci-library (dogfood)
+┌──────────────────────────────┐            ┌──────────────────────────────┐
+│ ci.yml                       │            │ ci.yml            ← consumer │
+│ ci-feature.yaml              │            │ ci-feature.yaml   ← consumer │
+│ ci-main.yaml                 │            │ ci-main.yaml      ← consumer │
+│                              │            │ ci-engine.yml     ← provider │
+│ uses: org/gitea-ci-library/  │            │ uses: org/gitea-ci-library/  │
+│   .../ci-engine.yml@v1       │            │   .../ci-engine.yml@v1       │
+└──────────────────────────────┘            │ suorituskoodi     ← provider │
+                                            └──────────────────────────────┘
+```
+
+Ulkoinen mikropalvelu on puhdas consumer (vain `ci.yml` + conf-tiedostot). Provider tulee `uses:`-viittauksella kirjastosta — dogfood mukaan lukien.
+
+---
+
+## Kuusi data-virtaa
+
+```
+1. CONSUMER → PROVIDER (push)
+   Consumer tietää branchin → valitsee jobin + config-file + kontit.
+   Provider vastaanottaa, ei tulkitse branchia.
+
+   ci.yml ──with: config-file + kontti-imaget──► ci-engine.yml
+
+2. PROVIDER SISÄINEN
+   Engine lukee config-file-polun → rakentaa steppigraafin → ajaa stepit.
+   Mitä pipelinea ajetaan johtuu conf-tiedostosta, ei branch-tiedosta providerissa.
+
+3. PROVIDER → GITEA (commit-status)
+   Jokainen steppi raportoi tilansa commitille (Gitea REST API).
+   Uniikki key per vaihe (periaate 1).
+
+4. GITEA → CONSUMER (feedback loop)
+   Consumerin commitille kertyy statuksia jokaisesta stepistä.
+   Kehittäjä näkee suoraan commitilta: mitä ajettiin, menikö läpi.
+   url-kenttä linkittää raportteihin / buildiin.
+
+5. PROVIDER → MinIO → GITEA (raportit)
+   Steppi generoi raportin → julkaisu MinIO:hon
+   → deterministinen URL → URL liitetään commit-statusviestiin
+   (periaate 5).
+
+6. CROSS-REPO KETJU
+   Mikropalvelu-commit (root) → dispatch → toinen repo → status takaisin root-committiin.
+   root-build kulkee inputs-parametrina koko ketjun läpi (periaate 7).
+```
+
+---
+
+## Silmukka
+
+```
+Consumer pushaa koodia
+       │
+       ├── feature-branch → ci.yml valitsee feature-jobin
+       │                      with: config-file: ci-feature.yaml + kontit
+       │
+       └── main-branch     → ci.yml valitsee main-jobin
+                              with: config-file: ci-main.yaml + kontit
+       │
+       ▼  uses:
+┌──────────────────────────────────────────────┐
+│  ci-engine.yml (provider, branch-agnostinen) │
+│  Lukee config-file → steppigraafi → stepit  │
+│                                              │
+│  config-file → steppigraafi → stepit ajetaan │
+│       │            │            │            │
+│       └────────────┴────────────┘            │
+│                    │                         │
+│                    ▼                         │
+│         jokainen steppi → status commitille  │
+│                    │                         │
+│         (raportit) → MinIO → url statusiin   │
+└──────────────────┬───────────────────────────┘
+                   │ POST /api/v1/repos/.../statuses/{sha}
+                   ▼
+┌──────────────────────────────────────────────┐
+│  Gitea commit                                │
+│  ├── ci/start        ✓                       │
+│  ├── ci/unit-test    ✓  (url → raportti)    │
+│  ├── ci/code-coverage ✓                      │
+│  └── ci/end          ✓                       │
+└──────────────────────────────────────────────┘
+```
+
+### Cross-repo ketju (periaate 7)
+
+```
+Mikropalvelu (root-commit abc123)
+       │
+       ├── build + deploy ──dispatch──► Helm-repo (commit def456)
+       │                                      │
+       │                                      ├── status → oma commit
+       │                                      └── status → root abc123
+       │
+       └── test-flow ──dispatch──► Testi-repo (commit ghi789)
+                                          │
+                                          ├── status → oma commit
+                                          ├── status → root abc123
+                                          └── status → Helm def456
+
+root-build (abc123) kulkee workflow_dispatch inputs -parametrina koko ketjun läpi.
+```
+
+---
+
+## Omistajuus
+
+| Mitä | Omistaja | Miten liikkuu |
+|------|----------|---------------|
+| Branch-päätös | Consumer | `ci.yml` `if:` |
+| Mitä pipelinea ajetaan | Consumer | Valittu pipeline-as-conf -tiedosto |
+| Pipeline-runko (steppigraafi) | Provider | Engine rakentaa confista |
+| Kontit (maven, dind…) | Consumer | `with:` → provider `inputs` |
+| Projektidata (ecosystem, test-flow…) | Consumer | pipeline-as-conf repossa |
+| Moottori + jaettu suorituskoodi | Provider | `ci-engine.yml` + provider-logiikka |
+| Tokenit, salasanat | Gitea org | secrets — `secrets: inherit` |
+| Org-laajuiset infra-endpointit | Gitea org | variables (valinnainen poikkeus) |
+
+---
+
+## Consumer-sopimus
+
+`ci.yml` on **mahdollisimman lyhyt**:
+
+- Kaksi jobia (feature / main) tai vastaava `if:`-jaottelu
+- Sama engine, eri `config-file` per job
+- Kontit consumerin `with:`:ssa — provider ei sisällä image-versioita
+- `secrets: inherit`
+
+```yaml
+# Esimerkki — kovakoodattu provider-polku (provider main-haarassa, tag @v1)
+
+jobs:
+  feature:
+    if: gitea.ref != 'refs/heads/main'
+    uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
+    secrets: inherit
+    with:
+      config-file: ci-feature.yaml
+      maven-image: ...
+
+  main:
+    if: gitea.ref == 'refs/heads/main'
+    uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
+    secrets: inherit
+    with:
+      config-file: ci-main.yaml
+      maven-image: ...
+      dind-image: ...
+```
+
+---
+
+## Provider-sopimus
+
+- Vain `workflow_call` — ei omaa triggeriä
+- Pakollinen input: `config-file` (polku repossa)
+- Valinnaiset: kontti-imaget consumerilta
+- Ei branch-ehtoja provider-tiedostossa — consumer on jo päättänyt mitä ajetaan conf-valinnalla
+- Lukee consumer-datan (lähdekoodi + config-file) ja tuo provider-artefaktit runnerille
+- Lukee conf → suorittaa → raportoi
+
+### Mitä engine EI tiedä
+
+- Onko kyseessä feature vai main — consumer on jo valinnut conf-tiedoston
+- Mitä komentoja ajetaan — ne tulevat conf-tiedostosta
+- Mitä kontteja on käytössä — consumer kertoo `with:`:ssa
+
+Engine on branch-agnostinen suorittaja. Consumer omistaa päätökset ja datan.
+
+---
+
+## Esimerkki: gitea-ci-library (dogfood)
+
+Tämä projekti on sekä provider että consumer. Roolit pysyvät samoina kuin ulkoisella mikropalvelulla — **sama `uses:`-viittaus** (`@v1`), ei suhteellista polkua. Consumer-sopimuksen esimerkki pätee sellaisenaan.
+
+| Rooli | Tiedosto | Mitä tekee |
+|-------|----------|------------|
+| Consumer | `ci.yml` | Tietää branchin, valitsee jobin ja conf-tiedoston, syöttää kontit |
+| Consumer | `ci-feature.yaml`, `ci-main.yaml` | Pipeline-as-conf — projektin data per pipeline-tyyppi |
+| Provider | `ci-engine.yml` | Pipeline-määrittely; lukee config-file:n, rakentaa steppigraafin, ajaa, raportoi |
+| Provider | jaettu suorituskoodi | Status, raportit, dispatch — toteutus avoin |
+
+---
+
+## Mitä tämä EI ota kantaa
+
+- Moottorin toteutuskieli ja -muoto (bash, TypeScript, Python, Go — erillinen päätös)
+- Nykyiset skriptitiedostot ja niiden rajapinnat (mahdollinen redesign)
+- Raporttien julkaisumekanismi (miten MinIO:hon — toteutus avoin)
+- Provider-artefaktien toimitus runnerille (checkout, bundle, inline — toteutus myöhemmin)
+- Main-skeletonin yksityiskohdat (build, deploy, test-flow)
+- Conf-tiedoston skeema / kentät (→ `config-model.md`)
+- Cross-repon workflow-tiedostojen sisältö

tmp/git-pages.yaml

@@ -0,0 +1,259 @@
+# DEPRECATED — käytä Helm chartia: git-pages/
+#   helm upgrade --install git-pages ./git-pages -n git-pages -f dev-values.yaml
+#
+# git-pages — k3s homelab (Codeberg git-pages)
+#
+# Yksi apex index-site (pages.helm-dev.../.index). Sisältö Gitea-poluissa:
+#   {owner}/{repo}/reports/{sha8}/index.html
+#
+# Julkaisu (CI → Traefik → git-pages):
+#   PATCH https://pages.helm-dev.keskikuja.site/  Authorization: Basic publish:<token>
+#   Traefik basicAuth middleware — token K8s-secretissä (htpasswd)
+#   git-pages PAGES_INSECURE=1 takana — ei forge/DNS/Gitea write
+#
+# Secret (kerran, ennen ensimmäistä publishia):
+#   export GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 32)"
+#   kubectl -n git-pages create secret generic git-pages-publish-auth \
+#     --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")"
+#   # Sama arvo → Gitea Actions secret GIT_PAGES_PUBLISH_TOKEN
+#
+# Lukeminen: GET/HEAD julkinen (OIDC myöhemmin Traefikissä)
+#
+# URL-esimerkki:
+#   https://pages.helm-dev.keskikuja.site/niko/gitea-ci-library/reports/abc12345/index.html
+#
+# Image: codeberg.org/git-pages/git-pages:0.9.1
+# CI: GIT_PAGES_PUBLISH_URL=https://pages.helm-dev.keskikuja.site
+#     GIT_PAGES_PUBLISH_TOKEN → Gitea Actions secret
+
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+    app.kubernetes.io/component: pages-server
+
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: git-pages-config
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+data:
+  config.toml: |
+    log-format = "text"
+
+    [server]
+    pages = "tcp/:3000"
+    caddy = "-"
+    metrics = "tcp/:3002"
+
+    [storage]
+    type = "fs"
+
+    [storage.fs]
+    root = "/app/data"
+
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: git-pages-data
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 5Gi
+
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: git-pages
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+    app.kubernetes.io/component: pages-server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: git-pages
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: git-pages
+        app.kubernetes.io/component: pages-server
+    spec:
+      securityContext:
+        fsGroup: 1000
+      containers:
+        - name: git-pages
+          image: codeberg.org/git-pages/git-pages:0.9.1
+          imagePullPolicy: IfNotPresent
+          command:
+            - git-pages
+          args:
+            - -config
+            - /etc/git-pages/config.toml
+          env:
+            - name: PAGES_INSECURE
+              value: "1"
+          ports:
+            - name: http
+              containerPort: 3000
+              protocol: TCP
+            - name: metrics
+              containerPort: 3002
+              protocol: TCP
+          volumeMounts:
+            - name: config
+              mountPath: /etc/git-pages
+              readOnly: true
+            - name: data
+              mountPath: /app/data
+          readinessProbe:
+            tcpSocket:
+              port: http
+            initialDelaySeconds: 3
+            periodSeconds: 10
+          livenessProbe:
+            tcpSocket:
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 20
+          resources:
+            requests:
+              cpu: 50m
+              memory: 128Mi
+            limits:
+              cpu: 1000m
+              memory: 512Mi
+      volumes:
+        - name: config
+          configMap:
+            name: git-pages-config
+        - name: data
+          persistentVolumeClaim:
+            claimName: git-pages-data
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: git-pages
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/name: git-pages
+  ports:
+    - name: http
+      port: 3000
+      targetPort: http
+      protocol: TCP
+
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: git-pages-tls
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+spec:
+  secretName: git-pages-tls
+  dnsNames:
+    - pages.helm-dev.keskikuja.site
+  issuerRef:
+    name: letsencrypt-prod
+    kind: ClusterIssuer
+
+---
+# PATCH/PUT vaatii BasicAuth (publish-token). Ilman tokenia → 401.
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: git-pages-publish-auth
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+spec:
+  basicAuth:
+    secret: git-pages-publish-auth
+
+---
+# Julkinen luku: GET/HEAD. Julkaisu: PATCH/PUT + basicAuth (erillinen reitti).
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: git-pages
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+spec:
+  entryPoints:
+    - websecure
+  routes:
+    - match: >-
+        Host(`pages.helm-dev.keskikuja.site`) &&
+        (Method(`PATCH`) || Method(`PUT`))
+      kind: Rule
+      middlewares:
+        - name: git-pages-publish-auth
+      services:
+        - name: git-pages
+          port: 3000
+    - match: Host(`pages.helm-dev.keskikuja.site`) && (Method(`GET`) || Method(`HEAD`))
+      kind: Rule
+      services:
+        - name: git-pages
+          port: 3000
+  tls:
+    secretName: git-pages-tls
+
+---
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: https-redirect
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+spec:
+  redirectScheme:
+    scheme: https
+    permanent: true
+
+---
+# HTTP → HTTPS. Jätä /.well-known/acme-challenge/ pois — cert-manager HTTP-01 (web :80).
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: git-pages-http
+  namespace: git-pages
+  labels:
+    app.kubernetes.io/name: git-pages
+spec:
+  entryPoints:
+    - web
+  routes:
+    - match: >-
+        Host(`pages.helm-dev.keskikuja.site`) &&
+        !PathPrefix(`/.well-known/acme-challenge/`)
+      kind: Rule
+      middlewares:
+        - name: https-redirect
+      services:
+        - name: git-pages
+          port: 3000

tmp/gitea-pages.yaml

@@ -0,0 +1,162 @@
+# DEPRECATED — älä käytä. deadnews/gitea-pages vetää pages-branchin Giteasta (väärä suunta).
+# Käytä sen sijaan: tmp/git-pages.yaml (Codeberg git-pages, CI pushaa HTML:n).
+#
+# Gitea Pages — k3s homelab (standardimalli, kuten vikunja)
+#
+# Sovellus: HTTP :8000 — ei omaa ingressiä, ei ACME:ä, ei TLS:ää podissa.
+# Ulospäin: cert-manager Certificate → Traefik IngressRoute (websecure).
+#
+# Image: ghcr.io/deadnews/gitea-pages — vetää tiedostot Gitea API:sta.
+# Data flow: CI git push → Gitea (branch "pages") → pages-server lukee API:lla.
+#
+# URL: https://pages.helm-dev.keskikuja.site/{owner}/{repo}/reports/{sha8}/cucumber/...
+#
+# Secret = Gitea PAT (read repository).
+# POC: Secret inline alla (älä commitoi oikeaa tokenia).
+# Tuotanto: kubectl-snippet, Secret pois manifestista — PR:llä repoon.
+
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: gitea-pages
+  labels:
+    app.kubernetes.io/name: gitea-pages
+    app.kubernetes.io/component: pages-server
+
+# Tuotanto — Secret kubectl:lla (PAT Giteasta):
+#
+#   NS=gitea-pages
+#   export GITEA_PAGES_TOKEN='gitea_pat_...'
+#   kubectl create secret generic gitea-pages-secrets \
+#     --from-literal=gitea-api-token="$GITEA_PAGES_TOKEN" \
+#     -n $NS
+#
+#   kubectl apply -f tmp/gitea-pages.yaml   # ilman Secret-resurssia
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: gitea-pages-secrets
+  namespace: gitea-pages
+  labels:
+    app.kubernetes.io/name: gitea-pages
+type: Opaque
+stringData:
+  # POC: Gitea PAT read repository — täytä paikallisesti, älä commitoi
+  gitea-api-token: ""
+
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gitea-pages
+  namespace: gitea-pages
+  labels:
+    app.kubernetes.io/name: gitea-pages
+    app.kubernetes.io/component: pages-server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: gitea-pages
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: gitea-pages
+        app.kubernetes.io/component: pages-server
+    spec:
+      containers:
+        - name: gitea-pages
+          image: ghcr.io/deadnews/gitea-pages:v1.0.1
+          imagePullPolicy: IfNotPresent
+          ports:
+            - name: http
+              containerPort: 8000
+              protocol: TCP
+          env:
+            - name: GITEA_PAGES_SERVER
+              value: "https://gitea.app.keskikuja.site"
+            - name: GITEA_PAGES_BRANCH
+              value: "pages"
+            - name: GITEA_PAGES_ADDR
+              value: ":8000"
+            - name: GITEA_PAGES_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: gitea-pages-secrets
+                  key: gitea-api-token
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: http
+            initialDelaySeconds: 3
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 20
+          resources:
+            requests:
+              cpu: 50m
+              memory: 64Mi
+            limits:
+              cpu: 500m
+              memory: 256Mi
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: gitea-pages
+  namespace: gitea-pages
+  labels:
+    app.kubernetes.io/name: gitea-pages
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/name: gitea-pages
+  ports:
+    - name: http
+      port: 8000
+      targetPort: http
+      protocol: TCP
+
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: gitea-pages-tls
+  namespace: gitea-pages
+  labels:
+    app.kubernetes.io/name: gitea-pages
+spec:
+  secretName: gitea-pages-tls
+  commonName: pages.helm-dev.keskikuja.site
+  dnsNames:
+    - pages.helm-dev.keskikuja.site
+  issuerRef:
+    name: letsencrypt-prod
+    kind: ClusterIssuer
+
+---
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: gitea-pages
+  namespace: gitea-pages
+  labels:
+    app.kubernetes.io/name: gitea-pages
+spec:
+  entryPoints:
+    - websecure
+  routes:
+    - match: Host(`pages.helm-dev.keskikuja.site`)
+      kind: Rule
+      services:
+        - name: gitea-pages
+          port: 8000
+  tls:
+    secretName: gitea-pages-tls