gitea-ci-library/docs/ai-context.md

# AI Context: Gitea Actions CI -kirjasto

**Updated**: 2026-06-19 (provider/consumer dual role, Project Skills -aktivointi)

## Project Overview
Gitea Actions reusable workflow -kirjasto mikropalveluiden build-, testaus-,
raportointi-, deployment- ja test flow -prosessien orkestrointiin. Korvaa
`ci-jenkins-library`:n Gitea-natiivilla toteutuksella. Mikropalvelut
käyttävät kirjastoa `uses:`-direktiivillä.

## Monorepo: kaksi erillistä kokonaisuutta

### 1. Juuri (`gitea-ci-library`)
Provider- ja consumer-kirjasto: reusable workflowt, scriptit, ADRt, dokumentaatio,
ja consumer-esimerkit (dogfood). Consumer kutsuu provider-workflowta `uses:`-direktiivillä.

### 2. `git-pages/` — oma kokonaisuus
Helm-chartti Codeberg git-pagesille. Täysin itsenäinen — oma dokumentaatio,
omat tekniset valinnat, oma design-rationale. Kaikki git-pages-spesifi tieto
kuuluu `git-pages/docs/`-alle, ei juuren `docs/`-kansioon.

## Repository Structure

| Path | Purpose |
|---|---|
| `.gitea/workflows/config-provider.yml` | Provider: lataa + validoi config-tiedoston, tuottaa `env_json` |
| `.gitea/workflows/check-version.yml` | Provider: tarkistaa onko commitille jo artifact, laskee version |
| `.gitea/workflows/docker-build-push.yml` | Provider: buildaa + puskea Docker-imagen, tagittaa commitin |
| `.gitea/workflows/ci-container-build-push.yml` | Provider: buildaa + puskea CI-työkalukontin |
| `.gitea/workflows/example-*` | **Consumer-esimerkki**: tämän repon oma CI (dogfood) |
| `scripts/` | Provider-skriptit: `report-status.sh`, `publish-git-pages.sh`, `ci-validate.sh` |
| `.gitea/scripts/` | **Consumer-skriptit**: `bats-coverage.sh`, `bats-report.sh` |
| `docs/` | Arkkitehtuuri, ADRt (0004–0008) |
| `skills/consumer-pipelines/` | Consumer-pipeline-standardit (ks. Project Skills). Koskee vain consumer-puolta |
| `skills/ci-container-build/` | CI-kontin build-workflow'n template (ks. Project Skills) |
| `docs/adr/` | Architecture Decision Records |
| `git-pages/` | Raporttien hostaus (Helm-chartti) |
| `tests/` | Bats-testit skripteille |

### Provider workflowt (6 kpl)

| Workflow | Input | Output | Kuvaus |
|---|---|---|---|
| `config-provider.yml` | `config_path` | `env_json`, `config_path` | Validoi ja jäsentää `.conf` → JSON. Sama kutsu hoitaa validoinnin. |
| `check-version.yml` | `env_json` | `artifact_exists`, `version` | Tarkistaa git-tagit ja `package.json`:n, laskee seuraavan version. Vain main-haarassa. |
| `docker-build-push.yml` | `env_json`, `version` | — | Buildaa Docker-imagen, puskea rekisteriin, tagittaa commitin. |
| `ci-container-build-push.yml` | `env_json`, `dockerfile_path`, `image_name`, `tag` | — | Buildaa CI-työkalukontin, puskea rekisteriin. Ei versiointia eikä git-tägäystä. |
| `report-summary.yml` | `env_json`, `suites` | — | Generoi `GITHUB_STEP_SUMMARY`-taulukon raporttilinkeillä (Gitea 1.27+) |
| `helm-build-push.yml` | `env_json`, `version` | — | Pakkaa + puskea Helm chartin OCI-registryyn, tagittaa commitin. **Tekninen velka:** asentaa node.js:n runtime-vaiheessa (`apk add --no-cache nodejs` ennen checkouttia) koska `alpine/helm`-kontissa ei ole nodea. Rikkoo Offline Container -periaatetta. Ratkaistaan myöhemmin: proper multi-tool CI-kontti (helm + nodejs + git) docker hubiin. Ei consumerin ongelma. |

