niko/gitea-ci-library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: POC — gitea-pages report publish + commit status
CI / call-engine (push) Failing after 2m26s
Details

Browse Source 
- 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
This commit is contained in:
moilanik
2026-06-12 07:48:15 +03:00
parent 26a8b9efa8
commit 0f2a8a2a8c
15 changed files with 671 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files
git-pages/docs/architecture.md
+9 -8
View File
@@ -39,23 +39,24 @@ TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit).
## URL ja sisältö
Julkinen osoite = **selvä URL** + **Gitea-yhteensopiva polku**:
Julkinen osoite peilaa suoraan Gitean commit-polun rakennetta, lisäten raportin nimen:
```
https://pages.example.com/acme-corp/backend-api/reports/abc12345/index.html
└─ selvä URL ─┘ └────────── Gitea-yhteensopiva polku ──────────┘
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):
Levyllä (apex index-site) polku vastaa URL:ia:
```
/app/data/
{owner}/
{repo}/
reports/
{sha8}/
index.html
.meta # branch, sha, published_at
commit/
{sha}/
{raportin-nimi}/
index.html
.meta # branch, sha, published_at
```
Apex-juuri `/` on tyhjä — ei landing-sivua.
git-pages/docs/design-rationale.md
+24 -8
View File
@@ -55,6 +55,20 @@ URL rakennetaan kahdesta erillisestä osasta, ei yhdestä sekavasta kaavasta:
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.
@@ -78,15 +92,17 @@ Apex-juuri `/` on tyhjä tarkoituksella — ei landing-sivua.
rewritea, ei per-owner subdomaineja, ei erillistä “julkaisu-URL vs. lukemis-URL” -kaavaa.
Yksi TLS-sertifikaatti, yksi IngressRoute, yksi PVC.
### 2. Julkaisu ja luku erotettu
### 2. Sovelluksen sisäinen security kytketty pois, Traefik hoitaa rajauksen
Julkaisu (PATCH/PUT) vaatii Traefik BasicAuthin. Luku (GET/HEAD) on erillinen reitti —
katso [Luku-auth](#luku-auth) alla.
`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.
**Miksi:** git-pages ajaa `PAGES_INSECURE=1` — sovellus ei validoi julkaisuoikeuksia.
Kirjoitusoikeus on eksplisiittisesti Traefik Middlewaressä (`git-pages-publish-auth`).
### 3. Julkaisu ja luku erotettu
### 3. Yksi publish-token, kaksi säilöä
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).
@@ -94,14 +110,14 @@ Sama plaintext-token: klusterin Secretissä htpasswd-hashina, julkaisijan 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).
### 4. Secretit erillisessä hallinnassa
### 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).
### 5. Minimaalinen parametrisointi
### 6. Minimaalinen parametrisointi
Instance-arvot (`host`, `issuer`, PVC) `{env}-values.yaml`:ssa. Resurssinimet,
secret-nimet ja Traefik-wire kovakoodattu templatessa.
git-pages/docs/secrets.md
+207 -66
View File
@@ -1,96 +1,237 @@
# Secrets - Prerequisites
# Secrets — git-pages
`git-pages` requires the following Kubernetes Secrets to exist before the cluster
consumers can use them. These secrets are not managed by Helm — create them manually or
via external secret management (SealedSecrets, External Secrets Operator, Vault).
## Quick Start
TLS (`git-pages-tls`) is issued by cert-manager — not a manual prerequisite.
### Vaihe 1: Secret-arkkitehtuuri
---
Järjestelmässä on kaksi loogista salaista arvoa. Publish-token jaetaan kahteen K8s-secretiin (Traefik-yhteensopivuus):
## Secret Inventory
| Looginen nimi | K8s | Gitea |
|---|---|---|
| `report_publish_api_token` (htpasswd) | `git-pages-publish-auth` (users) | - |
| `report_publish_api_token` (plaintext) | `git-pages-publish-token` (token) | Actions Secret: `GIT_PAGES_PUBLISH_TOKEN` |
| `reports_retention_read_token` | `git-pages-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
| Secret | Keys | Consumers | Required |
|--------|------|-----------|----------|
| `git-pages-publish-auth` | `users` | Traefik Middleware `git-pages-publish-auth` | Always |
| `git-pages-retention-gitea` | `token` | CronJob `git-pages-retention` | Always |
**Huomio:** Publish-token jaetaan kahteen secretiin, koska Traefik BasicAuth middleware vaatii single-key secretin sekä on muodossa, missä sitä ei saa takaisin. Jokainen repo mikä raportteja käyttää, tarvitsee selväkielisen arvon, joka on "ylimääräisessä" secretissä.
---
### Vaihe 2: Luo Gitea PAT (retention)
## Tokens
### Publish token
Ei Gitea PAT. Satunnainen merkkijono (`GIT_PAGES_PUBLISH_TOKEN`), joka menee kahteen paikkaan:
| Paikka | Muoto |
|--------|-------|
| Kubernetes `git-pages-publish-auth` | htpasswd: `publish:<hash>` |
| Gitea Actions secret `GIT_PAGES_PUBLISH_TOKEN` | sama plaintext |
CI käyttää sitä Traefik BasicAuthiin. Ei git-kirjoitusoikeutta.
**Vienti Giteaan:** Organization or Repository → Settings → Actions → Secrets →
`GIT_PAGES_PUBLISH_TOKEN` = publish-tokenin plaintext (org secret, jos usea repo julkaisee).
### Retention token
Gitea PAT CronJobille. CronJob listaa branchit repokohtaisesti
(`GET /api/v1/repos/{owner}/{repo}/branches`) ja poistaa raportit, joiden `.meta.branch`
ei ole enää Giteassa.
Tarvitaan vain **`read:repository`**. Ei `write:repository`. Tokenin omistajan täytyy
nähdä kaikki repot, joista raportteja on levyllä.
**Ei viedä Giteaan** — vain Kubernetes Secret `git-pages-retention-gitea`.
**PAT Giteassa (read only):**
**Avaa Gitea browserissa:**
1. Kirjaudu Gitea-käyttäjällä, jolla on luku kaikkiin raporttirepoihin
2. **Settings** → **Applications** → **Generate New Token**
3. Token name: esim. `git-pages-retention`
4. Scopes: valitse vain **`read:repository`** — älä valitse `write:repository` eikä muita
5. **Generate Token** → kopioi token heti (näytetään vain kerran)
6. Aseta shelliin: `export GITEA_RETENTION_TOKEN='gitea_pat_…'`
3. Token name: `CI-REPORTS_READ_FOR_RETENTION`
4. Scopes: valitse vain **`read:repository`**
5. **Generate Token** → **kopioi token heti** (näytetään vain kerran)
6. Tallenna token talteen (`GITEA_RETENTION_TOKEN`)
---
### Vaihe 3: Generoi publish-token
## Create Secrets
**Palaa terminaalille:**
```bash
GITEA_RETENTION_TOKEN="<from Gitea>"
GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
echo "Publish-token generoitu. Tallennetaan K8s-secretiin Vaiheessa 4."
echo "$GIT_PAGES_PUBLISH_TOKEN"
```
### Vaihe 4: Luo K8s secrets
```bash
NS=git-pages
# Publish
GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
# 1. Publish-auth: htpasswd (Traefik BasicAuth - vaatii single-key secretin)
kubectl create secret generic git-pages-publish-auth \
--from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
-n $NS
-n "$NS"
echo "Gitea Actions → GIT_PAGES_PUBLISH_TOKEN:"
echo "$GIT_PAGES_PUBLISH_TOKEN"
# 2. Publish-token: plaintext (luetaan README:stä Giteaan viedessä)
kubectl create secret generic git-pages-publish-token \
--from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
-n "$NS"
# Retention (PAT luotu yllä Giteassa)
# 3. Retention (käyttää Vaiheessa 2 luotua PAT:ia)
kubectl create secret generic git-pages-retention-gitea \
--from-literal=token="$GITEA_RETENTION_TOKEN" \
-n $NS
-n "$NS"
kubectl get secrets -n $NS
kubectl get secrets -n "$NS"
```
---
## Secret Management (Production)
### Seuraava: Helm-asennus
Secrets can be created manually with the snippets above, or migrated to a secret management
solution. The `kubectl create` blocks are the rolling source — replace them with the target
tool's equivalent when ready:
Palaa takaisin [README.md](../README.md#käyttöönotto) ja jatka kohdasta "Instanssin values-tiedosto".
| Approach | Replaces `kubectl create` with |
|----------|-------------------------------|
| Manual rotation | Re-run the same snippets with new values |
| SealedSecrets | `kubeseal` encrypted manifest |
| External Secrets Operator | `ExternalSecret` CR pointing to the vault |
| Vault / other | Vault agent / CSI driver injection |
---
Structure of `docs/secrets.md` stays identical regardless of the chosen approach.
## Secret Arkkitehtuuri
### Loogiset salaisuudet
| Looginen nimi | K8s | Gitea |
|---|---|---|
| `report_publish_api_token` | `git-pages-publish-auth` (htpasswd) | Actions Secret: `GIT_PAGES_PUBLISH_TOKEN` |
| `reports_retention_read_token` | `git-pages-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
### Secret Reference Architecture
```mermaid
graph TD
subgraph "Publish Flow"
P1["Actions Secret<br/>GIT_PAGES_PUBLISH_TOKEN"]
P2["K8s Secret<br/>git-pages-publish-auth"]
P1 -->|token| TRAEFIK
P2 -->|htpasswd| TRAEFIK
TRAEFIK["Traefik BasicAuth"]
end
subgraph "Retention Flow"
R1["K8s Secret<br/>git-pages-retention-gitea"]
R2["Gitea PAT<br/>CI-REPORTS_READ_FOR_RETENTION"]
R1 -->|token| CJ["CronJob"]
R2 -->|API auth| GITEA["Gitea API"]
CJ -->|read branches| GITEA
end
```
---
## Data Flow
### Flow 1: Julkaisu (Publish)
```mermaid
sequenceDiagram
participant Actions as Gitea Actions
participant Traefik as Traefik
participant K8sAuth as K8s Secret<br/>git-pages-publish-auth
participant K8sToken as K8s Secret<br/>git-pages-publish-token
participant GP as git-pages
Note over Actions: 1. Lue plaintext-token
Actions->>K8sToken: lue token-avain
K8sToken-->>Actions: plaintext token
Note over Actions: 2. Lähettää raportin
Actions->>Traefik: PUT / + BasicAuth<br/>publish:TOKEN + repo-url
Traefik->>K8sAuth: lue users (htpasswd)
K8sAuth-->>Traefik: publish:$apr1$...
alt Token match
Traefik->>GP: välitä
GP-->>Traefik: 200 OK
Traefik-->>Actions: 200 OK
else Token ei match
Traefik-->>Actions: 401 Unauthorized
end
```
**Kaksi secretiä (Traefik-yhteensopivuus):**
- `git-pages-publish-auth` = `users` (htpasswd, Traefik käyttää)
- `git-pages-publish-token` = `token` (plaintext, luetaan Giteaan viedessä)
---
### Flow 2: Luku (Read)
```mermaid
sequenceDiagram
participant Browser as Selain
participant Traefik as Traefik
participant GP as git-pages
Browser->>Traefik: GET /OWNER/REPO/commit/SHA/raportti/index.html
Traefik->>GP: välitä (ei authia)
GP-->>Traefik: HTML
Traefik-->>Browser: HTML
```
GET/HEAD-reitillä ei ole Middlewarea. Luku on julkinen, jos URL tunnetaan.
---
### Flow 3: Retention (Siivous)
```mermaid
sequenceDiagram
participant CronJob as CronJob<br/>git-pages-retention
participant K8sSecret as K8s Secret<br/>git-pages-retention-gitea
participant GiteaAPI as Gitea API
participant PVC as PVC /app/data
Note over CronJob: 1. Lue PAT
CronJob->>K8sSecret: lue token
K8sSecret-->>CronJob: Gitea PAT
Note over CronJob: 2. Skaalaa deployment 0:aan
CronJob->>PVC: lue .meta-tiedostot
Note over CronJob: 3. Kysy branch-lista
CronJob->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches
GiteaAPI-->>CronJob: branch names
Note over CronJob: 4. Vertaa ja poista
CronJob->>PVC: poista vanhentuneet
Note over CronJob: 5. Skaalaa deployment 1:een
```
**Huomio:** Retention-PAT:in omistajalla on oltava lukuoikeus KAIKKIIN repoihin,
joista raportteja on PVC:llä.
---
## Troubleshooting
- **"secret not found"** — luiko secretit ennen Helm-asennusta?
- **"401 Unauthorized"** — onko Gitea Actions secret oikea?
- **"found 2 elements for secret"** — Traefik vaatii single-key secretin. Varmista että `git-pages-publish-auth` sisältää vain `users`-avaimen.
- **"token hukkuu"** — generoi uusi token (Vaihe 3) ja päivitä molemmat publish-secretit:
```bash
# 1. Generoi uusi
GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
# 2. Päivitä K8s secrets (molemmat)
NS=git-pages
kubectl delete secret git-pages-publish-auth -n "$NS"
kubectl delete secret git-pages-publish-token -n "$NS"
kubectl create secret generic git-pages-publish-auth \
--from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
-n "$NS"
kubectl create secret generic git-pages-publish-token \
--from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
-n "$NS"
# 3. Päivitä Gitea Actions secret jokaisessa repoissa (luke README:stä)
```
## Automatisointi: useamman repon salaisuuden lisääminen
Jos repoja on monta, voit käyttää Gitea API:ta (vaatii admin-tokenin):
```bash
ADMIN_TOKEN="<gitea-admin-token>"
NS=git-pages
# Lue plaintext-token erillisestä secretistä
TOKEN=$(kubectl get secret git-pages-publish-token -n "$NS" -o jsonpath='{.data.token}' | base64 -d)
for repo in "owner/repo1" "owner/repo2" "owner/repo3"; do
curl -X POST "https://gitea.example.com/api/v1/repos/$repo/actions/secrets" \
-H "Authorization: token $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\":\"GIT_PAGES_PUBLISH_TOKEN\",\"data\":\"$TOKEN\"}"
done
```
Tai `tea` CLI:lla (Gitea:n virallinen CLI):
```bash
tea actions secrets add --repo owner/repo1 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"
tea actions secrets add --repo owner/repo2 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"
```