gitea-ci-library/git-pages/docs/design-rationale.md

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, tech-stack.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). 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 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.

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.

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.

---

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ä)