### Example-tiedostot (consumer-referenssi)

| Tiedosto | Laukaisin | Flow |
|---|---|---|
| `example-feature.yml` | push [ei main] | load-config → bats + cucumber → report-summary |
| `example-main.yml` | push [main] | load-config → check-version → bats + cucumber → report-summary → docker-build-push |
| `example-bats-tests.yml` | workflow_call | Unit-testit Batsilla, raportit git-pagesiin, status linkillä |
| `example-cucumber-tests.yml` | workflow_call | Hyväksymätestit Cucumberilla, raportit git-pagesiin, status linkillä |
| `example-gitea-env.conf` | — | KEY=VALUE config tälle repolle |

## Provider & Consumer Dual Role

Tämä repo on **yhtä aikaa sekä provider että consumer**. Eri puolilla on eri säännöt:

- **Provider-puoli**: `.gitea/workflows/*.yml` (pl. `example-*`), `scripts/` — reusable workflowt joita muut projektit kutsuvat. Saa käyttää `docker run` -komentoja (esim. `docker-build-push.yml`). Consumer-pipeline-standardit (`skills/consumer-pipelines/`) eivät koske provideria.
- **Consumer-puoli**: `.gitea/workflows/example-*`, `.gitea/scripts/` — tämän repon oma CI (dogfood), toimii consumer-esimerkkinä. Käyttää `@main`-refiä provider-viittauksissa (sama repo). Noudattaa `skills/consumer-pipelines/`-sääntöjä.
- **Ulkoiset consumerit** käyttävät `@v1`-tagia provider-viittauksissa.

## Project Skills (skills/)

Tämä projekti sisältää omia `.ai/skills/`-järjestelmästä riippumattomia skillejä `skills/`-kansiossa. Jokainen alihakemisto sisältää `SKILL.md`:n jossa on `activation-gate`-kenttä.

**Sääntö:** Uuden tehtävän alussa skannaa `skills/*/SKILL.md` ja arvioi jokaisen `activation-gate` annettua tehtävää vasten. Jos gate matchaa, lataa skill aktiiviseksi ohjeeksi ennen toimenpiteitä.

| Skill | Gate | Kuvaus |
|---|---|---|
| `skills/consumer-pipelines/` | Consumer-pipeline-muutokset | Consumer-pipeline-standardit: reitittimen puhtaus, exit-koodi, konttipolitiikka, raportointi, nimeäminen. Koskee vain consumer-puolta. |
| `skills/ci-container-build/` | CI-kontin build | CI-kontin build-workflown template ja Dockerfile-ohjeet |

## Key Technical Decisions

- **Provider & Consumer -malli**: Tämä repo on sekä provider että consumer. Provider-workflowt reusableja muille, `example-*`-tiedostot tämän repon oma consumer-CI (dogfood). ADR 0005.
- **Vain Gitea, vain reusable workflowt**: ei custom actioneita, ei multi-platform
- **Commit-status API vain raporttilinkeille**: Tool-jobit luottavat natiiviin. Test-jobit käyttävät API:a koska se on ainoa tapa upottaa raporttilinkki. ADR 0004, 0007.
- **Exit-koodi on ainoa onnistumisen mittari**: Ei pipeä, ei tiedostoheuristiikkaa. ADR 0008.
- **Raportit git-pagesissa**: HTML selailtavissa, retention automaattinen
- **GITHUB_STEP_SUMMARY**: Summary-näkymä raporttilinkeille Gitea 1.27:ssä (forward-compat)

## Common Commands
- Helm-asennus: `helm upgrade --install git-pages ./git-pages -n <ns> -f <values>`
- Julkaisu: `bash scripts/publish-git-pages.sh <report-dir>`
- Status: `bash scripts/report-status.sh <state> <desc> <context> [suite] [url]`

## What NOT to Do
- Älä lisää tukea muille Git-alustoille
- Älä lisää Docker custom actioneita ilman pakottavaa syytä
- Älä kirjoita git-pages-spesifiä tietoa juuren `docs/`-kansioon
- Älä käytä commit-status API:a jollei ole raporttia linkitettäväksi (ADR 0007)
- Älä käytä pipeä `run`-komennon viimeisenä — se syö exit-koodin (ADR 0008)