POC: test reusable workflow job visibility in Gitea Actions (#5)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com>
Reviewed-on: #5

docs/adr/0005-provider-consumer.md

@@ -0,0 +1,66 @@
+# 5. Provider & Consumer -malli
+
+## Päätös
+
+Provider (gitea-ci-library) ja Consumer (mikropalveluprojekti) erotetaan
+selkeällä rajapinnalla: `.gitea/workflows/ci-engine.yml` on ainoa pinta,
+jota consumer kutsuu.
+
+Kaikki muu providerin koodi (scriptit, git-pages-helmi, retention) on
+sisäistä toteutusta, johon consumerilla ei ole suoraa pääsyä eikä
+riippuvuutta.
+
+## Rajapinnat
+
+### Consumer → Provider (pakollinen)
+
+```yaml
+# .gitea/workflows/ci.yml — consumerin repo
+jobs:
+  ci:
+    uses: niko/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1
+    secrets: inherit
+```
+
+Consumer:
+- Omistaa pipeline-logiikan (mitä testejä ajetaan, missä järjestyksessä)
+- Luo raportit omiin polkuihinsa (`reports/{sha8}/{step}/`)
+- Luo `.meta`-tiedostot per step
+- Määrittelee Gitea-secretit (`GIT_PAGES_PUBLISH_TOKEN`, `GITEA_TOKEN`)
+
+### Provider → Consumer (mitä provider tarjoaa)
+
+- **Raporttien julkaisu**: consumerin tuottamat raportit viedään
+  git-pages-palveluun osoitteeseen, josta ne ovat selaimella luettavissa.
+- **Commit-status linkillä**: jokaiselle raportille luodaan commit-status,
+  jonka kautta käyttäjä pääsee suoraan raporttiin Gitean commit-näkymästä.
+- **Orkestrointi**: build-ketjun ylittäessä reporajat, provider huolehtii
+  workflown käynnistyksestä ja tilan seurannasta.
+- **Raporttien elinkaari**: vanhat raportit poistetaan automaattisesti
+  retention-sääntöjen mukaan.
+
+### Provider (sisäinen toteutus, ei consumerin rajapinta)
+
+- Git-pages Helm-chartti
+- Retention sidecar
+- Scriptit ja työkalut (toteutus avoin, uudelleenkirjoitettavissa)
+- Kaikki paitsi `ci-engine.yml` on sisäistä toteutusta ja voi muuttua
+  ilman versiopäivitystä
+
+## Periaatteet
+
+1. `ci-engine.yml` on **lukittu rajapinta**. Consumer kutsuu tätä, ei
+   koskaan providerin scriptejä suoraan. `ci-engine.yml` voi muuttua vain
+   version vaihtuessa.
+2. Consumer omistaa pipeline-logiikan. Provider ei tiedä mitä testejä
+   ajetaan, missä järjestyksessä tai millä työkaluilla.
+3. Providerin versiointi: tag (`v1`, `v2`, ...). Branchit ovat kehitystä
+   varten, consumerit käyttävät tageja.
+
+## Tausta
+
+Jenkins-versiossa kaikki logiikka oli yhdessä kirjastossa. Gitea Actionsin
+reusable workflow -mekanismi pakottaa selkeämpään erotteluun: consumer
+kutsuu provideria, mutta omistaa oman pipeline-logiikkansa. Tämä vähentää
+providerin kompleksisuutta ja antaa consumerille vapauden päättää mitä
+ajetaan.