gitea-ci-library/docs/report-hosting.md

Raporttivarasto — MinIO

Kuuluu arkkitehtuuriin: architecture.md. Tämä dokumentti määrittelee testiraporttien tallennuksen, URL-rakenteen, autentikoinnin ja retention policyn.

---

Miksi MinIO

Gitea Actionsin sisäänrakennettu artifact-järjestelmä ei tue HTML-selailtavuutta (vain ZIP-lataus), ja artifactien retentio on aikapohjainen (oletus 90 vrk). Jenkins-versiossa raportit olivat selailtavissa suoraan buildista ja pysyivät build-historian mukana.

MinIO täyttää tämän aukon:

• S3-yhteensopiva — standardi API, laaja työkalutuki (mc, s3cmd, AWS SDK)
• Staattinen web-hosting — HTML-raportit renderöityvät selaimessa suoraan bucketista
• Kubernetes-natiivi — yksi binääri, helppo deployata samaan klusteriin
• Ei per-repo-konfiguraatiota — yksi bucket palvelee kaikkia projekteja
• Ennustettava URL — polku rakentuu deterministisesti reposta ja commitista

URL-rakenne

{MINIO_BASE}/{repo_slug}/{commit_short}/{report_type}/index.html

Osa	Lähde	Esimerkki
MINIO_BASE	Gitea org variable MINIO_BASE_URL	https://reports.smith.keskikuja.site
repo_slug	GITHUB_REPOSITORY → slug	temperature-store
commit_short	GITHUB_SHA → 8 merkkiä	abc12345
report_type	Raportin tyyppi	cucumber, jacoco, junit, site

URL rakennetaan push-reports.sh-skriptissä ja POSTataan Gitea-commitin statusviestiin url-kenttään.

Staattinen web-hosting

MinIO-bucket konfiguroidaan staattiseksi web-sivustoksi:

mc anonymous set download minio/reports
mc website create minio/reports --region us-east-1

Bucketin rakenne:

reports/
├── temperature-store/
│   ├── abc12345/
│   │   ├── cucumber/
│   │   │   └── overview-features.html
│   │   ├── jacoco/
│   │   │   └── index.html
│   │   └── site/
│   │       └── index.html
│   └── def67890/
│       └── ...
├── user-service/
│   └── ...

Jokaisella buildilla on oma {commit_short}-hakemistonsa — ei race conditionia rinnakkaisten buildien välillä.

Autentikointi: OIDC + Traefik middleware

Raporttien tulee olla katseltavissa ilman erillistä kirjautumista (muuten commitin statusviestin URL-linkki ei toimi suoraan). Samalla julkinen bucket halutaan suojata.

Ratkaisu: MinIO asetetaan Traefik reverse-proxyn taakse. Traefik middleware hoitaa OIDC-autentikoinnin, jossa:

1. Käyttäjä klikkaa raportin URL:ää commitin statusviestistä
2. Traefik ohjaa OIDC-kirjautumiseen (Gitea OAuth2 provider)
3. Onnistuneen kirjautumisen jälkeen käyttäjä ohjataan raporttiin
4. Session säilyy — ei tarvitse kirjautua jokaista raporttia varten

Selain ──→ Traefik ──→ OIDC middleware ──→ Gitea OAuth2
                     │
                     └──→ MinIO (bucket reports, static web)

CI-pusku ohittaa OIDC:n: Workflow'n push-reports.sh käyttää MinIO:n S3 API:a suoraan access key + secret key -parilla (Gitea org secrets). CI-liikenne ei kulje julkisen ingressin kautta — mc-työkalu puhuu suoraan MinIO-palvelulle klusterin sisällä.

Retention policy

Pelkkä aikaperustainen retentio ("poista yli 90 vrk vanhat") ei riitä. Retention policyn pitää huomioida:

Kriteeri	Kuvaus
Aika	Raportti säilyy X päivää buildin jälkeen
Branch	master-branchin raportit säilyvät pidempään kuin feature-branchien
Tagi	Version kanssa tagitun commitin raportteja ei poisteta koskaan
Viimeisin N	Jokaisesta branchista säilytetään vähintään N uusinta raporttia

Toteutus: Retention policy konfiguroidaan ConfigMap:lla, jonka siivousskripti lukee. ConfigMap on osa MinIO-deploymentin Kubernetes-manifestia.

apiVersion: v1
kind: ConfigMap
metadata:
  name: minio-report-retention
data:
  retention.yaml: |
    rules:
      - branch: "master"
        maxAgeDays: 365
        keepMin: 20
      - branch: "feature/*"
        maxAgeDays: 90
        keepMin: 5
      - tagged: true
        maxAgeDays: -1     # ei koskaan poisteta
        keepMin: -1
      - default:
        maxAgeDays: 90
        keepMin: 3

Siivoussripti ajetaan CronJobina (esim. kerran päivässä):

1. Listaa kaikki bucketin objektit
2. Parsii polusta repo_slug ja commit_short
3. Hakee Gitea API:sta commitin metadata (branch, onko tagattu)
4. Soveltaa ConfigMapin retention-sääntöjä
5. Poistaa vanhentuneet objektit mc rm:llä

Raporttien pushaus workflow'sta

push-reports.sh:

#!/bin/bash
# Käyttö: push-reports.sh <report_type> <source_dir>
# Esim:   push-reports.sh cucumber target/cucumber-report/

REPORT_TYPE=$1
SOURCE_DIR=$2
TARGET="minio/reports/${GITHUB_REPOSITORY}/${GITHUB_SHA::8}/${REPORT_TYPE}/"

mc cp --recursive "$SOURCE_DIR" "$TARGET"

echo "${MINIO_BASE_URL}/${GITHUB_REPOSITORY}/${GITHUB_SHA::8}/${REPORT_TYPE}/index.html"

Skripti palauttaa URL:n, joka syötetään report-status.sh:lle commit-statusviestin url-kenttään.

Konfiguraatio Giteassa

Secret / Variable	Tyyppi	Sisältö
MINIO_ACCESS_KEY	Org secret	MinIO access key
MINIO_SECRET_KEY	Org secret	MinIO secret key
MINIO_BASE_URL	Org variable	https://reports.smith.keskikuja.site

Workflow lukee nämä automaattisesti — projekti ei määrittele niitä ci-flow-values.yaml:ssa.

MinIO-deployment (viitteellinen)

Minimalistinen Kubernetes-deployment samassa klusterissa:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: minio-reports
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: minio
        image: minio/minio:latest
        args: ["server", "/data", "--console-address", ":9001"]
        env:
        - name: MINIO_ROOT_USER
          valueFrom:
            secretKeyRef:
              name: minio-secrets
              key: access-key
        - name: MINIO_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: minio-secrets
              key: secret-key
        ports:
        - containerPort: 9000   # S3 API
        - containerPort: 9001   # Console UI
        volumeMounts:
        - name: data
          mountPath: /data
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: minio-reports-pvc

Huomioitavaa

• Bucketin luonti ja web-hostingin aktivointi tehdään kerran deploymentin yhteydessä. Ei per build.
• URL on deterministinen — raportin URL voidaan generoida jo ennen kuin raportti on pushattu. Jos raporttihakemistoa ei ole (esim. testit skipattiin), linkki johtaa 404:ään.
• Indeksitiedoston nimi riippuu raporttityypistä: Cucumber → overview-features.html, JaCoCo → index.html, Maven Site → index.html. push-reports.sh:n vastuulla varmistaa, että indeksitiedosto löytyy.