pipeline siivous ja testikattavuuden nosto (#9)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #9
2026-06-14 03:26:44 +03:00
parent a1d1f1e5ab
commit c422825bf0
33 changed files with 779 additions and 302 deletions
@@ -3,7 +3,7 @@
 ## Päätös

 Provider (gitea-ci-library) ja Consumer (mikropalveluprojekti) erotetaan
-selkeällä rajapinnalla: `.gitea/workflows/ci-engine.yml` on ainoa pinta,
+selkeällä rajapinnalla: `.gitea/workflows/build-feature.yml` on ainoa pinta,
 jota consumer kutsuu.

 Kaikki muu providerin koodi (scriptit, git-pages-helmi, retention) on
@@ -18,7 +18,7 @@ riippuvuutta.
 # .gitea/workflows/ci.yml — consumerin repo
 jobs:
  ci:
-    uses: niko/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
+    uses: niko/gitea-ci-library/.gitea/workflows/build-feature.yml@v1
    secrets: inherit
 ```

@@ -44,13 +44,13 @@ Consumer:
 - Git-pages Helm-chartti
 - Retention sidecar
 - Scriptit ja työkalut (toteutus avoin, uudelleenkirjoitettavissa)
- Kaikki paitsi `ci-engine.yml` on sisäistä toteutusta ja voi muuttua
+- Kaikki paitsi `build-feature.yml` on sisäistä toteutusta ja voi muuttua
  ilman versiopäivitystä

 ## Periaatteet

-1. `ci-engine.yml` on **lukittu rajapinta**. Consumer kutsuu tätä, ei
-   koskaan providerin scriptejä suoraan. `ci-engine.yml` voi muuttua vain
+1. `build-feature.yml` on **lukittu rajapinta**. Consumer kutsuu tätä, ei
+   koskaan providerin scriptejä suoraan. `build-feature.yml` voi muuttua vain
   version vaihtuessa.
 2. Consumer omistaa pipeline-logiikan. Provider ei tiedä mitä testejä
   ajetaan, missä järjestyksessä tai millä työkaluilla.
@@ -0,0 +1,70 @@
+# 6. Directory ownership — provider vs consumer
+
+## Päätös
+
+Provider-repossa (`gitea-ci-library`) kansioiden omistajuus on seuraava:
+
+| Kansio / Tiedosto | Omistaja | Tyyppi |
+|-------------------|----------|--------|
+| `.gitea/workflows/` | Sekoitettu | Providerin reusable workflowt + consumerin pipeline |
+| `.gitea/workflows/gitea-env.conf` | Consumer | KEY=VALUE config |
+| `.gitea/scripts/` | Consumer | Consumer-skriptit |
+| `scripts/` | Provider | Providerin sisäiset työkalut |
+
+## Reusable workflowt — sijaintipakko
+
+Gitea Actions vaatii, että `uses:`-direktiivillä kutsuttavat workflowt
+ovat muodossa `{owner}/{repo}/.gitea/workflows/{file}@{ref}`.
+
+**Tämä on Gitea Actionsin asettama tekninen rajoite.** Toimivia
+polkuja ovat vain:
+
+```
+# ✅ kelpaa
+uses: org/repo/.gitea/workflows/file.yml@branch
+
+# ❌ eivät kelpaa
+uses: org/repo/workflows/file.yml@branch
+uses: org/repo/.gitea/workflows/path/file.yml@branch
+uses: org/repo/scripts/workflow.yml@branch
+```
+
+Tästä syystä providerin reusable workflowt (`config-provider.yml`,
+`build-feature.yml`) ovat samassa `.gitea/workflows/`-kansiossa consumerin
+pipeline-tiedostojen (`ci.yml`) kanssa.
+
+Erottelu on nimessä ja dokumentaatiossa, ei kansiorakenteessa:
+- `config-provider.yml`, `build-feature.yml` — providerin tarjoamia
+- `ci.yml` — consumerin omistamia
+
+## Providerin `scripts/` (juuressa)
+
+Providerin sisäiset työkalut. Consumer ei koskaan kutsu näitä suoraan —
+vain providerin workflowt kutsuvat tupla checkoutin kautta:
+`.ci/scripts/publish-git-pages.sh`.
+
+Consumerilla ei ole suoraa polkua näihin tiedostoihin ilman providerin
+workflowa.
+
+## Consumerin `.gitea/scripts/`
+
+Consumerin omat skriptit, osana consumerin pipeline-logiikkaa.
+Kutsutaan consumerin workflowista ilman tupla checkouttia:
+`.gitea/scripts/bats-report.sh`.
+
+## Consumerin `.gitea/workflows/gitea-env.conf`
+
+Consumerin konfiguraatiotiedosto. Providerin `config-provider.yml`
+lukee tämän ja muuntaa JSONiksi, mutta consumer omistaa sisällön.
+
+## Vaikutukset
+
+- Provider voi muuttaa `scripts/` ja `config-provider.yml` sisältöä
+  ilman consumerin hyväksyntää (versiovaihdon yhteydessä)
+- Consumer voi muuttaa `.gitea/workflows/ci.yml`,
+  `.gitea/workflows/build-feature.yml` ja `.gitea/scripts/` sisältöä
+  ilman providerin muutoksia
+- Providerin workflowt käyttävät `.ci/scripts/...` -polkua (tupla checkout)
+- Consumerin workflowt käyttävät `.gitea/scripts/...` -polkua (natiivi checkout)
+- Sekä provider että consumer jakavat `.gitea/workflows/` — tämä on
+  Gitea Actionsin tekninen rajoite, ei suunnittelupäätös
@@ -17,8 +17,7 @@ Tämä repo on käytännössä monorepo, jossa on kaksi itsenäistä osaa:

 ### 1. Juuri (`gitea-ci-library`)
 Provider-kirjasto: reusable workflowt, scriptit, ADRt, dokumentaatio.
-Rajapinta: `.gitea/workflows/ci-engine.yml` — ainoa pinta, jota consumerit
-kutsuvat.
+Consumer kutsuu `build-feature.yml`-workflowa `uses:`-direktiivillä.

 ### 2. `git-pages/` — oma kokonaisuus
 Helm-chartti Codeberg git-pagesille. Täysin itsenäinen — oma dokumentaatio,
@@ -32,7 +31,7 @@ Ohut ja yksiselitteinen:

 ```
 scripts/publish-git-pages.sh <report-dir>
-  → PATCH tar osoitteeseen PAGES_HOST
+  → PATCH tar osoitteeseen GIT_PAGES_URL
  → palauttaa BASE URL:n

 git-pages tarjoaa:
@@ -46,9 +45,9 @@ blob-arkkitehtuuri). Git-pages ei tiedä workflowista, scripteistä tai
 provider-logiikasta.

 ## Architecture (POC-tila)
