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
145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# 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` |
|
|
| **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 peilaa suoraan Gitean commit-polun rakennetta, lisäten raportin nimen:
|
|
|
|
```
|
|
https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/commit/14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb/cucumber/index.html
|
|
└────────────── selvä URL ──────────────┘ └──────────────────────── Gitea-yhteensopiva polku ────────────────────────┘
|
|
```
|
|
|
|
Levyllä (apex index-site) polku vastaa URL:ia:
|
|
|
|
```
|
|
/app/data/
|
|
{owner}/
|
|
{repo}/
|
|
commit/
|
|
{sha}/
|
|
{raportin-nimi}/
|
|
index.html
|
|
.meta # branch, sha, published_at
|
|
```
|
|
|
|
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"]
|
|
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](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](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.
|