git-pages helm chart

2026-06-10 05:18:58 +03:00
parent 14cf2eaeed
commit 26a8b9efa8
29 changed files with 2610 additions and 0 deletions
@@ -0,0 +1,163 @@
+# Miksi oma CI-kirjastoprojekti — ei perus-Gitea-tiedostoja
+
+> Liittyy: [architecture.md](../architecture.md), [config-model.md](../config-model.md), [design-rationale.md](../design-rationale.md)
+
+---
+
+## Taso 1: Miksi kirjastoprojekti, ei repo-kohtaisia workflow'ta
+
+Kirjasto (`gitea-ci-library`) on oma projektinsa, koska sen tarjoamat palvelut
+ovat **cross-cutting** — samat kaikissa mikropalveluissa. Ilman kirjastoa
+jokainen repo kopioisi identtisen CI-logiikan.
+
+### Mitä kirjasto tarjoaa "ilmaiseksi"
+
+| Palvelu | Tiedosto/skripti | Rivimäärä | Jos 20 projektia kopioisi |
+|---|---|---|---|
+| Commit-statusraportointi | `report-status.sh` | ~45 | 900 riviä |
+| Workflow-ketjutus + pollaus | `dispatch-workflow.sh` | ~80 | 1 600 riviä |
+| HTML-raporttien MinIO-pushaus | `push-reports.sh` | ~50 | 1 000 riviä |
+| GitOps-deploy (YAML-muokkaus + commit + cross-repo-trace) | `deploy.yml` | ~100 | 2 000 riviä |
+| Test flow -ketjutus (dispatch + poll + cross-repo-status) | `ci-master.yml` + `test.yml` | ~150 | 3 000 riviä |
+| Feature-branch CI (build-ekosysteemin valinta, concurrency) | `ci-feature.yml` | ~80 | 1 600 riviä |
+
+**Yhteensä ilman kirjastoa: ~10 000 riviä identtistä CI-koodia 20 repossa.**
+
+Yksi bugikorjaus (esim. `push-reports.sh`:n retry-logiikka) = 20 PR:ää, 20 review'tä, 20 mergeä.
+Osa jää tekemättä → eri projektit käyttäytyvät eri tavalla → CI-epäluotettavuus leviää.
+
+**Kirjaston kanssa:** Yksi PR, yksi review, yksi merge. Kaikki projektit saavat korjauksen
+`uses: org/gitea-ci-library/.gitea/workflows/ci-feature.yml@v1`-viittauksen kautta.
+
+### Miksi juuri nämä asiat ansaitsevat oman projektin
+
+Nämä kolme huolta ovat **pitkälle mietitty kokonaisuus**, jonka toteuttaminen
+repo-kohtaisesti olisi massiivista tautologiaa:
+
+1. **Dynaaminen test plan K8s-ympäristössä** — Deploy developmentiin → integraatiotestit
+   → deploy stagingiin → e2e-testit. Jokainen steppi dispatchaa toisen repon workflow'n,
+   pollaa sen valmistumista, ja raportoi cross-repo-statuksen takaisin root-committiin.
+
+2. **HTML-testiraporttien tallennus** — Cucumber, JaCoCo, Maven Site. Pushataan MinIO:hon
+   deterministisellä URL:llä. URL linkitetään commit-statusviestiin. Retention CronJob
+   siivoaa vanhat. Tämä on kokonainen alijärjestelmä, ei yksi steppi.
+
+3. **GitOps-deployment** — Päivitä YAML-arvo Helm-repossa, committaa, pushaa,
+   raportoi cross-repo-status molempiin suuntiin. Sama mekaniikka jokaisessa
+   mikropalvelussa — vain `projectFolder` ja `fileName` vaihtelee.
+
+Näiden toteuttaminen per repo olisi kuin jokainen mikropalvelu toteuttaisi oman
+tietokantakerroksensa sen sijaan että käyttäisi jaettua kirjastoa.
+
+---
+
+## Taso 2: Miksi `ci-flow-values.yaml` — Gitean natiivikonfiguraatio ei riitä
+
+Gitean natiivimekanismit hoitavat salaisuudet ja infra-arvot.
+`ci-flow-values.yaml` hoitaa rakenteisen, versioidun, projekti-spesifin konfiguraation.
+Ne täydentävät toisiaan, eivät kilpaile.
+
+### Mitä Gitea tarjoaa natiivisti
+
+| Mekanismi | Tyyppi | Sijainti | Rajoite |
+|-----------|--------|----------|---------|
+| `workflow_call` `inputs` | Skalaari (`string`, `boolean`, `number`) | Kutsuvan workflow'n parametrit | **Ei tue listoja, objekteja, nested-rakenteita** |
+| Org/repo secrets | `string` (salattu) | Gitea UI | Flat key-value, ei rakennetta |
+| Org/repo variables | `string` | Gitea UI | Flat key-value, ei rakennetta |
+| `.gitea/workflows/*.yml` | YAML | Projektin repo | Täysi workflow-logiikka, ei dataa |
+
+### Ongelma 1: skalaarityypit eivät kanna rakenteista konfiguraatiota
+
+`ci-flow-values.yaml` sisältää mm:
+
+```yaml
+test-flow:
+  - deploy: development
+    wait: true
+  - test:
+      name: "integration fast"
+      repo: tests/integration
+      tags: "@temperature and not @slow"
+  - test:
+      name: e2e
+      repo: tests/e2e
+```
+
+Tämän ilmaiseminen Gitea `inputs`:na vaatisi jokaisen kentän erillisenä parametrina:
+
+```yaml
+with:
+  test_flow_0_deploy: "development"
+  test_flow_1_test_name: "integration fast"
+  test_flow_1_test_repo: "tests/integration"
+  test_flow_1_test_tags: "@temperature and not @slow"
+  # …hajoaa heti kun array pituus vaihtelee
+```
+
+**Gitean `inputs` ei tue dynaamisen pituisia listoja.** Projekteilla on 0–n test flow -steppiä.
+
+### Ongelma 2: konfiguraatio kuuluu repoon, ei Gitean UI:hin
+
+Jos kaikki asetukset vietäisiin Gitea org/repo variables -mekanismiin:
+
+- **Versionhallinta katoaa.** Konfiguraation historiaa ei voi tarkastella (`git log`), reviewata (PR), tai rollbackata (`git revert`).
+- **Konfiguraatio irtoaa koodista.** Kun koodi muuttuu ja tarvitsee uuden konfiguraatioavaimen, muutos tehdään Gitean UI:ssa — eri ajankohtana kuin koodimuutos. CI hajoaa välissä.
+- **Ei PR-prosessia konfiguraatiolle.** Gitean variables/secrets eivät kulje review'n läpi.
+- **Siirtäminen ympäristöjen välillä vaikeutuu.** Staging- ja production-Gitealla on eri variablet. Ei `git cherry-pick` -mekanismia.
+
+### Miksi kaksi tiedostoa, ei yksi
+
+Eli miksi projektilla on **sekä** `.gitea/workflows/ci.yml` **että** `ci-flow-values.yaml`?
+
+```
+.gitea/workflows/ci.yml          → MITEN ajetaan (workflow-valinta + parametrit)
+ci-flow-values.yaml              → MITÄ ajetaan (projektin data)
+```
+
+| `.gitea/workflows/ci.yml` | `ci-flow-values.yaml` |
+|---------------------------|----------------------|
+| Sama kaikissa projekteissa | Uniikki per projekti |
+| Asuu projektin repossa (ohut kutsuja) | Asuu projektin repossa |
+| Kopioitavissa, mutta EI sisällä logiikkaa | Versioituu projektin mukana |
+| Välittää parametrit `with:` → kirjastolle | Sisältää: docker-nimi, sonar-projekti, test-flow-array |
+
+### Työnjako Gitea natiivin ja `ci-flow-values.yaml`:n välillä
+
+| Vaatimus | Gitea natiivi | `ci-flow-values.yaml` |
+|----------|--------------|----------------------|
+| Nested-rakenteet (listat, objekit) | Ei (`inputs` = skalaari) | Kyllä (YAML) |
+| Versionhallinta + PR-review | Ei (UI-pohjainen) | Kyllä (`git`) |
+| Projekti omistaa konffinsa | Osittain (repo variables) | Kyllä |
+| Infra-tason salaisuudet | Kyllä (org secrets) | **Ei** |
+| Jaetut infra-arvot | Kyllä (org variables) | **Ei** |
+
+---
+
+## Yhteenveto: moottori + consumer-tiedostot
+
+```
+gitea-ci-library (MOOTTORI)               Jokainen consumer-repo
+┌──────────────────────────────┐          ┌──────────────────────────────┐
+│ Reusable workflowt            │          │ .gitea/workflows/ci.yml      │
+│ ci-feature.yml                │◄─────────│ uses: .../ci-feature.yml@v1  │
+│ ci-master.yml                 │  kutsuu  │                              │
+│ deploy.yml                    │          │ ci-flow-values.yaml          │
+│ test.yml                      │◄─────────│ build.ecosystem: maven       │
+│                               │  lukee   │ docker.imageName: ...        │
+│ Jaetut skriptit               │          │ test-flow: [...]             │
+│ report-status.sh              │          └──────────────────────────────┘
+│ dispatch-workflow.sh          │
+│ push-reports.sh               │          Gitea org
+│ tag-commit.sh                 │          ┌──────────────────────────────┐
+└──────────────────────────────┘          │ secrets: tokenit, salasanat   │
+                                          │ variables: MinIO URL, Sonar   │
+Kirjasto EI sisällä ci.yml:ää             └──────────────────────────────┘
+consumerille — se on moottori,
+joka syö consumerin tuomia tiedostoja.     ci.yml on kopioitavissa,
+                                            identtinen kaikilla consumereilla.
+```
+
+Salaisuudet (tokenit, salasanat) ja jaetut infra-arvot (MinIO URL, SonarQube URL)
+kuuluvat Gitean natiivimekanismeihin (org secrets/variables).
+CI-logiikka kuuluu kirjastoon (moottori).
+Projektikohtainen data (`ci-flow-values.yaml`) ja ohut kutsuja (`ci.yml`) kuuluvat consumer-repoon.