- **Provider & Consumer -malli**: `ci-engine.yml` on lukittu rajapinta.
+- **Provider & Consumer -malli**: `build-feature.yml` on lukittu rajapinta.
  ADR 0005.
- **Raporttien hostaus**: git-pages Helm-chartilla (`git-pages/`).
+- **Raporttien hostaus**: git-pages Helm-chartilla (`git-pages/`), `GIT_PAGES_URL` määrittää perusosoitteen.
 - **Retention**: sidecar samassa podissa, HTTP API localhost:3000,
  Gitea API branch-check.
 - **Commit-status**: Gitea Actions näyttää automaattisesti. API vain
@@ -59,19 +58,19 @@ provider-logiikasta.

 | Path | Purpose |
 |---|---|
-| `.gitea/workflows/` | `ci-engine.yml` (ainoa reusable workflow POC-vaiheessa) |
+| `.gitea/workflows/` | Reusable workflowt (`build-feature.yml`, `config-provider.yml`) |
 | `scripts/` | `publish-git-pages.sh`, `report-status.sh`, `dispatch-workflow.sh` |
 | **`git-pages/`** | **Oma kokonaisuus: Helm-chartti + docs + retention** |
 | `docs/` | Root-tason arkkitehtuuri, ADRt (0001–0005) |
 | `docs/adr/` | Architecture Decision Records |
 | `tests/` | Bats-testit skripteille |
