docs: POC-katselmus — git-pages retention, ADRt, dokumenttipäivitykset

- ADR 0004: commit-status-periaate (natiivi riittää, API vain custom-linkkiin) - ADR 0005: provider & consumer -malli (ci-engine.yml lukittu rajapinta) - docs/design-rationale: uusi periaate 1 "Hyödynnä natiivia", periaate 2 korjattu (API vain tarvittaessa), periaate 6 (MinIO→git-pages), teknologiavalinnat poistettu - docs/config-model: isContainerBuild→isArtifactBuild, Docker-labelit poistettu - docs/ai-context: monorepo-kuvaus (git-pages oma kokonaisuus, ohut rajapinta) - docs/architecture, tech-stack, report-hosting, shared-scripts, workflows: MinIO→git-pages, provider agnostinen build-ekosysteemeille - docs/adr/: ADRt siirretty decisions/→adr/ - git-pages/docs: retention-osiot päivitetty CronJob→sidecar+HTTP API, URL-kaava korjattu (reports/{sha8}/) - git-pages/docs/implementation-notes: uusi (storage v2, Host-header, whiteout, .init, PATCH+directoryt) - git-pages/templates/init-job.yaml: post-install init (.index) - scripts/publish-git-pages.sh: PUT-fallback poistettu (init hoitaa), palauttaa BASE URL ilman index.html
2026-06-12 08:55:23 +03:00
parent f4baa286c7
commit 28754bd410
18 changed files with 464 additions and 660 deletions
@@ -1,216 +1,52 @@
 # Architecture — Gitea Actions CI -kirjasto

-> Hub-dokumentti. Komponentit, niiden roolit ja rajapinnat. Yksityiskohtaiset kuvaukset linkitetyissä detail-dokumenteissa.
+> ⚠️ POC-vaihe. Tämä dokumentti kuvaa suunniteltua arkkitehtuuria. Toteutus
+> on edelleen kehitysvaiheessa (`ci-engine.yml` on ainoa reusable workflow).
+> Odota uudelleenkirjoitusta ennen kuin luotat tähän dokumenttiin.
 >
-> Tämä dokumentti on **normatiivinen** — se määrittelee mikä on rakennettava. `design-rationale.md` kertoo miksi.
+> Normatiivinen lähde: ADR 0004, ADR 0005, `docs/design-rationale.md`.

 ---

 ## Yleiskuvaus

-Kirjasto on kokoelma **Gitea Actions reusable workflow** -tiedostoja, jotka orkestroivat mikropalveluiden build-, testaus-, raportointi-, deployment- ja test flow -prosessit. Projekti käyttää kirjastoa `uses:`-direktiivillä `.gitea/workflows/*.yml`-tiedostossaan ja määrittelee konfigurationsa `ci-flow-values.yaml`-tiedostossa.
+Kirjasto on kokoelma **Gitea Actions reusable workflow** -tiedostoja, jotka
+orkestroivat mikropalveluiden build-, testaus-, raportointi-, deployment- ja
+test flow -prosessit. Projekti käyttää kirjastoa `uses:`-direktiivillä.

-Kirjasto on Gitea-spesifi. Se hyödyntää Gitean REST API:a commit-statusraportointiin, workflow-dispatchiin ja run-pollaukseen. Raportit tallennetaan MinIO:hon, josta ne ovat selailtavissa HTML-muodossa.
+Kirjasto on Gitea-spesifi. Raportit hallinnoidaan git-pages Helm-chartilla
+(`git-pages/`).

---
+## Provider & Consumer -malli

-## Komponentit
+| Rooli | Kuvaus |
+|-------|--------|
+| **Provider** | `gitea-ci-library` — tarjoaa `ci-engine.yml`:n (lukittu rajapinta) sekä scriptit |
+| **Consumer** | Mikropalveluprojekti — kutsuu `uses:`-direktiivillä, omistaa pipeline-logiikan |

-### Reusable workflowt (4 kpl)
+Tarkemmin: ADR 0005.

-| Workflow | Tiedosto | Rooli |
-|----------|----------|-------|
-| **Feature flow** | `ci-feature.yml` | Testaa feature-branchin, generoi raportit, raportoi statuksen committiin. Ei buildaa konttia. |
-| **Master flow** | `ci-master.yml` | Testaa, buildaa kontin, pushaa rekisteriin, tagittaa commitin, ketjuttaa test flow'n. |
-| **Deployment flow** | `deploy.yml` | GitOps-deployment: päivittää YAML-arvoa, committaa, pushaa, raportoi cross-repo-statuksen. |
-| **Test flow** | `test.yml` | Vastaanottaa dispatchin, ajaa testit, generoi raportit, raportoi statuksen. |
+## Komponentit (POC)

-> Yksityiskohtaiset kuvaukset: [workflows.md](workflows.md)
+| Komponentti | Tila |
+|-------------|------|
+| `ci-engine.yml` | Toimii POC-tasolla. Ainoa reusable workflow. |
+| `publish-git-pages.sh` | Toimii. PATCH tar git-pagesiin. |
+| `report-status.sh` | Toimii. POSTaa commit-status (vain custom-linkkiin). |
+| `dispatch-workflow.sh` | Suunniteltu, ei toteutettu POCissa. |
+| `git-pages/` | Helm-chartti raporttien hostaukseen. Oma kokonaisuus, tarkemmin: `git-pages/docs/`. |

