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
PVC	Raporttisisältö ({owner}/{repo}/reports/{sha8}/…)
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
CronJob git-pages-retention	Päivittäinen siivous (PVC + Gitea branch-lista)

Secret	Rooli
git-pages-publish-auth	htpasswd julkaisuun (Traefik)
git-pages-retention-gitea	Gitea PAT branch-listaan (CronJob)

---

URL ja sisältö

Julkinen osoite = selvä URL + Gitea-yhteensopiva polku:

https://pages.example.com/acme-corp/backend-api/reports/abc12345/index.html
         └─ selvä URL ─┘ └────────── Gitea-yhteensopiva polku ──────────┘

Levyllä (apex index-site):

/app/data/
  {owner}/
    {repo}/
      reports/
        {sha8}/
          index.html
          .meta          # branch, sha, published_at

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"]
        GP["git-pages Pod"]
        PVC["PVC /app/data"]
        CJ["CronJob retention"]
    end

    PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK
    BR -->|"GET/HEAD"| TRAEFIK
    TRAEFIK --> GP
    CM --> TRAEFIK
    GP --> PVC
    CJ -->|"read branches"| GITEA
    CJ --> PVC

---

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

CronJob git-pages-retention (oletus kerran päivässä):

1. Skaalaa git-pages deployment hetkeksi pois (RWO-PVC)
2. Käy läpi reports/{sha8}/.meta
3. Poistettu branch — jos .meta.branch ei ole Gitean branch-listassa → poista (aina)
4. Aktiivinen branch — maxAgeDays + keepMin (retention.rules instanssiarvoissa)
5. Skaalaa deployment takaisin

Gitea API: GET /api/v1/repos/{owner}/{repo}/branches — 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
CronJob → Gitea	HTTPS GET	PAT read:repository	branch-lista per repo
Traefik → git-pages	HTTP :3000	—	sisäverkko

git-pages ei käytä Gitea forge-API:a julkaisuun eikä pages-branchia.