283 lines
13 KiB
Markdown
283 lines
13 KiB
Markdown
# Data flow — periaatetaso
|
|
|
|
> Tila: DRAFT — kevyt suunnitteludokumentti, muokataan tarpeen mukaan.
|
|
> Ei ADR. Ei normatiivinen. Kuvaa periaatteen, ei implementaatiota.
|
|
>
|
|
> Lähde: [docs/design-rationale.md](../docs/design-rationale.md) — erityisesti periaatteet 1 (commit-status), 3 (konfiguraatio repossa), 5 (raportit MinIO:ssa) ja 7 (cross-repo traceability).
|
|
|
|
## Tarkoitus
|
|
|
|
Selventää **kuka omistaa mitä datan** ja **miten se liikkuu** consumer → provider → Gitea -ketjussa.
|
|
|
|
**Ydinperiaate:** Branch-päätös on consumerin vastuulla. Provider on branch-agnostinen — se saa polun config-tiedostoon ja suorittaa sen määrittämän pipelinen. Consumer valitsee kumman jobin ja minkä pipeline-as-conf -tiedoston ajetaan; engine lukee vain sen mitä `with:` välittää.
|
|
|
|
---
|
|
|
|
## Roolit ja tiedostot
|
|
|
|
| Rooli | Tiedosto(t) | Mitä tietää / mitä tekee |
|
|
|-------|-------------|--------------------------|
|
|
| **Consumer** | `ci.yml` | Trigger, branch (`if:`), valitsee pipeline-as-conf -tiedoston ja kontit, kutsuu engineä `uses:` |
|
|
| **Consumer** | `*-conf.yaml` (pipeline-as-conf) | Projektin data: mitä pipeline ajaa (ekosysteemi, test-flow, docker jne.) — versioitu repossa |
|
|
| **Provider** | `ci-engine.yml` | Gitea workflow (`.gitea/workflows/`); `workflow_call` only; pipeline-määrittely |
|
|
| **Provider** | jaettu suorituskoodi | Uudelleenkäytettävä logiikka — **ei** Gitea workflow; engine kutsuu steppien sisällä |
|
|
| **Gitea org** | secrets | Tokenit, salasanat — ei koskaan repoon; `secrets: inherit` |
|
|
| **Gitea org** | variables (kapea poikkeus) | Org-laajuiset infra-endpointit (esim. `MINIO_BASE_URL`, `GITEA_SERVER_URL`) — valinnainen shortcut |
|
|
|
|
### Secrets vs. variables vs. conf
|
|
|
|
Kolmitasoinen jako — helppo sääntö kehittäjälle:
|
|
|
|
| Tyyppi | Missä | Esimerkkejä |
|
|
|--------|-------|-------------|
|
|
| **Secrets** | Gitea org secrets | `GITEA_TOKEN`, `SONAR_TOKEN`, `DEPLOY_TOKEN` |
|
|
| **Projektidata** | Consumer `*-conf.yaml` | `build.ecosystem`, `docker.imageName`, `sonarqube.*`, `test-flow`, `deployment.*` |
|
|
| **Org-infra** | Gitea org variables (valinnainen) | `MINIO_BASE_URL`, `GITEA_SERVER_URL` — sama kaikille, harvoin muuttuu |
|
|
|
|
1. Salainen? → org secret
|
|
2. Projektin asia? → conf-tiedosto (periaate 3)
|
|
3. Koko orgin sama infra-endpoint? → org variable, vain jos et halua toistaa sitä jokaisessa confissa
|
|
|
|
Org variables on **kapea poikkeus** infra-endpointeille — ei korvike conf-tiedostolle. Projektikohtaiset arvot (docker-nimi, test-flow, Sonar projectKey) kuuluvat aina confiin.
|
|
|
|
### Pipeline vs. jaettu suorituskoodi
|
|
|
|
Kaksi eri artefaktityyppiä provider-puolella:
|
|
|
|
```
|
|
Provider (gitea-ci-library)
|
|
├── .gitea/workflows/ci-engine.yml ← pipeline (Gitea workflow, consumer kutsuu uses:)
|
|
└── jaettu suorituskoodi ← uudelleenkäytettävä logiikka (EI .gitea/workflows/:ssa)
|
|
|
|
Consumer (mikropalvelu)
|
|
├── .gitea/workflows/ci.yml ← ohut kutsuja (Gitea workflow)
|
|
└── ci-feature.yaml ← data (ei suoritettavaa koodia)
|
|
```
|
|
|
|
- **Pipeline-tiedosto** (`ci-engine.yml`) on Gitean workflow — sen täytyy olla `.gitea/workflows/`:ssa, jotta `uses:` löytää sen.
|
|
- **Jaettu suorituskoodi** on providerin omistamaa logiikkaa (status-raportointi, raporttien julkaisu, dispatch jne.). Consumer ei kopioi sitä — korjaus provider-repoon, kaikki consumerit hyötyvät `@v1`:stä.
|
|
- **Toteutus** (kieli, tiedostomuoto, sijainti repossa) ei kuulu tähän dokumenttiin.
|
|
|
|
### Binding: consumer → provider
|
|
|
|
Ei dynaamista löytämistä — consumer kovakoodaa `uses:`-polun:
|
|
|
|
```
|
|
org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
|
|
```
|
|
|
|
| Vaihe | Mitä tapahtuu |
|
|
|-------|---------------|
|
|
| 1 | Push consumer-repoon → Gitea lukee consumerin `ci.yml` |
|
|
| 2 | `if:` valitsee jobin |
|
|
| 3 | `uses:` → Gitea hakee provider-reposta `ci-engine.yml` annetulla `@ref`:llä |
|
|
| 4 | Provider vaatii `on: workflow_call` |
|
|
| 5 | `with:` → providerin `inputs`; checkout = **consumer-repo** (lähdekoodi + config-file) |
|
|
| 6 | Engine tuo provider-artefaktit runnerille tagilla `@v1` |
|
|
|
|
**`@ref`:** `@v1` (tag providerin main-haarassa). Pinnaa engine-version — consumer ei seuraa providerin kehityshaaraa.
|
|
|
|
### Dogfood-erikoistapaus
|
|
|
|
`gitea-ci-library` sisältää sekä consumer- että provider-tiedostot samassa repossa. **Roolit eivät muutu** — vain fyysinen sijainti on poikkeuksellinen.
|
|
|
|
**Dogfood-sääntö:** Consumerin `ci.yml` viittaa provideriin **samalla `uses:`-polulla** kuin mikä tahansa ulkoinen mikropalvelu. Ei suhteellista polkua (`./.gitea/workflows/...`).
|
|
|
|
```
|
|
Ulkoinen mikropalvelu (puhdas consumer) gitea-ci-library (dogfood)
|
|
┌──────────────────────────────┐ ┌──────────────────────────────┐
|
|
│ ci.yml │ │ ci.yml ← consumer │
|
|
│ ci-feature.yaml │ │ ci-feature.yaml ← consumer │
|
|
│ ci-main.yaml │ │ ci-main.yaml ← consumer │
|
|
│ │ │ ci-engine.yml ← provider │
|
|
│ uses: org/gitea-ci-library/ │ │ uses: org/gitea-ci-library/ │
|
|
│ .../ci-engine.yml@v1 │ │ .../ci-engine.yml@v1 │
|
|
└──────────────────────────────┘ │ suorituskoodi ← provider │
|
|
└──────────────────────────────┘
|
|
```
|
|
|
|
Ulkoinen mikropalvelu on puhdas consumer (vain `ci.yml` + conf-tiedostot). Provider tulee `uses:`-viittauksella kirjastosta — dogfood mukaan lukien.
|
|
|
|
---
|
|
|
|
## Kuusi data-virtaa
|
|
|
|
```
|
|
1. CONSUMER → PROVIDER (push)
|
|
Consumer tietää branchin → valitsee jobin + config-file + kontit.
|
|
Provider vastaanottaa, ei tulkitse branchia.
|
|
|
|
ci.yml ──with: config-file + kontti-imaget──► ci-engine.yml
|
|
|
|
2. PROVIDER SISÄINEN
|
|
Engine lukee config-file-polun → rakentaa steppigraafin → ajaa stepit.
|
|
Mitä pipelinea ajetaan johtuu conf-tiedostosta, ei branch-tiedosta providerissa.
|
|
|
|
3. PROVIDER → GITEA (commit-status)
|
|
Jokainen steppi raportoi tilansa commitille (Gitea REST API).
|
|
Uniikki key per vaihe (periaate 1).
|
|
|
|
4. GITEA → CONSUMER (feedback loop)
|
|
Consumerin commitille kertyy statuksia jokaisesta stepistä.
|
|
Kehittäjä näkee suoraan commitilta: mitä ajettiin, menikö läpi.
|
|
url-kenttä linkittää raportteihin / buildiin.
|
|
|
|
5. PROVIDER → MinIO → GITEA (raportit)
|
|
Steppi generoi raportin → julkaisu MinIO:hon
|
|
→ deterministinen URL → URL liitetään commit-statusviestiin
|
|
(periaate 5).
|
|
|
|
6. CROSS-REPO KETJU
|
|
Mikropalvelu-commit (root) → dispatch → toinen repo → status takaisin root-committiin.
|
|
root-build kulkee inputs-parametrina koko ketjun läpi (periaate 7).
|
|
```
|
|
|
|
---
|
|
|
|
## Silmukka
|
|
|
|
```
|
|
Consumer pushaa koodia
|
|
│
|
|
├── feature-branch → ci.yml valitsee feature-jobin
|
|
│ with: config-file: ci-feature.yaml + kontit
|
|
│
|
|
└── main-branch → ci.yml valitsee main-jobin
|
|
with: config-file: ci-main.yaml + kontit
|
|
│
|
|
▼ uses:
|
|
┌──────────────────────────────────────────────┐
|
|
│ ci-engine.yml (provider, branch-agnostinen) │
|
|
│ Lukee config-file → steppigraafi → stepit │
|
|
│ │
|
|
│ config-file → steppigraafi → stepit ajetaan │
|
|
│ │ │ │ │
|
|
│ └────────────┴────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ jokainen steppi → status commitille │
|
|
│ │ │
|
|
│ (raportit) → MinIO → url statusiin │
|
|
└──────────────────┬───────────────────────────┘
|
|
│ POST /api/v1/repos/.../statuses/{sha}
|
|
▼
|
|
┌──────────────────────────────────────────────┐
|
|
│ Gitea commit │
|
|
│ ├── ci/start ✓ │
|
|
│ ├── ci/unit-test ✓ (url → raportti) │
|
|
│ ├── ci/code-coverage ✓ │
|
|
│ └── ci/end ✓ │
|
|
└──────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Cross-repo ketju (periaate 7)
|
|
|
|
```
|
|
Mikropalvelu (root-commit abc123)
|
|
│
|
|
├── build + deploy ──dispatch──► Helm-repo (commit def456)
|
|
│ │
|
|
│ ├── status → oma commit
|
|
│ └── status → root abc123
|
|
│
|
|
└── test-flow ──dispatch──► Testi-repo (commit ghi789)
|
|
│
|
|
├── status → oma commit
|
|
├── status → root abc123
|
|
└── status → Helm def456
|
|
|
|
root-build (abc123) kulkee workflow_dispatch inputs -parametrina koko ketjun läpi.
|
|
```
|
|
|
|
---
|
|
|
|
## Omistajuus
|
|
|
|
| Mitä | Omistaja | Miten liikkuu |
|
|
|------|----------|---------------|
|
|
| Branch-päätös | Consumer | `ci.yml` `if:` |
|
|
| Mitä pipelinea ajetaan | Consumer | Valittu pipeline-as-conf -tiedosto |
|
|
| Pipeline-runko (steppigraafi) | Provider | Engine rakentaa confista |
|
|
| Kontit (maven, dind…) | Consumer | `with:` → provider `inputs` |
|
|
| Projektidata (ecosystem, test-flow…) | Consumer | pipeline-as-conf repossa |
|
|
| Moottori + jaettu suorituskoodi | Provider | `ci-engine.yml` + provider-logiikka |
|
|
| Tokenit, salasanat | Gitea org | secrets — `secrets: inherit` |
|
|
| Org-laajuiset infra-endpointit | Gitea org | variables (valinnainen poikkeus) |
|
|
|
|
---
|
|
|
|
## Consumer-sopimus
|
|
|
|
`ci.yml` on **mahdollisimman lyhyt**:
|
|
|
|
- Kaksi jobia (feature / main) tai vastaava `if:`-jaottelu
|
|
- Sama engine, eri `config-file` per job
|
|
- Kontit consumerin `with:`:ssa — provider ei sisällä image-versioita
|
|
- `secrets: inherit`
|
|
|
|
```yaml
|
|
# Esimerkki — kovakoodattu provider-polku (provider main-haarassa, tag @v1)
|
|
|
|
jobs:
|
|
feature:
|
|
if: gitea.ref != 'refs/heads/main'
|
|
uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
|
|
secrets: inherit
|
|
with:
|
|
config-file: ci-feature.yaml
|
|
maven-image: ...
|
|
|
|
main:
|
|
if: gitea.ref == 'refs/heads/main'
|
|
uses: org/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
|
|
secrets: inherit
|
|
with:
|
|
config-file: ci-main.yaml
|
|
maven-image: ...
|
|
dind-image: ...
|
|
```
|
|
|
|
---
|
|
|
|
## Provider-sopimus
|
|
|
|
- Vain `workflow_call` — ei omaa triggeriä
|
|
- Pakollinen input: `config-file` (polku repossa)
|
|
- Valinnaiset: kontti-imaget consumerilta
|
|
- Ei branch-ehtoja provider-tiedostossa — consumer on jo päättänyt mitä ajetaan conf-valinnalla
|
|
- Lukee consumer-datan (lähdekoodi + config-file) ja tuo provider-artefaktit runnerille
|
|
- Lukee conf → suorittaa → raportoi
|
|
|
|
### Mitä engine EI tiedä
|
|
|
|
- Onko kyseessä feature vai main — consumer on jo valinnut conf-tiedoston
|
|
- Mitä komentoja ajetaan — ne tulevat conf-tiedostosta
|
|
- Mitä kontteja on käytössä — consumer kertoo `with:`:ssa
|
|
|
|
Engine on branch-agnostinen suorittaja. Consumer omistaa päätökset ja datan.
|
|
|
|
---
|
|
|
|
## Esimerkki: gitea-ci-library (dogfood)
|
|
|
|
Tämä projekti on sekä provider että consumer. Roolit pysyvät samoina kuin ulkoisella mikropalvelulla — **sama `uses:`-viittaus** (`@v1`), ei suhteellista polkua. Consumer-sopimuksen esimerkki pätee sellaisenaan.
|
|
|
|
| Rooli | Tiedosto | Mitä tekee |
|
|
|-------|----------|------------|
|
|
| Consumer | `ci.yml` | Tietää branchin, valitsee jobin ja conf-tiedoston, syöttää kontit |
|
|
| Consumer | `ci-feature.yaml`, `ci-main.yaml` | Pipeline-as-conf — projektin data per pipeline-tyyppi |
|
|
| Provider | `ci-engine.yml` | Pipeline-määrittely; lukee config-file:n, rakentaa steppigraafin, ajaa, raportoi |
|
|
| Provider | jaettu suorituskoodi | Status, raportit, dispatch — toteutus avoin |
|
|
|
|
---
|
|
|
|
## Mitä tämä EI ota kantaa
|
|
|
|
- Moottorin toteutuskieli ja -muoto (bash, TypeScript, Python, Go — erillinen päätös)
|
|
- Nykyiset skriptitiedostot ja niiden rajapinnat (mahdollinen redesign)
|
|
- Raporttien julkaisumekanismi (miten MinIO:hon — toteutus avoin)
|
|
- Provider-artefaktien toimitus runnerille (checkout, bundle, inline — toteutus myöhemmin)
|
|
- Main-skeletonin yksityiskohdat (build, deploy, test-flow)
|
|
- Conf-tiedoston skeema / kentät (→ `config-model.md`)
|
|
- Cross-repon workflow-tiedostojen sisältö
|