-### Jaetut skriptit
-
-| Skripti | Rooli |
-|---------|-------|
-| **`report-status.sh`** | POSTaa build-statuksen Gitea `/api/v1/repos/{owner}/{repo}/statuses/{sha}` |
-| **`dispatch-workflow.sh`** | Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista |
-| **`push-reports.sh`** | Puskaa testiraportit MinIO:hon ja generoi URL:n |
-| **`tag-commit.sh`** | Tagittaa commitin versiolla Gitea REST API:n kautta |
-
-> Yksityiskohtaiset kuvaukset: [shared-scripts.md](shared-scripts.md)
-
-### Konfiguraatio
-
-| Artefakti | Sijainti | Rooli |
-|-----------|----------|-------|
-| **`ci-flow-values.yaml`** | Projektin repo | Projektikohtainen konfiguraatio (docker, sonar, deployment, test-flow) |
-| **Gitea org secrets** | Gitea organization | Tokenit ja salasanat |
-| **Gitea org variables** | Gitea organization | Infra-tason asetukset (MinIO URL, SonarQube URL) |
-
-> Yksityiskohtaiset kuvaukset: [config-model.md](config-model.md)
-
-### Ulkoiset palvelut
+## Ulkoiset palvelut

 | Palvelu | Rooli |
 |---------|-------|
-| **Gitea REST API** | Commit-statusraportointi, workflow-dispatch, run-pollaus, taggaus |
-| **Gitea Packages** | Docker-imagen ja NPM-paketin säilytys |
-| **Gitea act runner** | Suorittaa workflowt. Konteista, DinD:stä ja label-järjestelmästä: [runner.md](runner.md) |
-| **MinIO** | Testiraporttien tallennus ja staattinen web-hosting |
-| **SonarQube** | Koodin laadun analyysi ja quality gate |
+| **Gitea REST API** | Commit-status, workflow-dispatch, run-pollaus |
+| **Gitea Packages** | Docker-imagen säilytys |
+| **git-pages** | Raporttien hostaus |
+| **SonarQube** | Koodin laadun analyysi (suunniteltu) |

---
+## Arkkitehtuuriset rajoitteet

