moilanik
164 lines
8.2 KiB
Markdown
164 lines
8.2 KiB
Markdown
# 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.
|