moilanik
0f2a8a2a8c
CI / call-engine (push) Failing after 2m26s
- ci-engine.yml: 2 dummy test stepiä + agnostinen publish-stage (skannaa .meta-tiedostot, PATCH raportit, postaa status + linkki) - publish-git-pages.sh: palauta BASE URL (ilman index.html) - .meta-formaatti: lisää context, description, state kentät
197 lines
8.8 KiB
Markdown
197 lines
8.8 KiB
Markdown
# 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
|
|
|
|
CronJob `git-pages-retention` (kerran päivässä) skannaa PVC:n ja poistaa vanhentuneet
|
|
raportit. Julkaisija kirjoittaa `reports/{sha8}/.meta` (branch, sha, published_at).
|
|
|
|
| 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` (`default` + `branches.{name}`).
|
|
|
|
**Puutteet:** tagattuja commiteja ei suojata erikseen. RWO-PVC vaatii lyhyen katkon
|
|
(deployment skaalataan 0:ksi ajon ajaksi).
|
|
|
|
Secret: `git-pages-retention-gitea` — Gitea PAT branch-listaan. 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ä) |
|