-## Järjestelmäkaavio
-
-```mermaid
-%%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
-flowchart TB
-    subgraph PROJ["Projektin repo"]
-        WF[".gitea/workflows/ci.yml
-        uses: gitea-ci-library/ci-master@v1"]
-        CONF["ci-flow-values.yaml"]
-    end
-
-    subgraph LIB["gitea-ci-library (reusable workflowt)"]
-        FEATURE["ci-feature.yml"]
-        MASTER["ci-master.yml"]
-        DEPLOY["deploy.yml"]
-        TEST["test.yml"]
-    end
-
-    subgraph SCRIPTS["Jaetut skriptit"]
-        REPORT["report-status.sh"]
-        DISPATCH["dispatch-workflow.sh"]
-        PUSHREP["push-reports.sh"]
-        TAG["tag-commit.sh"]
-    end
-
-    subgraph EXT["Ulkoiset palvelut"]
-        GITEA["Gitea API
-        + Packages"]
-        MINIO["MinIO
-        (S3 + static web)"]
-        SONAR["SonarQube"]
-    end
-
-    subgraph HELM["Helm-repo"]
-        VALUES["values-{env}.yaml"]
-    end
-
-    subgraph TESTREPO["Testi-repo"]
-        TESTWF[".gitea/workflows/test.yml"]
-    end
-
-    WF -- "kutsuu" --> MASTER
-    WF -- "lukee" --> CONF
-    MASTER -- "käyttää" --> SCRIPTS
-    DEPLOY -- "käyttää" --> SCRIPTS
-    TEST -- "käyttää" --> SCRIPTS
-    REPORT -- "POST status" --> GITEA
-    DISPATCH -- "dispatch + poll" --> GITEA
-    PUSHREP -- "S3 upload" --> MINIO
-    TAG -- "POST tag" --> GITEA
-    MASTER -- "quality gate" --> SONAR
-    DEPLOY -- "muokkaa" --> VALUES
-    DEPLOY -- "commit + push" --> HELM
-    DISPATCH -- "dispatch" --> TESTWF
-    TESTWF -- "raportoi" --> GITEA
-    MINIO -- "URL commit-statusviestiin" --> GITEA
-
-    style PROJ fill:#1e3a5f,color:#f9fafb,stroke:#64748b
-    style LIB fill:#1f2937,color:#f9fafb,stroke:#64748b
-    style SCRIPTS fill:#064e3b,color:#f9fafb,stroke:#64748b
-    style EXT fill:#5c1a1a,color:#f9fafb,stroke:#64748b
-    style HELM fill:#4a1a6b,color:#f9fafb,stroke:#64748b
-    style TESTREPO fill:#4a1a6b,color:#f9fafb,stroke:#64748b
-    style WF fill:#2563eb,color:#ffffff
-    style CONF fill:#f59e0b,color:#111827
-    style FEATURE fill:#2563eb,color:#ffffff
-    style MASTER fill:#2563eb,color:#ffffff
-    style DEPLOY fill:#2563eb,color:#ffffff
-    style TEST fill:#2563eb,color:#ffffff
-    style REPORT fill:#059669,color:#ffffff
-    style DISPATCH fill:#059669,color:#ffffff
-    style PUSHREP fill:#059669,color:#ffffff
-    style TAG fill:#059669,color:#ffffff
-    style GITEA fill:#dc2626,color:#ffffff
-    style MINIO fill:#dc2626,color:#ffffff
-    style SONAR fill:#dc2626,color:#ffffff
-    style VALUES fill:#9333ea,color:#ffffff
-    style TESTWF fill:#9333ea,color:#ffffff
-    linkStyle default stroke:#9ca3af,stroke-width:3px
-```
-
---
-
-## Tietovuot
-
-### 1. Commit-statusraportointi
-
-```
-Workflow-steppi → report-status.sh → POST Gitea API → commitin status päivittyy
-                                                    ↘ URL → raporttiin / buildiin
-```
-
-Jokainen vaihe (test, build, push) POSTaa oman statusviestinsä uniikilla `key`-arvolla. Samaan committiin kertyy useita rinnakkaisia statuksia.
-
-### 2. Cross-repo traceability
-
-```
-Mikropalvelu (root-build)  →  Helm (deployment)  →  Testi (integraatio)
-       ↓                           ↓                       ↓
-  Status omaan committiin    Status omaan committiin  Status omaan committiin
-       ↑                           ↑                       ↑
-  Status root-committiin ←  Status root-committiin ←  Status root-committiin
-  (deployattu, testattu)   (mistä kontti tuli)       (mitä testattiin)
-```
-
-Root-build-viite kulkee `workflow_dispatch`in `inputs`-parametrina koko ketjun läpi.
-
-### 3. Raporttien URL-generointi
-
-```
-push-reports.sh → mc cp ./reports/ minio/bucket/{repo}/{commit_short}/{report}/
-                → URL = {MINIO_BASE}/{repo}/{commit_short}/{report}/index.html
-                → report-status.sh POSTaa URL:n commit-statusviestiin
-```
-
-### 4. Test flow -ketjutus
-
-```
-ci-master.yml → test-flow-taulukko (ci-flow-values.yaml)
-              → for each step:
-                  dispatch-workflow.sh {test-repo} {inputs}
-                  poll Gitea API run status
-                  success? → next step
-                  failure? → stop
-```
-
---
-
-## Laajennuspisteet
-
-| Piste | Mekanismi | Tila |
-|-------|-----------|------|
-| **Docker-rekisterit** | Factory/adapter — `ci-flow-values.yaml` → `docker.type` → valitsee pusherin | MVP: Gitea Packages. Artifactory, Nexus myöhemmin |
-| **Testikehykset** | `push-reports.sh` tukee mitä tahansa hakemistoa → MinIO | Cucumber, JUnit, JaCoCo, Maven Site, custom |
-| **Build-ekosysteemit** | Workflow'n `container:` määrittelee projektin itse | Maven, Gradle, npm, mikä tahansa |
-| **SonarQube** | Rajapinta vaihdettavissa — parempi kuin pollaus tutkitaan | Quality gate -tarkistus |
-
---
-
-## Top-level rajoitteet
-
- Kaikki integraatio Gitea REST API:n kautta — ei suoria tietokantakytkentöjä, ei jaettua filesysteemiä
- Workflowt eivät jaa tilaa keskenään paitsi `workflow_dispatch`in `inputs`-parametrien kautta
- Raporttien URL on deterministinen: `{MINIO_BASE}/{repo_slug}/{commit_short}/{report}/`
- Cross-repo-statusraportoinnissa root-build on aina se mikropalvelun commit, josta ketju käynnistyi
-
-## Repo-jako
-
-| Repo | Sisältö |
-|------|---------|
-| **`gitea-ci-library`** | Reusable workflowt, jaetut skriptit, `report-service/`-moduuli (raporttiskriptit, retention CronJob, index.html-generointi) |
-| **Deployment / infra -repo** (olemassa oleva) | MinIO Kubernetes-manifestit, Traefik OIDC middleware, ConfigMap, ingress |
-
-`gitea-ci-library/report-service/` on oma moduulinsa samassa repossa — ei erillistä repositoriota, mutta selkeä sisäinen raja workflow-skriptien ja raporttipalvelun koodin välillä. Moduuli sisältää `docs/`-hakemiston deploy-esimerkeillä, mutta varsinainen deployment hoidetaan GitOps/Helm-repon kautta kuten muutkin palvelut.
+- `ci-engine.yml` on ainoa consumerin kutsuma rajapinta (ADR 0005)
+- Gitea Actionsin natiivi commit-status on ensisijainen (ADR 0004)
+- Raportit ovat julkisia URL:lla (osoite tunnettava)