gitea-ci-library/docs/analysis/ci-flow-values-vs-native-config.md

Miksi oma CI-kirjastoprojekti — ei perus-Gitea-tiedostoja

Liittyy: architecture.md, config-model.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:

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:

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.