# AI Context: Gitea Actions CI -kirjasto

**Updated**: 2026-06-12 (POC-vaihe, suunniteltu uudelleenkirjoitus)

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

POC on valmis: raporttien julkaisu git-pagesiin ja commit-status linkillä
toimii.

## Monorepo: kaksi erillistä kokonaisuutta

Tämä repo on käytännössä monorepo, jossa on kaksi itsenäistä osaa:

### 1. Juuri (`gitea-ci-library`)
Provider-kirjasto: reusable workflowt, scriptit, ADRt, dokumentaatio.
Consumer kutsuu `build-feature.yml`-workflowa `uses:`-direktiivillä.

### 2. `git-pages/` — oma kokonaisuus
Helm-chartti Codeberg git-pagesille. Täysin itsenäinen — oma dokumentaatio,
omat tekniset valinnat, oma design-rationale. Kohdeltava kuten se olisi jo
oma reponsa: kaikki git-pages-spesifi tieto kuuluu `git-pages/docs/`- alle,
ei juuren `docs/`-kansioon.

### Rajapinta juuren ja git-pagesin välillä

Ohut ja yksiselitteinen:

```
scripts/publish-git-pages.sh <report-dir>
  → PATCH tar osoitteeseen GIT_PAGES_URL
  → palauttaa BASE URL:n

git-pages tarjoaa:
  - HTTP endpoint (GET/PATCH/PUT)
  - retention (automaattinen)
  - TLS, BasicAuth (Traefik)
```

Juuri ei tiedä git-pagesin sisäisestä toiminnasta (storage v2, .index,
blob-arkkitehtuuri). Git-pages ei tiedä workflowista, scripteistä tai
provider-logiikasta.

## Architecture (POC-tila)
- **Provider & Consumer -malli**: `build-feature.yml` on lukittu rajapinta.
  ADR 0005.
- **Raporttien hostaus**: git-pages Helm-chartilla (`git-pages/`), `GIT_PAGES_URL` määrittää perusosoitteen.
- **Retention**: sidecar samassa podissa, HTTP API localhost:3000,
  Gitea API branch-check.
- **Commit-status**: Gitea Actions näyttää automaattisesti. API vain
  custom-linkkiin. ADR 0004.
- **Julkaisu**: `publish-git-pages.sh` → PATCH tar git-pagesiin.

## Repository Structure

| Path | Purpose |
|---|---|
| `.gitea/workflows/` | Reusable workflowt (`build-feature.yml`, `config-provider.yml`) |
| `scripts/` | `publish-git-pages.sh`, `report-status.sh`, `dispatch-workflow.sh` |
| **`git-pages/`** | **Oma kokonaisuus: Helm-chartti + docs + retention** |
| `docs/` | Root-tason arkkitehtuuri, ADRt (0001–0005) |
| `docs/adr/` | Architecture Decision Records |
| `tests/` | Bats-testit skripteille |
| `.gitea/workflows/ci.yml` | Dogfood — kutsuu `build-feature.yml`:a |

**Tarkemmat git-pages-asiat:** `git-pages/docs/` (implementation-notes,
architecture, design-rationale, secrets, tech-stack).

## Key Technical Decisions
- **Provider & Consumer**: `build-feature.yml` lukittu rajapinta, muu koodi
  vapaasti muutettavissa
- **Vain Gitea, vain reusable workflowt**: ei custom actioneita, ei
  multi-platform
- **Raportit git-pagesissa**: HTML selailtavissa, retention automaattinen
- **Git-pages omana kokonaisuutena**: voi erottaa omaksi repokseen
  tulevaisuudessa

## Tech Stack (POC)
- **Runtime:** Bash, curl, jq, python3 (retention whiteout)
- **Alusta:** Gitea Actions, Gitea act runner
- **Hostaus:** git-pages 0.9.1 (Codeberg), Traefik, cert-manager
- **Integraatiot:** Gitea REST API, Gitea Packages

## 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> <url> <context>`

## 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 —
  kuuluu `git-pages/docs/`-alle
- Älä POSTaa commit-status APIin jokaiselle vaiheelle — natiivi riittää