# Architecture — Gitea Actions CI -kirjasto

> Normatiivinen lähde: ADR 0004, 0005, 0006, 0007, 0008.

---

## 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ä.

Kirjasto on Gitea-spesifi. Raportit hallinnoidaan git-pages Helm-chartilla
(`git-pages/`).

## Provider & Consumer -malli

| Rooli | Kuvaus |
|-------|--------|
| **Provider** | `gitea-ci-library` — tarjoaa reusable workflowt (`config-provider.yml`, `check-version.yml`, `docker-build-push.yml`) ja scriptit |
| **Consumer** | Mikropalveluprojekti — kutsuu `uses:`-direktiivillä, omistaa pipeline-logiikan. Tämän repon oma toteutus: `example-*`-tiedostot |

Tarkemmin: ADR 0005.

## Komponentit

| Komponentti | Tyyppi | Kuvaus |
|---|---|---|
| `config-provider.yml` | Provider | Lataa + validoi `.conf`-tiedoston, tuottaa `env_json` |
| `check-version.yml` | Provider | Tarkistaa git-tagit, laskee version, palauttaa `artifact_exists` + `version` |
| `docker-build-push.yml` | Provider | Buildaa Docker-imagen, puskea rekisteriin, tagittaa commitin |
| `example-feature.yml` | Consumer | Feature-haaran CI: load-config → bats + cucumber → summary |
| `example-main.yml` | Consumer | Main-haaran CI: load-config → check-version → bats + cucumber → summary → docker |
| `example-bats-tests.yml` | Consumer | Unit-testit Batsilla |
| `example-cucumber-tests.yml` | Consumer | Hyväksymätestit Cucumberilla |
| `example-report-summary.yml` | Consumer | `GITHUB_STEP_SUMMARY`-taulukko (Gitea 1.27+) |
| `publish-git-pages.sh` | Provider-skripti | PATCH tar git-pagesiin |
| `report-status.sh` | Provider-skripti | POSTaa commit-status (vain custom-linkkiin) |
| `ci-validate.sh` | Provider-skripti | Validoi `.conf`-tiedoston ja tarkistaa secretit |
| `dispatch-workflow.sh` | Provider-skripti | Dispatchee workflown ja pollaa valmistumista |
| `git-pages/` | Infra | Helm-chartti raporttien hostaukseen. Oma kokonaisuus |

## Statusraportointi

| Job-tyyppi | Mekanismi | Syy |
|---|---|---|
| Tool-jobit | Vain Gitea natiivi job-status | Ei raporttia linkitettäväksi |
| Test-jobit | Commit-status API linkillä | Ainoa tapa upottaa raporttilinkki commit-näkymään |
| Docker-build-push | Commit-status API linkillä | Linkki Docker registryyn |

Tarkemmin: ADR 0004, 0007.

## Ulkoiset palvelut

| Palvelu | Rooli |
|---|---|
| Gitea REST API | Commit-status (vain custom-linkit), git-tagit |
| Gitea Packages | Docker-imagen säilytys |
| git-pages | Raporttien hostaus |

## Arkkitehtuuriset rajoitteet

- Provider-workflowt ovat reusableja (`workflow_call`), consumer omistaa orkestroinnin
- Gitea Actionsin natiivi commit-status on ensisijainen (ADR 0004)
- API:a käytetään vain custom-linkkeihin (ADR 0007)
- Exit-koodi on ainoa onnistumisen mittari — ei pipeä (ADR 0008)
- Raportit ovat julkisia URL:lla (osoite tunnettava)
- Consumer-skriptit `.gitea/scripts/`-alla, provider-skriptit `scripts/`-alla (ADR 0006)