-| `.gitea/workflows/ci.yml` | Dogfood — kutsuu `ci-engine.yml`:a |
+| `.gitea/workflows/ci.yml` | Dogfood — kutsuu `build-feature.yml`:a |

 **Tarkemmat git-pages-asiat:** `git-pages/docs/` (implementation-notes,
 architecture, design-rationale, secrets, tech-stack).

 ## Key Technical Decisions
- **Provider & Consumer**: `ci-engine.yml` lukittu rajapinta, muu koodi
+- **Provider & Consumer**: `build-feature.yml` lukittu rajapinta, muu koodi
  vapaasti muutettavissa
 - **Vain Gitea, vain reusable workflowt**: ei custom actioneita, ei
  multi-platform
@@ -1,9 +1,6 @@
 # Architecture — Gitea Actions CI -kirjasto

-> ⚠️ POC-vaihe. Tämä dokumentti kuvaa suunniteltua arkkitehtuuria. Toteutus
-> on edelleen kehitysvaiheessa (`ci-engine.yml` on ainoa reusable workflow).
-> Odota uudelleenkirjoitusta ennen kuin luotat tähän dokumenttiin.
->
+> ⚠️ POC-vaihe. Tämä dokumentti kuvaa suunniteltua arkkitehtuuria.
 > Normatiivinen lähde: ADR 0004, ADR 0005, `docs/design-rationale.md`.

 ---
@@ -21,7 +18,7 @@ Kirjasto on Gitea-spesifi. Raportit hallinnoidaan git-pages Helm-chartilla

 | Rooli | Kuvaus |
 |-------|--------|
-| **Provider** | `gitea-ci-library` — tarjoaa `ci-engine.yml`:n (lukittu rajapinta) sekä scriptit |
+| **Provider** | `gitea-ci-library` — tarjoaa `build-feature.yml` (lukittu rajapinta) sekä scriptit |
 | **Consumer** | Mikropalveluprojekti — kutsuu `uses:`-direktiivillä, omistaa pipeline-logiikan |

 Tarkemmin: ADR 0005.
@@ -30,10 +27,10 @@ Tarkemmin: ADR 0005.

 | Komponentti | Tila |
 |-------------|------|
-| `ci-engine.yml` | Toimii POC-tasolla. Ainoa reusable workflow. |
+| `build-feature.yml` | Toimii. Ainoa reusable workflow. |
 | `publish-git-pages.sh` | Toimii. PATCH tar git-pagesiin. |
 | `report-status.sh` | Toimii. POSTaa commit-status (vain custom-linkkiin). |
-| `dispatch-workflow.sh` | Suunniteltu, ei toteutettu POCissa. |
+| `dispatch-workflow.sh` | Toimii. Dispatchee workflown ja pollaa valmistumista. |
 | `git-pages/` | Helm-chartti raporttien hostaukseen. Oma kokonaisuus, tarkemmin: `git-pages/docs/`. |

 ## Ulkoiset palvelut
@@ -43,10 +40,9 @@ Tarkemmin: ADR 0005.
 | **Gitea REST API** | Commit-status, workflow-dispatch, run-pollaus |
 | **Gitea Packages** | Docker-imagen säilytys |
 | **git-pages** | Raporttien hostaus |
-| **SonarQube** | Koodin laadun analyysi (suunniteltu) |

 ## Arkkitehtuuriset rajoitteet

- `ci-engine.yml` on ainoa consumerin kutsuma rajapinta (ADR 0005)
+- `build-feature.yml` on ainoa consumerin kutsuma rajapinta (ADR 0005)
 - Gitea Actionsin natiivi commit-status on ensisijainen (ADR 0004)
 - Raportit ovat julkisia URL:lla (osoite tunnettava)
