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

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

git-pages/docs/architecture.md

@@ -0,0 +1,142 @@
+# Architecture — git-pages
+
+> Komponentit, datavirrat ja rajapinnat. Miksi näin on rakennettu: [design-rationale.md](design-rationale.md).
+> Secretit: [secrets.md](secrets.md). Teknologiat: [tech-stack.md](tech-stack.md).
+
+Tämä dokumentti koskee vain `git-pages/`-palvelua — ei juuren `gitea-ci-library`-kirjastoa.
+
+---
+
+## Yleiskuvaus
+
+git-pages on jaettu **HTML-raporttiarkisto**: yksi apex-host, monta Gitea-repoa, commit-kohtaiset
+raporttipolut. Julkaisija (esim. CI) puskaa sisällön tar-arkistona; lukija avaa raportin
+selaimella commit-linkistä.
+
+Codeberg git-pages ajaa `PAGES_INSECURE=1` — sovellus ei tee forge-authia. Julkaisu- ja
+TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit).
+
+---
+
+## Komponentit
+
+| Komponentti | Rooli |
+|-------------|-------|
+| **git-pages Pod** | Codeberg git-pages `0.9.1`, filesystem-storage `/app/data` |
+| **retention sidecar** | Samassa podissa, HTTP API localhost:3000, siivoaa vanhat raportit |
+| **PVC** | Raporttisisältö (storage v2 — `.index` + blob) |
+| **Service** | ClusterIP :3000 git-pagesille |
+| **Traefik IngressRoute** | Julkaisu (PATCH/PUT + BasicAuth) ja luku (GET/HEAD) eri säännöillä |
+| **Traefik Middleware** | `git-pages-publish-auth` (BasicAuth), HTTPS-redirect |
+| **cert-manager Certificate** | TLS → Secret `git-pages-tls` |
+
+| Secret | Rooli |
+|--------|-------|
+| `git-pages-publish-auth` | htpasswd julkaisuun (Traefik) |
+| `git-pages-publish-token` | plaintext token (Gitea Actions -secretiin vietäväksi) |
+| `git-pages-retention-gitea` | Gitea PAT branch-tarkistukseen (sidecar)
+
+---
+
+## URL ja sisältö
+
+Julkinen osoite:
+
+```
+https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/reports/f4baa286/cucumber/index.html
+         └────────── selvä URL ─────────┘ └───────────────── Gitea-yhteensopiva polku ─────────────────────────┘
+```
+
+Levyllä (apex index-site):
+
+```
+/app/data/site/{host}/
+  .index          # Protobuf-manifesti (storage v2 — kaikki tiedostot tässä yhdessä tiedostossa)
+```
+
+Tiedostot eivät ole flat-FS:nä — katso `implementation-notes.md`.
+
+Apex-juuri `/` on tyhjä — ei landing-sivua.
+
+---
+
+## Järjestelmäkaavio
+
+```mermaid
+flowchart TB
+    subgraph ext["Ulkoiset"]
+        PUB["Julkaisija\n(CI)"]
+        BR["Selain"]
+        GITEA["Gitea API\n(branch-lista)"]
+    end
+
+    subgraph edge["Reuna"]
+        TRAEFIK["Traefik\nIngressRoute + Middleware"]
+        CM["cert-manager\nTLS"]
+    end
+
+    subgraph cluster["git-pages Pod"]
+        GP["git-pages\n(kontti)"]
+        RT["retention sidecar\n(kontti)\nHTTP API localhost:3000"]
+        PVC["PVC /app/data"]
+    end
+
+    PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK
+    BR -->|"GET/HEAD"| TRAEFIK
+    TRAEFIK --> GP
+    CM --> TRAEFIK
+    GP --> PVC
+    RT -->|"reads .git-pages/manifest.json\nHTTP localhost"| GP
+    RT -->|"check branches"| GITEA
+```
+
+---
+
+## Julkaisu
+
+1. Julkaisija paketoi `{owner}/{repo}/reports/{sha8}/` tar-arkistoksi (sis. `.meta`)
+2. `PATCH` tai `PUT` apex-URL:iin (`https://{host}/`) + `Content-Type: application/x-tar`
+3. Traefik tarkistaa BasicAuth (`publish` + token) → välittää git-pagesille
+4. git-pages kirjoittaa PVC:lle
+
+Julkaisu kulkee aina julkisen ingressin kautta — ei suoraa ClusterIP-kirjoitusta ulkopuolelta.
+
+---
+
+## Luku
+
+1. Selain avaa commit-statuslinkin (GET/HEAD)
+2. Traefik välittää git-pagesille ilman julkaisu-Middlewarea
+3. git-pages palauttaa HTML:n polusta
+
+Luku-auth (OIDC) ei ole toteutettu — GET/HEAD on julkinen, jos URL tunnetaan.
+Katso [design-rationale.md — Luku-auth](design-rationale.md#luku-auth).
+
+---
+
+## Retention
+
+Sidecar-kontti samassa podissa, ajaa retention-cleanup.sh 24h välein:
+
+1. Lukee `.git-pages/manifest.json` HTTP:lla localhost:3000
+2. Etsii `.meta`-tiedostot, tarkistaa iän ja branchin
+3. **Poistettu branch** — jos `.meta.branch` ei ole Giteassa → whiteout PATCH
+4. **Aktiivinen branch** — `maxAgeDays` + `keepMin` (`retention.rules`)
+5. Whiteout-tar → PATCH localhost:3000 — poistaa raportit
+
+Gitea API: `GET /api/v1/repos/{owner}/{repo}/branches/{branch}` — `read:repository` PAT.
+Katso [secrets.md](secrets.md).
+
+---
+
+## Rajapinnat
+
+| Suunta | Protokolla | Auth | Kuvaus |
+|--------|------------|------|--------|
+| Julkaisija → Traefik | HTTPS PATCH/PUT | BasicAuth `publish` | tar → apex site |
+| Selain → Traefik | HTTPS GET/HEAD | — (tänään) | HTML-raportti |
+| Sidecar → Gitea | HTTPS GET | PAT `read:repository` | branch-tarkistus per repo |
+| Sidecar → git-pages | HTTP :3000 | — (PAGES_INSECURE) | manifestin luku + whiteout PATCH |
+| Traefik → git-pages | HTTP :3000 | — | sisäverkko |
+
+git-pages ei käytä Gitea forge-API:a julkaisuun eikä `pages`-branchia.

git-pages/docs/design-rationale.md

@@ -0,0 +1,198 @@
+# Design Rationale — git-pages
+
+> Miksi git-pages on rakennettu näin. Arvot, periaatteet ja reunaehdot.
+>
+> Tämä dokumentti on **normatiivinen** `git-pages/`-alikansiolle. Se ei kuvaa juuren
+> `gitea-ci-library`-kirjastoa eikä sen workfloweja.
+>
+> Liittyvät dokumentit: [architecture.md](architecture.md), [tech-stack.md](tech-stack.md), [secrets.md](secrets.md).
+
+---
+
+## Miksi tämä on olemassa
+
+### Ongelma
+
+CI-testiajoista syntyy HTML-raportteja. Esimerkiksi Cucumber-testiraportti toimii
+elävänä dokumentaationa git commitin tilasta.
+
+Gitea ei tarjoa web-selaimella selattavaa arkistoa näille HTML-raporteille.
+
+git-pages ratkaisee tämän ongelman.
+
+| Vaihtoehto | Miksi ei riitä |
+|---|---|
+| **Gitea Actions -artifactit** | Vain ZIP-lataus — HTML ei renderöidy selaimessa |
+| **Gitea `pages`-branch** | Yksi branch per repo; rinnakkaiset buildit törmäävät saman branchin pushissa |
+| **Gitea Releases** | Sotkee julkaisuhistorian satojen CI-buildien raporteilla |
+
+### Ongelma URL:ssa (hylätty malli)
+
+Alkuvaiheen malli sitoi hostin repoon: `https://{owner}.{host}/{repo}/...`
+(subdomain per owner). Julkinen linkki piti sitten “kääntää” Gitea-tyyliseksi poluksi
+Traefik-rewritellä (`/{owner}/{repo}/...` → eri `Host` + lyhyempi polku).
+
+Tämä oli ongelmallinen:
+
+- per-owner middleware / rewrite kube-resursseina
+- julkaisu-URL ja lukemis-URL eri muodossa
+- wildcard-TLS tai monimutkainen cert-hallinta
+- vaikea selittää kehittäjälle mistä host tulee
+
+### Ratkaisu — `selvä_url` + Gitea-yhteensopiva polku
+
+URL rakennetaan kahdesta erillisestä osasta, ei yhdestä sekavasta kaavasta:
+
+| Osa | Mistä | Esimerkki |
+|-----|-------|-----------|
+| **Selvä URL** | Organisaation kiinteä pages-host | `https://pages.example.com` |
+| **Gitea-yhteensopiva polku** | Repo (`{owner}/{repo}`) + commit | `/acme-corp/backend-api/reports/abc12345/index.html` |
+
+**Julkinen linkki** = selvä URL + polku (yksi merkkijono commit-statusiin, ei rewritea):
+
+`https://pages.example.com/acme-corp/backend-api/reports/abc12345/index.html`
+
+Polku vastaa Gitea Pages -käytäntöä (`/{owner}/{repo}/...`). Host on aina sama —
+ei `{owner}.pages...`-subdomainia.
+
+**Konkreettinen esimerkki (nykyinen ympäristö):**
+
+| Elementti | Arvo |
+|-----------|------|
+| **Gitea-instanssi** | `gitea.app.keskikuja.site` |
+| **Repo** | `niko/gitea-ci-library` |
+| **Haara** | `plan/0003-alkaa-käyttämään-itseään-commit-raportti` |
+| **Commit SHA** | `14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb` |
+| **Raportin nimi** | `cucumber` (esim.) |
+| **Gitea commit -URL** | `https://gitea.app.keskikuja.site/niko/gitea-ci-library/commit/14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb` |
+| **Raportin julkinen URL** | `https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/commit/14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb/cucumber/index.html` |
+
+Tämä varmistaa, että CI-statuslinkki on suoraan luettavissa ilman domain-rewriteä: raportin polku peilaa täsmälleen Gitean commit-polun rakennetta (`/{owner}/{repo}/commit/{sha}/{raportin-nimi}/`). Koska yksi ajo tuottaa useita raportteja, raportin nimi erottaa ne toisistaan.
+
+Julkaisija (CI tai muu asiakas) lähettää tar-arkiston PATCH/PUT:lla. Lukija hakee
+HTML:n GET:llä. Ei Gitea-git-integraatiota eikä `pages`-branchia.
+
+**Codebergin security-malli ei sovellu tähän käyttöön** — forge-auth (Gitea PAT +
+`write:repository`), DNS TXT -haaste ja muut git-pagesin sisäänrakennetut valtuutus-
+mekanismit on ohitettu kokonaan (`PAGES_INSECURE=1`). Niiden sijaan Kubernetes-kerros
+hoitaa rajauksen: Traefik BasicAuth julkaisuun, cert-manager TLS:ään, erillinen
+publish-token ([secrets.md](secrets.md)). Sovellus palvelee sisältöä; klusteri päättää
+kuka saa kirjoittaa.
+
+---
+
+## Suunnitteluperiaatteet
+
+### 1. Selvä URL + Gitea-yhteensopiva polku
+
+Julkinen osoite = kiinteä apex-host + polku `/{owner}/{repo}/reports/{sha8}/...`.
+Apex-juuri `/` on tyhjä tarkoituksella — ei landing-sivua.
+
+**Miksi:** Kehittäjä näkee Gitea-tyylisen polun; infra näkee yhden hostin. Ei Traefik-
+rewritea, ei per-owner subdomaineja, ei erillistä “julkaisu-URL vs. lukemis-URL” -kaavaa.
+Yksi TLS-sertifikaatti, yksi IngressRoute, yksi PVC.
+
+### 2. Sovelluksen sisäinen security kytketty pois, Traefik hoitaa rajauksen
+
+`git-pages`-sovelluksen koko sisäinen security-mekanismi on kytketty pois päältä (`PAGES_INSECURE=1`). Kirjoitusoikeuden validointi tapahtuu yksinomaan Kubernetes-reunalla Traefik BasicAuth -middlewaren avulla. Sovellus palvelee sisältöä sokeana; klusteri päättää, kuka saa kirjoittaa.
+
+### 3. Julkaisu ja luku erotettu
+
+Julkaisu (PATCH/PUT) vaatii Traefik BasicAuthin. Luku (GET/HEAD) on erillinen reitti — katso [Luku-auth](#luku-auth) alla.
+
+**Miksi:** Koska sovellus ei validoi julkaisuoikeuksia, kirjoitusoikeus on eksplisiittisesti eriytetty Traefik Middlewaressä (`git-pages-publish-auth`).
+
+### 4. Yksi publish-token, kaksi säilöä
+
+Sama plaintext-token: klusterin Secretissä htpasswd-hashina, julkaisijan secret-holvissa
+(esim. CI-alustan Actions-secret).
+
+**Miksi:** Ei Gitea PAT:ia eikä `write:repository` -oikeutta. Token antaa vain
+julkaisuoikeuden tähän palveluun. Yksi arvo, kaksi paikkaa — ks. [secrets.md](secrets.md).
+
+### 5. Secretit erillisessä hallinnassa
+
+`git-pages-publish-auth` luodaan ennen käyttöönottoa — ei osana sovelluksen konfiguraatiotiedostoja.
+
+**Miksi:** Salaisuudet eivät kulje versionoiduissa arvoissa. Rotaatio ja SealedSecrets
+pysyvät operaattorin hallussa. Ks. [secrets.md](secrets.md).
+
+### 6. Minimaalinen parametrisointi
+
+Instance-arvot (`host`, `issuer`, PVC) `{env}-values.yaml`:ssa. Resurssinimet,
+secret-nimet ja Traefik-wire kovakoodattu templatessa.
+
+**Miksi:** Parametrisoi vain se, mikä vaihtelee instanssien välillä (host, TLS-issuer,
+levy). Vakioidut nimet ja wire pysyvät ennustettavina kaikissa asennuksissa.
+
+---
+
+## Puutteet
+
+Tietoisesti avoimet asiat — eivät estä nykyistä julkaisu- ja lukumallia.
+
+### Luku-auth
+
+Julkaisu on suojattu (Traefik BasicAuth). **Luku ei ole:** GET/HEAD on julkinen — kuka
+tuntee URL:n voi lukea raportin.
+
+Tavoite: Traefik OIDC GET/HEAD-reitille (Gitea OAuth2 -provider). Session säilyy —
+commit-statuslinkki toimii kirjautumisen jälkeen ilman uutta julkaisuoikeutta.
+
+Ei toteutettu. Julkaisu- ja luku-reitit pysyvät erillisinä; OIDC lisätään vain lukupuolelle.
+
+### Retention
+
+Sidecar samassa podissa (HTTP localhost:3000), ajaa retention-cleanup.sh
+24h välein:
+
+| Sääntö | Konfiguroitavissa? | Kuvaus |
+|--------|-------------------|--------|
+| **Poistettu branch** | Ei — aina | Jos `.meta.branch` ei ole Giteassa enää, raportti poistetaan |
+| **maxAgeDays** | Kyllä (`dev-values`) | Aktiivisen branchin raportit vanhemmat kuin N päivää |
+| **keepMin** | Kyllä (`dev-values`) | Aktiivisella branchilla pidetään vähintään N uusinta |
+
+Poistettujen branchien siivous ei tarvitse parametreja. Jäljelle jääneille
+branchille säännöt tulevat `retention.rules` (`branches.default` +
+`branches.{name}`).
+
+Ei PVC-skaalausta — sidecar lukee manifestin HTTP:lla ja poistaa whiteout
+PATCHilla. Ei K8s API -oikeuksia.
+
+Secret: `git-pages-retention-gitea` — Gitea PAT branch-tarkistukseen.
+Ks. [secrets.md](secrets.md).
+
+---
+
+## Rajat
+
+- **Ei forge-integraatiota** — ei `pages`-branchia, ei Gitea API -hakua, ei forge-authia
+- **Ei julkaisijalogiikkaa** — kuka julkaisee ja milloin on julkaisijan vastuulla
+- **Ei sisäverkon ohitusjulkaisua** — julkaisu kulkee julkisen ingressin kautta (BasicAuth)
+
+---
+
+## Teknologiavalinnat
+
+| Valinta | Miksi |
+|---------|-------|
+| **Codeberg git-pages** `0.9.1` | Natiivi apex index-site + tar-pohjainen PATCH/PUT -julkaisu |
+| **Filesystem + PVC** | Yksinkertainen, yksi replica, ei erillistä objektivarastoa |
+| **Traefik IngressRoute + Middleware** | Julkaisuauth erillään sovelluksesta; GET/HEAD eri säännöllä |
+| **cert-manager** | TLS automaattisesti (`git-pages-tls`) |
+| **Helm v3** | Toistettava asennus; instanssikohtaiset arvot erillisessä values-tiedostossa |
+
+---
+
+## Mitä tietoisesti hylättiin
+
+| Hylätty | Syy |
+|---------|-----|
+| **deadnews/gitea-pages** | Vetää sisällön Gitea API:sta — ei sopinut CI-push-malliin |
+| **Gitea `pages`-branch** | Race condition rinnakkaisissa buildeissa |
+| **Per-owner subdomain** (`{owner}.pages...`) | Ongelmallinen URL; vaatii rewrite-middlewarea polun kääntämiseen |
+| **Traefik path→host -rewrite** | Korvattu apex + Gitea-polulla — yksi selvä URL commit-linkissä |
+| **Gitea forge-auth / PAT** | `write:repository` liian laaja oikeus vain raporttijulkaisuun |
+| **DNS TXT -haaste julkaisuun** | Operatiivinen kompleksisuus ilman hyötyä BasicAuthiin verrattuna |
+| **Helm-managed publish Secret** | Arvot values-tiedostoihin on kielletty; manuaalinen lähde totuudelle |
+| **Image tag `v0.9.1`** | Oikea tagi on `0.9.1` (ei `v`-etuliitettä) |

git-pages/docs/implementation-notes.md

@@ -0,0 +1,43 @@
+# Implementation Notes
+
+Teknisiä huomioita git-pages 0.9.1:n käyttäytymisestä, joita ei ole ilmeistä
+dokumentaatiosta.
+
+## Storage v2 (Protobuf manifest)
+
+Git-pages 0.9.1 käyttää v2-arkkitehtuuria. Kaikki sisältö on pakattu
+Protobuf-manifestiin (`site/{host}/.index`), ei flat-FS:nä. Tästä seuraa:
+
+- Tiedostoja ei voi etsiä tai poistaa `find`/`rm`-komennoilla
+- `.git-pages/manifest.json` listaa kaikki tiedostot (ProtoJSON)
+- `.git-pages/archive.tar` antaa koko sisällön (saattaa truncata HTTP/2:ssa)
+
+## Host-header
+
+Git-pages valitsee sivuston Host-headerin perusteella. Ilman oikeaa Hostia
+palauttaa 404.
+
+- Ulkoiset requestit: Traefik välittää alkuperäisen Hostin automaattisesti
+- Sidecar/localhost: `-H "Host: ci-reports.helm-dev.keskikuja.site"`
+
+## PATCH ja directory-entryt
+
+Jos PATCH-tar sisältää directory-entryn (tyyppi directory, tar typeflag '5'),
+se **korvaa** koko hakemiston dokumentaation mukaan. Tar saa sisältää vain
+file- ja symlink-entryjä, jotta PATCH toimii odotetusti.
+
+## Whiteout — tiedostojen poisto
+
+Ainoa tapa poistaa tiedostoja ilman koko sivuston PUT-korvausta:
+
+- Tarissa character device entry (`CHRTYPE`, tar typeflag '4')
+- `devmajor=0`, `devminor=0`
+- PATCH:ataan sivuston juureen
+
+## .init — ensimmäinen julkaisu
+
+Ensimmäinen julkaisu vaatii PUTin, joka luo `.index`-tiedoston. Tämän jälkeen
+PATCH riittää.
+
+Helm-chartin post-install -job hoitaa tämän automaattisesti:
+consumerien publish-scriptien ei tarvitse tuntea asennuksen tilaa.

git-pages/docs/secrets.md

@@ -0,0 +1,237 @@
+# Secrets — git-pages
+
+## Quick Start
+
+### Vaihe 1: Secret-arkkitehtuuri
+
+Järjestelmässä on kaksi loogista salaista arvoa. Publish-token jaetaan kahteen K8s-secretiin (Traefik-yhteensopivuus):
+
+| Looginen nimi | K8s | Gitea |
+|---|---|---|
+| `report_publish_api_token` (htpasswd) | `git-pages-publish-auth` (users) | - |
+| `report_publish_api_token` (plaintext) | `git-pages-publish-token` (token) | Actions Secret: `GIT_PAGES_PUBLISH_TOKEN` |
+| `reports_retention_read_token` | `git-pages-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
+
+**Huomio:** Publish-token jaetaan kahteen secretiin, koska Traefik BasicAuth middleware vaatii single-key secretin sekä on muodossa, missä sitä ei saa takaisin. Jokainen repo mikä raportteja käyttää, tarvitsee selväkielisen arvon, joka on "ylimääräisessä" secretissä. 
+
+### Vaihe 2: Luo Gitea PAT (retention)
+
+**Avaa Gitea browserissa:**
+
+1. Kirjaudu Gitea-käyttäjällä, jolla on luku kaikkiin raporttirepoihin
+2. **Settings** → **Applications** → **Generate New Token**
+3. Token name: `CI-REPORTS_READ_FOR_RETENTION`
+4. Scopes: valitse vain **`read:repository`**
+5. **Generate Token** → **kopioi token heti** (näytetään vain kerran)
+6. Tallenna token talteen (`GITEA_RETENTION_TOKEN`)
+
+### Vaihe 3: Generoi publish-token
+
+**Palaa terminaalille:**
+
+```bash
+GITEA_RETENTION_TOKEN="<from Gitea>"
+
+GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
+echo "Publish-token generoitu. Tallennetaan K8s-secretiin Vaiheessa 4."
+echo "$GIT_PAGES_PUBLISH_TOKEN"
+```
+
+### Vaihe 4: Luo K8s secrets
+
+```bash
+NS=git-pages
+
+# 1. Publish-auth: htpasswd (Traefik BasicAuth - vaatii single-key secretin)
+kubectl create secret generic git-pages-publish-auth \
+  --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
+  -n "$NS"
+
+# 2. Publish-token: plaintext (luetaan README:stä Giteaan viedessä)
+kubectl create secret generic git-pages-publish-token \
+  --from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
+  -n "$NS"
+
+# 3. Retention (käyttää Vaiheessa 2 luotua PAT:ia)
+kubectl create secret generic git-pages-retention-gitea \
+  --from-literal=token="$GITEA_RETENTION_TOKEN" \
+  -n "$NS"
+
+kubectl get secrets -n "$NS"
+```
+
+---
+
+### Seuraava: Helm-asennus
+
+Palaa takaisin [README.md](../README.md#käyttöönotto) ja jatka kohdasta "Instanssin values-tiedosto".
+
+---
+
+## Secret Arkkitehtuuri
+
+### Loogiset salaisuudet
+
+| Looginen nimi | K8s | Gitea |
+|---|---|---|
+| `report_publish_api_token` | `git-pages-publish-auth` (htpasswd) | Actions Secret: `GIT_PAGES_PUBLISH_TOKEN` |
+| `reports_retention_read_token` | `git-pages-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
+
+### Secret Reference Architecture
+
+```mermaid
+graph TD
+    subgraph "Publish Flow"
+        P1["Actions Secret<br/>GIT_PAGES_PUBLISH_TOKEN"]
+        P2["K8s Secret<br/>git-pages-publish-auth"]
+        P1 -->|token| TRAEFIK
+        P2 -->|htpasswd| TRAEFIK
+        TRAEFIK["Traefik BasicAuth"]
+    end
+
+    subgraph "Retention Flow"
+        R1["K8s Secret<br/>git-pages-retention-gitea"]
+        R2["Gitea PAT<br/>CI-REPORTS_READ_FOR_RETENTION"]
+        R1 -->|token| SC["Sidecar"]
+        SC -->|API auth| GITEA["Gitea API"]
+        SC -->|read branches| GITEA
+    end
+```
+
+---
+
+## Data Flow
+
+### Flow 1: Julkaisu (Publish)
+
+```mermaid
+sequenceDiagram
+    participant Actions as Gitea Actions
+    participant Traefik as Traefik
+    participant K8sAuth as K8s Secret<br/>git-pages-publish-auth
+    participant K8sToken as K8s Secret<br/>git-pages-publish-token
+    participant GP as git-pages
+
+    Note over Actions: 1. Lue plaintext-token
+    Actions->>K8sToken: lue token-avain
+    K8sToken-->>Actions: plaintext token
+
+    Note over Actions: 2. Lähettää raportin
+    Actions->>Traefik: PUT / + BasicAuth<br/>publish:TOKEN + repo-url
+    Traefik->>K8sAuth: lue users (htpasswd)
+    K8sAuth-->>Traefik: publish:$apr1$...
+    alt Token match
+        Traefik->>GP: välitä
+        GP-->>Traefik: 200 OK
+        Traefik-->>Actions: 200 OK
+    else Token ei match
+        Traefik-->>Actions: 401 Unauthorized
+    end
+```
+
+**Kaksi secretiä (Traefik-yhteensopivuus):**
+- `git-pages-publish-auth` = `users` (htpasswd, Traefik käyttää)
+- `git-pages-publish-token` = `token` (plaintext, luetaan Giteaan viedessä)
+
+---
+
+### Flow 2: Luku (Read)
+
+```mermaid
+sequenceDiagram
+    participant Browser as Selain
+    participant Traefik as Traefik
+    participant GP as git-pages
+
+    Browser->>Traefik: GET /OWNER/REPO/commit/SHA/raportti/index.html
+    Traefik->>GP: välitä (ei authia)
+    GP-->>Traefik: HTML
+    Traefik-->>Browser: HTML
+```
+
+GET/HEAD-reitillä ei ole Middlewarea. Luku on julkinen, jos URL tunnetaan.
+
+---
+
+### Flow 3: Retention (Siivous)
+
+```mermaid
+sequenceDiagram
+    participant Sidecar as Retention Sidecar
+    participant K8sSecret as K8s Secret<br/>git-pages-retention-gitea
+    participant GiteaAPI as Gitea API
+    participant GP as git-pages (localhost:3000)
+
+    Note over Sidecar: 1. Lue PAT
+    Sidecar->>K8sSecret: lue token
+    K8sSecret-->>Sidecar: Gitea PAT
+
+    Note over Sidecar: 2. Lue manifest
+    Sidecar->>GP: GET .git-pages/manifest.json
+    GP-->>Sidecar: sisällysluettelo
+
+    Note over Sidecar: 3. Kysy branch
+    Sidecar->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches/BRANCH
+    GiteaAPI-->>Sidecar: 200 / 404
+
+    Note over Sidecar: 4. Luo whiteout-tar + PATCH
+    Sidecar->>GP: PATCH / (whiteout)
+    GP-->>Sidecar: 200 OK
+```
+
+**Huomio:** Retention-PAT:in omistajalla on oltava lukuoikeus KAIKKIIN repoihin,
+joista raportteja on PVC:llä.
+
+---
+
+## Troubleshooting
+
+- **"secret not found"** — luiko secretit ennen Helm-asennusta?
+- **"401 Unauthorized"** — onko Gitea Actions secret oikea?
+- **"found 2 elements for secret"** — Traefik vaatii single-key secretin. Varmista että `git-pages-publish-auth` sisältää vain `users`-avaimen.
+- **"token hukkuu"** — generoi uusi token (Vaihe 3) ja päivitä molemmat publish-secretit:
+  ```bash
+  # 1. Generoi uusi
+  GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
+
+  # 2. Päivitä K8s secrets (molemmat)
+  NS=git-pages
+  kubectl delete secret git-pages-publish-auth -n "$NS"
+  kubectl delete secret git-pages-publish-token -n "$NS"
+  
+  kubectl create secret generic git-pages-publish-auth \
+    --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
+    -n "$NS"
+  
+  kubectl create secret generic git-pages-publish-token \
+    --from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
+    -n "$NS"
+
+  # 3. Päivitä Gitea Actions secret jokaisessa repoissa (luke README:stä)
+  ```
+
+## Automatisointi: useamman repon salaisuuden lisääminen
+
+Jos repoja on monta, voit käyttää Gitea API:ta (vaatii admin-tokenin):
+
+```bash
+ADMIN_TOKEN="<gitea-admin-token>"
+NS=git-pages
+
+# Lue plaintext-token erillisestä secretistä
+TOKEN=$(kubectl get secret git-pages-publish-token -n "$NS" -o jsonpath='{.data.token}' | base64 -d)
+
+for repo in "owner/repo1" "owner/repo2" "owner/repo3"; do
+  curl -X POST "https://gitea.example.com/api/v1/repos/$repo/actions/secrets" \
+    -H "Authorization: token $ADMIN_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d "{\"name\":\"GIT_PAGES_PUBLISH_TOKEN\",\"data\":\"$TOKEN\"}"
+done
+```
+
+Tai `tea` CLI:lla (Gitea:n virallinen CLI):
+
+```bash
+tea actions secrets add --repo owner/repo1 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"
+tea actions secrets add --repo owner/repo2 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"
+```

git-pages/docs/tech-stack.md

@@ -0,0 +1,81 @@
+# Tech Stack — git-pages
+
+> Mitä teknologioita `git-pages/` Helm chart käyttää ja edellyttää. Tämä dokumentti koskee vain
+> `git-pages/`-alikansiota monorepossa — ei juuren `gitea-ci-library`-kirjastoa.
+
+---
+
+## Sovellus
+
+| Teknologia | Versio | Käyttö |
+|---|---|---|
+| **git-pages** (Codeberg) | `0.9.1` | Staattinen sisältö, apex index-site (`/.index`), HTTP PATCH/PUT -julkaisu |
+| **Filesystem storage** | — | Sisältö PVC:llä (`/app/data`) |
+| **TOML** | — | Sovellusconfig ConfigMapissa (`config.toml`) |
+
+Image: `codeberg.org/git-pages/git-pages:0.9.1` (ei `v`-etuliitettä tagissa).
+
+Chart ajaa `PAGES_INSECURE=1` — julkaisuvaltuutus Traefik Middlewaressä, ei forge-authia.
+
+---
+
+## Alusta ja verkko
+
+| Teknologia | Versio / minimi | Käyttö |
+|---|---|---|
+| **Kubernetes** | 1.24+ | Deployment, Service, PVC, Secret |
+| **Helm** | v3 | Chart asennus ja päivitys |
+| **Traefik** | CRD `traefik.io/v1alpha1` | IngressRoute, Middleware (`basicAuth`, HTTPS-redirect) |
+| **cert-manager** | — | TLS-sertifikaatti (`git-pages-tls`) |
+
+---
+
+## Pysyvyys
+
+| Teknologia | Käyttö |
+|---|---|
+| **PersistentVolumeClaim** | Raporttisisältö (`ReadWriteOnce`) |
+| **storageClass** | Instance-kohtainen (`dev-values.yaml`) |
+
+---
+
+## Esiehdot (klusteri)
+
+| Resurssi | Lähde | Dokumentti |
+|---|---|---|
+| `git-pages-publish-auth` | Manuaalinen Secret | [secrets.md](secrets.md) |
+| `git-pages-tls` | cert-manager Certificate | Automaattinen asennuksessa |
+| `ClusterIssuer` | Klusteri (esim. `letsencrypt-prod`) | `dev-values.yaml` |
+
+---
+
+## Asennustyökalut (operaattori)
+
+| Työkalu | Käyttö |
+|---|---|
+| **kubectl** | Secretin luonti |
+| **openssl** | Publish-tokenin generointi (`rand -base64 24`) |
+| **Docker** (`httpd:2-alpine`) | htpasswd-rivin generointi |
+
+---
+
+## Konfiguraatio
+
+| Tiedosto | Kerros | Sisältö |
+|---|---|---|
+| `values.yaml` | Chart-vakiot | Image, resurssit, Traefik entrypointit |
+| `{env}-values.yaml` | Instanssi | Host, issuer, PVC koko/storageClass |
+
+Esimerkki: `helm upgrade --install git-pages ./git-pages -n git-pages -f dev-values.yaml`
+
+---
+
+## Mitä EI käytetä
+
+| Teknologia | Syy |
+|---|---|
+| **Gitea `pages`-branch** | Ei Gitea git-pages -integraatiota |
+| **deadnews/gitea-pages** | Ei Gitea API -hakua |
+| **MinIO / S3** | Erillinen raporttivarasto — ei tämän chartin scope |
+| **Gitea forge-auth / PAT** | Julkaisu BasicAuth-tokenilla (`git-pages-publish-auth`) |
+| **Helm-managed publish Secret** | `publishAuth.create: false` — secret manuaalisesti |