# 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.