@@ -50,6 +50,53 @@ Käytäntö:
 - Jos `docker run` tarvitsee env-arvoja, välitä ne eksplisiittisesti `-e VAR`-lipulla
 - `GITHUB_ENV` on validi tapa välittää arvoja stepien välille samassa jobissa, mutta ei leviä `docker run`-kontteihin ilman `-e`-lippua

+### Cross-job config propagation (validated 2026-06-13)
+
+Config-arvojen vienti kaikkiin jobeihin ilman toistoa vaatii kahden
+mekanismin ketjuttamista:
+
+1. **`needs` + `with:`** — `jobs.<job_id>.with.<with_id>` tukee
+   `needs`-kontekstia. Tämä mahdollistaa sen, että yhden jobin outputit
+   voidaan välittää toiselle reusable workflowille inputeina.
+2. **Workflow `env:`** — ainoa natiivi mekanismi, joka tekee arvoista
+   näkyviä kaikissa jobeissa automaattisesti (POC validioitu).
+
+Ketju toimii näin:
+
+```
+gitea-env.conf  →  config-provider.yml  →  env_json (yksi JSON-string)
+       (1)                                    (2)
+                                                 ↓
+                                        ci.yml with: env_json
+                                        ${{ needs.load-config.outputs.env_json }}
+                                          (3)
+                                                 ↓
+                                        build-feature.yml workflow env:
+                                        GITEA_API_URL: ${{ fromJson(inputs.env_json).GITEA_API_URL }}
+                                          (4)
+                                                 ↓
+                                         kaikki jobit → $GITEA_API_URL, $GIT_PAGES_URL jne.
+                                          (5)
+```
+
+Vaiheet:
+1. Consumer määrittelee arvot `gitea-env.conf`:ssä (KEY=VALUE)
+2. `config-provider.yml` lukee confin ja tuottaa yhden JSON-stringin outputina
+3. `ci.yml` välittää JSONin `needs` + `with:` -ketjulla
+4. `build-feature.yml` purkaa arvot workflow `env:`-tasolle `fromJson()`:lla
+5. Kaikki jobit käyttävät valmiita env-muuttujia (`$GIT_PAGES_URL` jne.)
+
+Avainkomponentit:
+- **config-provider.yml** — reusable workflow, joka muuntaa conf-tiedoston
+  yhdeksi JSON-outputiksi. Yksi output riittää, ei per-key outputteja.
+- **`jobs.<job_id>.with`** — tukee `needs`-kontekstia (Gitea Actions,
+  kuten GitHub Actions). Tämä on kriittinen yksityiskohta: ilman tätä
+  config-arvoja ei voi välittää reusable workflowille dynaamisesti.
+- **workflow `env:`** — ainoa tapa jakaa arvot kaikkiin jobeihin.
+  `fromJson(inputs.env_json).KEY` purkaa yksittäiset arvot ilman toistoa.
+- **Per-job `env:`** — sisältää vain secretit (`GITEA_TOKEN`,
+  `GIT_PAGES_PUBLISH_TOKEN`), ei config-arvoja.
+
 ## 5. Pipeline Provides All Dependencies

 - Ei luottamusta runnerin esiasennettuihin työkaluihin
@@ -63,3 +110,16 @@ Käytäntö:
 - Rinnakkaiset jobit (bats + cucumber) — tuloksia saa heti kun valmistuu
 - Jokainen testisetti omassa jobissaan
 - Finalize/build voi kerätä yhteenvedon (ei julkaista summarya jos kenelläkään ei ole linkkiä)
+
+## 7. Inline Logic Threshold
+
+Logiikka workflow YAML:ssa on hauras: YAML:n sisennys, heredocit ja
+kenoviivat tuottavat helposti toimimattomia steppejä.
+
+**Kynnys siirtää scriptiksi:** heti kun steppiin tulee ehtoja, silmukoita,
+tai yli 3 riviä inline-koodia, siirrä omaksi scriptikseen `.gitea/scripts/`-
+kansioon.
+
+Esimerkki: coverage-datan purku ja navigointi-indexin luonti oli aluksi
+inline-heredocina workflow YAML:ssa. Siirto omaan `bats-coverage.sh`-scriptiin
+teki siitä luettavan, testattavan ja muokattavan ilman YAML-muotoiluriskejä.
@@ -67,7 +67,7 @@ Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista synkronisesti
 ### 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 |
