gitea-ci-library/tmp/data-flow-design.md

Data flow — periaatetaso

Tila: DRAFT — kevyt suunnitteludokumentti, muokataan tarpeen mukaan. Ei ADR. Ei normatiivinen. Kuvaa periaatteen, ei implementaatiota.

Lähde: 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

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