gitea-ci-library/git-pages/docs/architecture.md

Architecture — git-pages

Komponentit, datavirrat ja rajapinnat. Miksi näin on rakennettu: design-rationale.md. Secretit: secrets.md. Teknologiat: 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

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.

---

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.

---

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.