@@ -76,6 +76,8 @@ dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> [timeout_
 | `workflow_file` | Kyllä | Workflow-tiedoston nimi (esim. `test.yml`) |
 | `ref` | Kyllä | Branch |
 | `inputs_json` | Kyllä | JSON-objekti input-parametreina |
+| `gitea_api_url` | Kyllä | Gitean API-URL (esim. `https://gitea.example.com`) |
+| `gitea_token` | Kyllä | Gitea API -token |
 | `timeout_minutes` | Ei | Oletus: 360 (6 tuntia) |

 ### Toiminta
@@ -90,7 +92,8 @@ dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> [timeout_

 ```bash
 dispatch-workflow.sh "tests/integration" "test.yml" "main" \
-  '{"version":"1.2.3","tags":"@smoke","root_commit":"abc123","root_repo":"services/temperature-store"}'
+  '{"version":"1.2.3","tags":"@smoke","root_commit":"abc123","root_repo":"services/temperature-store"}' \
+  "https://gitea.example.com" "gtp_abc123"
 ```

 ---
@@ -181,8 +184,8 @@ Skriptit lukevat nämä Gitea Actionsin ympäristömuuttujat:

 | Muuttuja | Lähde | Käyttäjä |
 |----------|-------|----------|
-| `GITEA_API_URL` | Org variable | Kaikki skriptit |
-| `GITEA_TOKEN` | Org secret | `report-status.sh`, `dispatch-workflow.sh`, `tag-commit.sh` |
+| `GITEA_API_URL` | Org variable | `report-status.sh` |
+| `GITEA_TOKEN` | Org secret | `report-status.sh`, `tag-commit.sh` |
 | `MINIO_BASE_URL` | Org variable | `push-reports.sh` |
 | `MINIO_ACCESS_KEY` | Org secret | `push-reports.sh` |
 | `MINIO_SECRET_KEY` | Org secret | `push-reports.sh` |
@@ -54,7 +54,7 @@ Dispatchaa workflow toisessa repossa ja pollaa sen valmistumista synkronisesti.
 ## 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 |
@@ -63,6 +63,8 @@ dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> [timeout_
 | `workflow_file` | Kyllä | Workflow-tiedosto (esim. `test.yml`) |
 | `ref` | Kyllä | Branch |
 | `inputs_json` | Kyllä | JSON-objekti input-parametreina |
+| `gitea_api_url` | Kyllä | Gitean API-URL |
+| `gitea_token` | Kyllä | Gitea API -token |
 | `timeout_minutes` | Ei | Oletus: 360 |

 ## API-kutsut
@@ -77,7 +79,8 @@ dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> [timeout_

 ```bash
 dispatch-workflow.sh "tests/integration" "test.yml" "main" \
-  '{"version":"1.2.3","tags":"@smoke","root_commit":"abc123","root_repo":"services/temperature-store"}'
+  '{"version":"1.2.3","tags":"@smoke","root_commit":"abc123","root_repo":"services/temperature-store"}' \
+  "https://gitea.example.com" "gtp_abc123"
 ```

 ## Verifiointi
@@ -1,8 +1,8 @@
 # Reusable workflowt

 > ⚠️ **POC-vaihe.** Tämä dokumentti kuvaa suunniteltuja workflow'ta
-> (ci-feature, ci-master, deploy, test). POCissa on toteutettu vain
-> `ci-engine.yml`. Uudelleenkirjoitus odottaa.
+> (ci-feature, ci-master, deploy, test). POCissa on toteutettu
+> `build-feature.yml`. Uudelleenkirjoitus odottaa.

 ---