POC: test reusable workflow job visibility in Gitea Actions (#5)
Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #5
This commit is contained in:
@@ -0,0 +1,282 @@
|
||||
# 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ö
|
||||
Reference in New Issue
Block a user