diff --git a/docs/adr/0004-commit-status.md b/docs/adr/0004-commit-status.md new file mode 100644 index 0000000..8084eb3 --- /dev/null +++ b/docs/adr/0004-commit-status.md @@ -0,0 +1,25 @@ +# 4. Commit-statusviestit — periaate + +## Päätös + +Gitea Actions näyttää jobien tilan (checkmark, risti, spinner) commit-näkymässä +**automaattisesti**. Tämä on ensisijainen tapa, eikä sitä korvata. + +Commit-status API:a (`/api/v1/repos/{owner}/{repo}/statuses/{sha}`) käytetään +**vain** kun natiivi toiminta ei riitä — ensisijaisesti custom-raporttilinkin +välittämiseen commit-näkymään. + +## Periaatteet + +1. Gitea Actionsin automaattinen commit-status on ensisijainen. +2. API:a kutsutaan vain tarpeeseen: linkki ulkoiseen raporttiin. +3. Jokainen API-kutsussa käytettävä `context`-avain on uniikki. +4. State-arvojen on oltava Gitea API:n valideja (`success`, `failure`, + `pending`, `error`, `warning`). + +## Tausta + +Jenkins-versiossa jokainen build-vaihe raportoi APIin, koska Jenkins ei +tarjonnut natiivia commit-statusnäkymää. Gitea Actionsissa tämä tulee +automaattisesti — sama tieto kahdesta paikasta aiheuttaa melua eikä lisää +arvoa. diff --git a/docs/adr/0005-provider-consumer.md b/docs/adr/0005-provider-consumer.md new file mode 100644 index 0000000..b898ae1 --- /dev/null +++ b/docs/adr/0005-provider-consumer.md @@ -0,0 +1,66 @@ +# 5. Provider & Consumer -malli + +## Päätös + +Provider (gitea-ci-library) ja Consumer (mikropalveluprojekti) erotetaan +selkeällä rajapinnalla: `.gitea/workflows/ci-engine.yml` on ainoa pinta, +jota consumer kutsuu. + +Kaikki muu providerin koodi (scriptit, git-pages-helmi, retention) on +sisäistä toteutusta, johon consumerilla ei ole suoraa pääsyä eikä +riippuvuutta. + +## Rajapinnat + +### Consumer → Provider (pakollinen) + +```yaml +# .gitea/workflows/ci.yml — consumerin repo +jobs: + ci: + uses: niko/gitea-ci-library/.gitea/workflows/ci-engine.yml@v1 + secrets: inherit +``` + +Consumer: +- Omistaa pipeline-logiikan (mitä testejä ajetaan, missä järjestyksessä) +- Luo raportit omiin polkuihinsa (`reports/{sha8}/{step}/`) +- Luo `.meta`-tiedostot per step +- Määrittelee Gitea-secretit (`GIT_PAGES_PUBLISH_TOKEN`, `GITEA_TOKEN`) + +### Provider → Consumer (mitä provider tarjoaa) + +- **Raporttien julkaisu**: consumerin tuottamat raportit viedään + git-pages-palveluun osoitteeseen, josta ne ovat selaimella luettavissa. +- **Commit-status linkillä**: jokaiselle raportille luodaan commit-status, + jonka kautta käyttäjä pääsee suoraan raporttiin Gitean commit-näkymästä. +- **Orkestrointi**: build-ketjun ylittäessä reporajat, provider huolehtii + workflown käynnistyksestä ja tilan seurannasta. +- **Raporttien elinkaari**: vanhat raportit poistetaan automaattisesti + retention-sääntöjen mukaan. + +### Provider (sisäinen toteutus, ei consumerin rajapinta) + +- Git-pages Helm-chartti +- Retention sidecar +- Scriptit ja työkalut (toteutus avoin, uudelleenkirjoitettavissa) +- Kaikki paitsi `ci-engine.yml` on sisäistä toteutusta ja voi muuttua + ilman versiopäivitystä + +## Periaatteet + +1. `ci-engine.yml` on **lukittu rajapinta**. Consumer kutsuu tätä, ei + koskaan providerin scriptejä suoraan. `ci-engine.yml` voi muuttua vain + version vaihtuessa. +2. Consumer omistaa pipeline-logiikan. Provider ei tiedä mitä testejä + ajetaan, missä järjestyksessä tai millä työkaluilla. +3. Providerin versiointi: tag (`v1`, `v2`, ...). Branchit ovat kehitystä + varten, consumerit käyttävät tageja. + +## Tausta + +Jenkins-versiossa kaikki logiikka oli yhdessä kirjastossa. Gitea Actionsin +reusable workflow -mekanismi pakottaa selkeämpään erotteluun: consumer +kutsuu provideria, mutta omistaa oman pipeline-logiikkansa. Tämä vähentää +providerin kompleksisuutta ja antaa consumerille vapauden päättää mitä +ajetaan. diff --git a/docs/ai-context.md b/docs/ai-context.md index 22aa56f..c5b2a0e 100644 --- a/docs/ai-context.md +++ b/docs/ai-context.md @@ -1,67 +1,98 @@ # AI Context: Gitea Actions CI -kirjasto -**Updated**: 2026-06-08 +**Updated**: 2026-06-12 (POC-vaihe, suunniteltu uudelleenkirjoitus) ## Project Overview -Gitea Actions reusable workflow -kirjasto mikropalveluiden build-, testaus-, raportointi-, deployment- ja test flow -prosessien orkestrointiin. Korvaa `ci-jenkins-library`:n Gitea-natiivilla toteutuksella. Mikropalvelut käyttävät kirjastoa `uses:`-direktiivillä ja konfiguroivat itsensä `ci-flow-values.yaml`:lla. +Gitea Actions reusable workflow -kirjasto mikropalveluiden build-, testaus-, +raportointi-, deployment- ja test flow -prosessien orkestrointiin. Korvaa +`ci-jenkins-library`:n Gitea-natiivilla toteutuksella. Mikropalvelut +käyttävät kirjastoa `uses:`-direktiivillä. -## Architecture -- 4 reusable workflow'ta: `ci-feature.yml`, `ci-master.yml`, `deploy.yml`, `test.yml` -- 4 jaettua bash-skriptiä (`scripts/`): `report-status.sh`, `dispatch-workflow.sh`, `push-reports.sh`, `tag-commit.sh` -- Raportit MinIO:ssa (S3 + static web), OIDC-autentikointi Traefikin kautta -- Cross-repo commit traceability Gitea REST API:n kautta -- `report-service/`-moduuli samassa repossa: raporttiskriptit, retention CronJob, index.html-generointi -- Normatiivinen arkkitehtuuri: `docs/architecture.md`, perustelut `docs/design-rationale.md` +POC on valmis: raporttien julkaisu git-pagesiin ja commit-status linkillä +toimii. + +## Monorepo: kaksi erillistä kokonaisuutta + +Tämä repo on käytännössä monorepo, jossa on kaksi itsenäistä osaa: + +### 1. Juuri (`gitea-ci-library`) +Provider-kirjasto: reusable workflowt, scriptit, ADRt, dokumentaatio. +Rajapinta: `.gitea/workflows/ci-engine.yml` — ainoa pinta, jota consumerit +kutsuvat. + +### 2. `git-pages/` — oma kokonaisuus +Helm-chartti Codeberg git-pagesille. Täysin itsenäinen — oma dokumentaatio, +omat tekniset valinnat, oma design-rationale. Kohdeltava kuten se olisi jo +oma reponsa: kaikki git-pages-spesifi tieto kuuluu `git-pages/docs/`- alle, +ei juuren `docs/`-kansioon. + +### Rajapinta juuren ja git-pagesin välillä + +Ohut ja yksiselitteinen: + +``` +scripts/publish-git-pages.sh + → PATCH tar osoitteeseen PAGES_HOST + → palauttaa BASE URL:n + +git-pages tarjoaa: + - HTTP endpoint (GET/PATCH/PUT) + - retention (automaattinen) + - TLS, BasicAuth (Traefik) +``` + +Juuri ei tiedä git-pagesin sisäisestä toiminnasta (storage v2, .index, +blob-arkkitehtuuri). Git-pages ei tiedä workflowista, scripteistä tai +provider-logiikasta. + +## Architecture (POC-tila) +- **Provider & Consumer -malli**: `ci-engine.yml` on lukittu rajapinta. + ADR 0005. +- **Raporttien hostaus**: git-pages Helm-chartilla (`git-pages/`). +- **Retention**: sidecar samassa podissa, HTTP API localhost:3000, + Gitea API branch-check. +- **Commit-status**: Gitea Actions näyttää automaattisesti. API vain + custom-linkkiin. ADR 0004. +- **Julkaisu**: `publish-git-pages.sh` → PATCH tar git-pagesiin. ## Repository Structure + | Path | Purpose | |---|---| -| `.gitea/workflows/` | Reusable workflow -tiedostot (`ci-feature.yml`, `ci-master.yml`, `deploy.yml`, `test.yml`) | -| `scripts/` | Jaetut bash-skriptit | -| `report-service/` | Raporttipalvelun koodi (retention, indeksigenerointi) | -| `docs/` | Arkkitehtuuri-, vaatimus- ja konfiguraatiodokumentaatio | -| `docs/tickets/` | Toteutustiketit (0001–0012), yksi per feature-branch | -| `docs/test-plan/` | TDD-opas: 3-kerrosmalli, kehityslooppi, mock, kontekstikuratointi | -| `docs/test-plan/tdd-guide.md` | Testivetoisen kehityksen menetelmädokumentti | -| `tests/` | Bats-testit skripteille ja workflow-validointi | -| `tests/features/` | Cucumber `.feature`-tiedostot (yksi per tiketti, tägätty @mock/@real/@ticket-NNNN) | -| `tests/helpers/` | Jaettu mock-palvelin (Gitea API + MinIO) | -| `.gitea/workflows/ci.yml` | Kirjaston oma CI — dogfood (käyttää itse itseään) | +| `.gitea/workflows/` | `ci-engine.yml` (ainoa reusable workflow POC-vaiheessa) | +| `scripts/` | `publish-git-pages.sh`, `report-status.sh`, `dispatch-workflow.sh` | +| **`git-pages/`** | **Oma kokonaisuus: Helm-chartti + docs + retention** | +| `docs/` | Root-tason arkkitehtuuri, ADRt (0001–0005) | +| `docs/adr/` | Architecture Decision Records | +| `tests/` | Bats-testit skripteille | +| `.gitea/workflows/ci.yml` | Dogfood — kutsuu `ci-engine.yml`:a | + +**Tarkemmat git-pages-asiat:** `git-pages/docs/` (implementation-notes, +architecture, design-rationale, secrets, tech-stack). ## Key Technical Decisions -- **Vain Gitea.** Ei multi-platform-tukea (GitLab, BitBucket, GitHub) -- **Ei omaa runtimea.** Reusable workflowt, ei Docker custom actioneita (ellei pakko) -- **Konfiguraatio repoon.** `ci-flow-values.yaml` projektin juuressa, infra-asetukset Gitea org secrets/variables -- **Vaiheittainen test flow.** Ei rinnakkaista suoritusta — deterministinen, debuggattava -- **Raportit MinIO:ssa.** Gitea artifact-järjestelmä ei tue HTML-selailtavuutta -- **Docker-rekisterit:** MVP:ssä vain Gitea Packages. Factory/adapter-pattern valmiina Artifactorylle/Nexukselle -- **MVP-scope:** `doNotDowngrade` ei mukana, vain Gitea Packages docker-rekisterinä +- **Provider & Consumer**: `ci-engine.yml` lukittu rajapinta, muu koodi + vapaasti muutettavissa +- **Vain Gitea, vain reusable workflowt**: ei custom actioneita, ei + multi-platform +- **Raportit git-pagesissa**: HTML selailtavissa, retention automaattinen +- **Git-pages omana kokonaisuutena**: voi erottaa omaksi repokseen + tulevaisuudessa -## Tech Stack -- **Runtime:** Bash 4.0+, curl 7.0+, jq 1.6+, git 2.30+, MinIO client (`mc`) -- **Alusta:** Gitea Actions 1.21+, Gitea act runner 0.2+ -- **Integraatiot:** Gitea REST API (`/api/v1/`), MinIO S3 API, SonarQube REST API -- **Tuetut build-ekosysteemit:** Java/Maven, Java/Gradle, Node.js/npm -- **Tuetut testikehykset:** Cucumber, JUnit, JaCoCo, Maven Site, custom HTML +## Tech Stack (POC) +- **Runtime:** Bash, curl, jq, python3 (retention whiteout) +- **Alusta:** Gitea Actions, Gitea act runner +- **Hostaus:** git-pages 0.9.1 (Codeberg), Traefik, cert-manager +- **Integraatiot:** Gitea REST API, Gitea Packages ## Common Commands -- Workflow-triggerit: `push` branchiin tai `workflow_dispatch` -- Skriptien kutsuminen tapahtuu workflow-stepeistä, ei paikallisesti -- `ci-flow-values.yaml` validointi: skeema `docs/config-model.md`:ssa -- Bats-testit: `bats tests/` — ajaa kaikki skripti- ja workflow-testit -- Testit vaativat: `bats` (Bash Automated Testing System), `jq`, `yq` - -## Development Process -- TDD: Red-Green-Refactor jokaiselle tiketille. Testit ensin, toteutus vasta kun testi epäonnistuu. -- Ominaisuusbranchit: `feature/NNNN-tiketin-nimi` (esim. `feature/0001-report-status-sh`) -- Yksi tiketti per sessio. Tiketit riippuvuusjärjestyksessä 0001 → 0012. -- Ennen jokaista tikettiä: lataa `docs/test-plan/tdd-guide.md` + tiketin Required context -skillin lisäksi -- Dogfood: `.gitea/workflows/ci.yml` — kirjaston oma CI käyttää omia reusable workflow'itaan +- Helm-asennus: `helm upgrade --install git-pages ./git-pages -n -f ` +- Julkaisu: `bash scripts/publish-git-pages.sh ` +- Status: `bash scripts/report-status.sh ` ## What NOT to Do -- Älä lisää tukea muille Git-alustoille (GitLab, BitBucket, GitHub) +- Älä lisää tukea muille Git-alustoille - Älä lisää Docker custom actioneita ilman pakottavaa syytä -- Älä siirrä konfiguraatiota pois reposita (`ci-flow-values.yaml`) -- Älä lisää rinnakkaista test flow -suoritusta -- Älä lisää ulkoista orkestraattoria — Gitea REST API riittää -- Älä käytä `repository_dispatch`-webhookia test flow -ketjutukseen +- Älä kirjoita git-pages-spesifiä tietoa juuren `docs/`-kansioon — + kuuluu `git-pages/docs/`-alle +- Älä POSTaa commit-status APIin jokaiselle vaiheelle — natiivi riittää diff --git a/docs/architecture.md b/docs/architecture.md index 7c169cc..3e6bad3 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,216 +1,52 @@ # Architecture — Gitea Actions CI -kirjasto -> Hub-dokumentti. Komponentit, niiden roolit ja rajapinnat. Yksityiskohtaiset kuvaukset linkitetyissä detail-dokumenteissa. +> ⚠️ POC-vaihe. Tämä dokumentti kuvaa suunniteltua arkkitehtuuria. Toteutus +> on edelleen kehitysvaiheessa (`ci-engine.yml` on ainoa reusable workflow). +> Odota uudelleenkirjoitusta ennen kuin luotat tähän dokumenttiin. > -> Tämä dokumentti on **normatiivinen** — se määrittelee mikä on rakennettava. `design-rationale.md` kertoo miksi. +> Normatiivinen lähde: ADR 0004, ADR 0005, `docs/design-rationale.md`. --- ## Yleiskuvaus -Kirjasto on kokoelma **Gitea Actions reusable workflow** -tiedostoja, jotka orkestroivat mikropalveluiden build-, testaus-, raportointi-, deployment- ja test flow -prosessit. Projekti käyttää kirjastoa `uses:`-direktiivillä `.gitea/workflows/*.yml`-tiedostossaan ja määrittelee konfigurationsa `ci-flow-values.yaml`-tiedostossa. +Kirjasto on kokoelma **Gitea Actions reusable workflow** -tiedostoja, jotka +orkestroivat mikropalveluiden build-, testaus-, raportointi-, deployment- ja +test flow -prosessit. Projekti käyttää kirjastoa `uses:`-direktiivillä. -Kirjasto on Gitea-spesifi. Se hyödyntää Gitean REST API:a commit-statusraportointiin, workflow-dispatchiin ja run-pollaukseen. Raportit tallennetaan MinIO:hon, josta ne ovat selailtavissa HTML-muodossa. +Kirjasto on Gitea-spesifi. Raportit hallinnoidaan git-pages Helm-chartilla +(`git-pages/`). ---- +## Provider & Consumer -malli -## Komponentit +| Rooli | Kuvaus | +|-------|--------| +| **Provider** | `gitea-ci-library` — tarjoaa `ci-engine.yml`:n (lukittu rajapinta) sekä scriptit | +| **Consumer** | Mikropalveluprojekti — kutsuu `uses:`-direktiivillä, omistaa pipeline-logiikan | -### Reusable workflowt (4 kpl) +Tarkemmin: ADR 0005. -| Workflow | Tiedosto | Rooli | -|----------|----------|-------| -| **Feature flow** | `ci-feature.yml` | Testaa feature-branchin, generoi raportit, raportoi statuksen committiin. Ei buildaa konttia. | -| **Master flow** | `ci-master.yml` | Testaa, buildaa kontin, pushaa rekisteriin, tagittaa commitin, ketjuttaa test flow'n. | -| **Deployment flow** | `deploy.yml` | GitOps-deployment: päivittää YAML-arvoa, committaa, pushaa, raportoi cross-repo-statuksen. | -| **Test flow** | `test.yml` | Vastaanottaa dispatchin, ajaa testit, generoi raportit, raportoi statuksen. | +## Komponentit (POC) -> Yksityiskohtaiset kuvaukset: [workflows.md](workflows.md) +| Komponentti | Tila | +|-------------|------| +| `ci-engine.yml` | Toimii POC-tasolla. Ainoa reusable workflow. | +| `publish-git-pages.sh` | Toimii. PATCH tar git-pagesiin. | +| `report-status.sh` | Toimii. POSTaa commit-status (vain custom-linkkiin). | +| `dispatch-workflow.sh` | Suunniteltu, ei toteutettu POCissa. | +| `git-pages/` | Helm-chartti raporttien hostaukseen. Oma kokonaisuus, tarkemmin: `git-pages/docs/`. | -### Jaetut skriptit - -| Skripti | Rooli | -|---------|-------| -| **`report-status.sh`** | POSTaa build-statuksen Gitea `/api/v1/repos/{owner}/{repo}/statuses/{sha}` | -| **`dispatch-workflow.sh`** | Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista | -| **`push-reports.sh`** | Puskaa testiraportit MinIO:hon ja generoi URL:n | -| **`tag-commit.sh`** | Tagittaa commitin versiolla Gitea REST API:n kautta | - -> Yksityiskohtaiset kuvaukset: [shared-scripts.md](shared-scripts.md) - -### Konfiguraatio - -| Artefakti | Sijainti | Rooli | -|-----------|----------|-------| -| **`ci-flow-values.yaml`** | Projektin repo | Projektikohtainen konfiguraatio (docker, sonar, deployment, test-flow) | -| **Gitea org secrets** | Gitea organization | Tokenit ja salasanat | -| **Gitea org variables** | Gitea organization | Infra-tason asetukset (MinIO URL, SonarQube URL) | - -> Yksityiskohtaiset kuvaukset: [config-model.md](config-model.md) - -### Ulkoiset palvelut +## Ulkoiset palvelut | Palvelu | Rooli | |---------|-------| -| **Gitea REST API** | Commit-statusraportointi, workflow-dispatch, run-pollaus, taggaus | -| **Gitea Packages** | Docker-imagen ja NPM-paketin säilytys | -| **Gitea act runner** | Suorittaa workflowt. Konteista, DinD:stä ja label-järjestelmästä: [runner.md](runner.md) | -| **MinIO** | Testiraporttien tallennus ja staattinen web-hosting | -| **SonarQube** | Koodin laadun analyysi ja quality gate | +| **Gitea REST API** | Commit-status, workflow-dispatch, run-pollaus | +| **Gitea Packages** | Docker-imagen säilytys | +| **git-pages** | Raporttien hostaus | +| **SonarQube** | Koodin laadun analyysi (suunniteltu) | ---- +## Arkkitehtuuriset rajoitteet -## Järjestelmäkaavio - -```mermaid -%%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%% -flowchart TB - subgraph PROJ["Projektin repo"] - WF[".gitea/workflows/ci.yml - uses: gitea-ci-library/ci-master@v1"] - CONF["ci-flow-values.yaml"] - end - - subgraph LIB["gitea-ci-library (reusable workflowt)"] - FEATURE["ci-feature.yml"] - MASTER["ci-master.yml"] - DEPLOY["deploy.yml"] - TEST["test.yml"] - end - - subgraph SCRIPTS["Jaetut skriptit"] - REPORT["report-status.sh"] - DISPATCH["dispatch-workflow.sh"] - PUSHREP["push-reports.sh"] - TAG["tag-commit.sh"] - end - - subgraph EXT["Ulkoiset palvelut"] - GITEA["Gitea API - + Packages"] - MINIO["MinIO - (S3 + static web)"] - SONAR["SonarQube"] - end - - subgraph HELM["Helm-repo"] - VALUES["values-{env}.yaml"] - end - - subgraph TESTREPO["Testi-repo"] - TESTWF[".gitea/workflows/test.yml"] - end - - WF -- "kutsuu" --> MASTER - WF -- "lukee" --> CONF - MASTER -- "käyttää" --> SCRIPTS - DEPLOY -- "käyttää" --> SCRIPTS - TEST -- "käyttää" --> SCRIPTS - REPORT -- "POST status" --> GITEA - DISPATCH -- "dispatch + poll" --> GITEA - PUSHREP -- "S3 upload" --> MINIO - TAG -- "POST tag" --> GITEA - MASTER -- "quality gate" --> SONAR - DEPLOY -- "muokkaa" --> VALUES - DEPLOY -- "commit + push" --> HELM - DISPATCH -- "dispatch" --> TESTWF - TESTWF -- "raportoi" --> GITEA - MINIO -- "URL commit-statusviestiin" --> GITEA - - style PROJ fill:#1e3a5f,color:#f9fafb,stroke:#64748b - style LIB fill:#1f2937,color:#f9fafb,stroke:#64748b - style SCRIPTS fill:#064e3b,color:#f9fafb,stroke:#64748b - style EXT fill:#5c1a1a,color:#f9fafb,stroke:#64748b - style HELM fill:#4a1a6b,color:#f9fafb,stroke:#64748b - style TESTREPO fill:#4a1a6b,color:#f9fafb,stroke:#64748b - style WF fill:#2563eb,color:#ffffff - style CONF fill:#f59e0b,color:#111827 - style FEATURE fill:#2563eb,color:#ffffff - style MASTER fill:#2563eb,color:#ffffff - style DEPLOY fill:#2563eb,color:#ffffff - style TEST fill:#2563eb,color:#ffffff - style REPORT fill:#059669,color:#ffffff - style DISPATCH fill:#059669,color:#ffffff - style PUSHREP fill:#059669,color:#ffffff - style TAG fill:#059669,color:#ffffff - style GITEA fill:#dc2626,color:#ffffff - style MINIO fill:#dc2626,color:#ffffff - style SONAR fill:#dc2626,color:#ffffff - style VALUES fill:#9333ea,color:#ffffff - style TESTWF fill:#9333ea,color:#ffffff - linkStyle default stroke:#9ca3af,stroke-width:3px -``` - ---- - -## Tietovuot - -### 1. Commit-statusraportointi - -``` -Workflow-steppi → report-status.sh → POST Gitea API → commitin status päivittyy - ↘ URL → raporttiin / buildiin -``` - -Jokainen vaihe (test, build, push) POSTaa oman statusviestinsä uniikilla `key`-arvolla. Samaan committiin kertyy useita rinnakkaisia statuksia. - -### 2. Cross-repo traceability - -``` -Mikropalvelu (root-build) → Helm (deployment) → Testi (integraatio) - ↓ ↓ ↓ - Status omaan committiin Status omaan committiin Status omaan committiin - ↑ ↑ ↑ - Status root-committiin ← Status root-committiin ← Status root-committiin - (deployattu, testattu) (mistä kontti tuli) (mitä testattiin) -``` - -Root-build-viite kulkee `workflow_dispatch`in `inputs`-parametrina koko ketjun läpi. - -### 3. Raporttien URL-generointi - -``` -push-reports.sh → mc cp ./reports/ minio/bucket/{repo}/{commit_short}/{report}/ - → URL = {MINIO_BASE}/{repo}/{commit_short}/{report}/index.html - → report-status.sh POSTaa URL:n commit-statusviestiin -``` - -### 4. Test flow -ketjutus - -``` -ci-master.yml → test-flow-taulukko (ci-flow-values.yaml) - → for each step: - dispatch-workflow.sh {test-repo} {inputs} - poll Gitea API run status - success? → next step - failure? → stop -``` - ---- - -## Laajennuspisteet - -| Piste | Mekanismi | Tila | -|-------|-----------|------| -| **Docker-rekisterit** | Factory/adapter — `ci-flow-values.yaml` → `docker.type` → valitsee pusherin | MVP: Gitea Packages. Artifactory, Nexus myöhemmin | -| **Testikehykset** | `push-reports.sh` tukee mitä tahansa hakemistoa → MinIO | Cucumber, JUnit, JaCoCo, Maven Site, custom | -| **Build-ekosysteemit** | Workflow'n `container:` määrittelee projektin itse | Maven, Gradle, npm, mikä tahansa | -| **SonarQube** | Rajapinta vaihdettavissa — parempi kuin pollaus tutkitaan | Quality gate -tarkistus | - ---- - -## Top-level rajoitteet - -- Kaikki integraatio Gitea REST API:n kautta — ei suoria tietokantakytkentöjä, ei jaettua filesysteemiä -- Workflowt eivät jaa tilaa keskenään paitsi `workflow_dispatch`in `inputs`-parametrien kautta -- Raporttien URL on deterministinen: `{MINIO_BASE}/{repo_slug}/{commit_short}/{report}/` -- Cross-repo-statusraportoinnissa root-build on aina se mikropalvelun commit, josta ketju käynnistyi - -## Repo-jako - -| Repo | Sisältö | -|------|---------| -| **`gitea-ci-library`** | Reusable workflowt, jaetut skriptit, `report-service/`-moduuli (raporttiskriptit, retention CronJob, index.html-generointi) | -| **Deployment / infra -repo** (olemassa oleva) | MinIO Kubernetes-manifestit, Traefik OIDC middleware, ConfigMap, ingress | - -`gitea-ci-library/report-service/` on oma moduulinsa samassa repossa — ei erillistä repositoriota, mutta selkeä sisäinen raja workflow-skriptien ja raporttipalvelun koodin välillä. Moduuli sisältää `docs/`-hakemiston deploy-esimerkeillä, mutta varsinainen deployment hoidetaan GitOps/Helm-repon kautta kuten muutkin palvelut. +- `ci-engine.yml` on ainoa consumerin kutsuma rajapinta (ADR 0005) +- Gitea Actionsin natiivi commit-status on ensisijainen (ADR 0004) +- Raportit ovat julkisia URL:lla (osoite tunnettava) diff --git a/docs/config-model.md b/docs/config-model.md index 2005b1f..c2a9876 100644 --- a/docs/config-model.md +++ b/docs/config-model.md @@ -1,6 +1,14 @@ # Konfiguraatiomalli — `ci-flow-values.yaml` -> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Tämä dokumentti määrittelee projektikohtaisen konfiguraation skeeman, `isContainerBuild()`-mekanismin ja version check -skriptin. +> ⚠️ **POC-vaihe.** Tämä dokumentti on peritty Jenkins-versiosta ja sisältää +> Docker-spesifistä legacyä (isContainerBuild, Docker-labelit). POC osoitti, +> että provider on agnostinen consumerin build-ekosysteemille. +> +> Uusi ajattelu: `isContainerBuild()` → `isArtifactBuild()`. Provider ei +> tiedä eikä tarvitse tietää, buildaako consumer kontin, JARin, npm-paketin +> vai mitään muuta. Dokumentti odottaa uudelleenkirjoitusta. +> +> Normatiivinen lähde: `docs/design-rationale.md`, ADR 0005. --- @@ -116,11 +124,20 @@ Array testi-steppejä. Jokainen steppi on joko `deploy` tai `test`. --- -## `isContainerBuild()`-mekanismi +## `isArtifactBuild()`-mekanismi (POC: suunniteltu, ei toteutettu) -**Ongelma:** Samaa committia vasten voidaan ajaa master-workflow useita kertoja. On mieletöntä buildata kontti uudestaan, koska commit on jo tagätty versiolla ja kontti on olemassa rekisterissä. Uudelleenbuildaus aiheuttaa versiokonflikteja ja tuhlaa CI-aikaa. +> **Jenkins-legacy:** Jenkins-versiossa tämä oli `isContainerBuild()`. POC +> osoitti, että provider ei tiedä eikä tarvitse tietää, buildaako consumer +> kontin, JARin vai npm-paketin. Siksi `isContainerBuild()` → +> `isArtifactBuild()`. -**Ratkaisu:** Workflow'n alussa tarkistetaan, onko tälle commitille jo olemassa versiotagi: +**Ongelma:** Samaa committia vasten voidaan ajaa master-workflow useita +kertoja. On mieletöntä buildata artifakti uudestaan, koska commit on jo +tagätty versiolla ja artifakti on olemassa rekisterissä. Uudelleenbuildaus +aiheuttaa versiokonflikteja ja tuhlaa CI-aikaa. + +**Ratkaisu:** Workflow'n alussa tarkistetaan, onko tälle commitille jo +olemassa versiotagi. ```bash # is-container-built.sh @@ -156,34 +173,8 @@ jobs: **Miksi tämä on välttämätöntä:** - Estää versiokonfliktit: `1.2.3.42` ei voi olla kahdesti -- Säästää CI-aikaa: kontin buildaus on hitain vaihe -- Pitää commitin ja kontin välisen suhteen yksiselitteisenä: `git tag` kertoo suoraan mikä versio vastaa tätä committia - ---- - -## Docker-labelit - -Jenkins-versiossa konttiin injektoitiin metadataa Docker-labelien kautta. Sama käytäntö jatkuu: - -```bash -docker build \ - --label "git.commit=${GITHUB_SHA::8}" \ - --label "git.commitBy=${GITHUB_ACTOR}" \ - --label "build.date=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ - --label "build.run=${GITHUB_RUN_NUMBER}" \ - --label "version=${DOCKER_VERSION}" \ - -t ${DOCKER_TAG} . -``` - -| Label | Arvo | Lähde | -|-------|------|-------| -| `git.commit` | 8-merkkinen hash | `GITHUB_SHA::8` | -| `git.commitBy` | Ajon laukaisija | `GITHUB_ACTOR` | -| `build.date` | ISO 8601 UTC | `date -u` | -| `build.run` | Ajon järjestysnumero | `GITHUB_RUN_NUMBER` | -| `version` | Kontin versio | `1.2.3.42` | - -Näillä labeleilla kontista näkee suoraan: kuka buildasi, milloin, mistä commitista, millä versiolla. Vianjäljitys kontista koodiin on suora. +- Säästää CI-aikaa: artifaktin buildaus on hitain vaihe +- Pitää commitin ja artifaktin välisen suhteen yksiselitteisenä: `git tag` kertoo suoraan mikä versio vastaa tätä committia --- diff --git a/docs/design-rationale.md b/docs/design-rationale.md index 09e9808..1be0113 100644 --- a/docs/design-rationale.md +++ b/docs/design-rationale.md @@ -12,21 +12,45 @@ Organisaatiolla on tuotannossa Jenkins-pohjainen CI-järjestelmä (`ci-jenkins-l Jenkins on kuitenkin raskas ylläpitää Kubernetesissa, ja organisaatio on siirtymässä Giteaan. Tavoitteena on **sama toiminnallisuus, pienemmällä ylläpitotaakalla**, hyödyntäen Gitea Actionsin natiiveja ominaisuuksia. -Kirjasto ei ole Jenkins-migraatiotyökalu. Se on Gitea Actions -natiivi uudelleensuunnittelu, joka säilyttää Jenkins-version todistetut patternit mutta hylkää ne osat, jotka olivat sidottuja Jenkinsin arkkitehtuuriin. +Kirjasto ei ole Jenkins-migraatiotyökalu. Se on Gitea Actions -natiivi +uudelleensuunnittelu, joka säilyttää Jenkins-version todistetut patternit +mutta hylkää ne osat, jotka olivat sidottuja Jenkinsin arkkitehtuuriin. +Gitea Actionsin ja Gitean natiiveja ominaisuuksia hyödynnetään aina kun +mahdollista — uutta kilpailevaa toteutusta ei kirjoiteta, jos toimiva +ratkaisu on jo olemassa. --- ## Suunnitteluperiaatteet -### 1. Git-commit on universaali statusnäkymä +### 1. Hyödynnä natiivia + +Gitea Actionsin ja Gitean natiiveja ominaisuuksia käytetään aina kun ne +riittävät. Uutta kilpailevaa toteutusta ei kirjoiteta, jos toimiva ratkaisu +on jo olemassa. + +**Miksi:** Oma toteutus on aina ylläpidettävä, testattava ja +dokumentoitava. Natiivi ominaisuus tulee ilmaiseksi, kehittyy alustan +mukana ja on käyttäjälle tuttu. + +**Esimerkkejä:** +- Gitea Actions näyttää jobien statuksen automaattisesti — omaa + commit-status API -kutsua ei tarvita jokaiselle vaiheelle +- Gitea organization secrets/variables korvaa erillisen credential-hallinnan +- Reusable workflow -mekanismi korvaa custom action -runtimen + +### 2. Git-commit on universaali statusnäkymä Buildin jokainen vaihe raportoi tilansa Git-committiin. Kehittäjä näkee yhdellä silmäyksellä, missä vaiheessa build on — ei tarvitse navigoida CI-järjestelmän UI:hun. **Miksi:** Jenkins-versio osoitti, että commit-statusviestit poistavat tarpeen CI-dashboardille. Kehittäjä työskentelee Gitissä, joten status kuuluu Gitiin. Statusviestien `url`-kenttä linkittää suoraan raportteihin — Cucumber-tulokset, SonarQube-tulokset, Docker-rekisteri — ilman että URL tarvitsee etsiä erikseen. -**Mitä tarkoittaa käytännössä:** Jokainen `testBegin/End`, `buildBegin/End`, `pushBegin/End`-vaihe POSTaa Gitean REST APIin (`/api/v1/repos/{owner}/{repo}/statuses/{sha}`). Uniikki `key` per vaihe estää duplikaatit ja mahdollistaa rinnakkaiset statukset samassa commitissa. +**Mitä tarkoittaa käytännössä:** Gitea Actions näyttää jobien tilan +(checkmark/risti/spinner) commit-näkymässä automaattisesti. API:a +(`/api/v1/repos/{owner}/{repo}/statuses/{sha}`) käytetään vain +custom-raporttilinkin välittämiseen. ADR 0004. -### 2. Reusable workflow — ei omaa runtimea +### 3. Reusable workflow — ei omaa runtimea Kirjasto jaetaan Gitea Actionsin reusable workflow -mekanismilla. Ei Docker-pohjaisia custom actioneita, ei erillistä ajonaikaista palvelinta. @@ -34,15 +58,17 @@ Kirjasto jaetaan Gitea Actionsin reusable workflow -mekanismilla. Ei Docker-pohj **Mitä tämä ei ole:** Tämä ei ole monorepo-työkalu, joka asennetaan projekteihin. Tämä on joukko `.gitea/workflows/`-tiedostoja, joihin mikropalvelut viittaavat `uses:`-direktiivillä. -### 3. Konfiguraatio kuuluu repoon +### 4. Konfiguraatio kuuluu repoon Projektikohtainen konfiguraatio (`ci-flow-values.yaml`-tyyppinen tiedosto) asuu mikropalvelun omassa repossa. Reusable workflow lukee sen, ei toisinpäin. **Miksi:** Mikropalvelun kehittäjä omistaa buildinsa. Hän tietää mitä Dockefileä käytetään, mitä SonarQube-projektia, mitä testi-steppejä tarvitaan. Jos konfiguraatio hajautetaan useaan repoon, muutokset vaativat koordinaatiota, ja yhden totuuden lähteen periaate rikkoutuu. -**Poikkeus:** Infra-tason asetukset (MinIO-URL, Gitea-instanssin URL) ovat organisaatiotasolla Gitean organization secrets/variables -mekanismissa. Ne eivät ole repokohtaisia, koska DNS voi osoittaa eri paikkaan kuin repo, ja usean repossa toistuva sama arvo on ylläpitoriski. +**Poikkeus:** Infra-tason asetukset (git-pages host, Gitea-instanssin URL) +ovat organisaatiotasolla Gitean organization secrets/variables +-mekanismissa. Ne eivät ole repokohtaisia. -### 4. Deterministinen testigraafi, vaiheittainen suoritus +### 5. Deterministinen testigraafi, vaiheittainen suoritus Test flow on tunnettu ennen buildin alkua, ja testit ajetaan yksi kerrallaan. Jos steppi epäonnistuu, koko flow pysähtyy. @@ -50,13 +76,18 @@ Test flow on tunnettu ennen buildin alkua, ja testit ajetaan yksi kerrallaan. Jo **Miten:** Orkestroiva workflow käyttää Gitea REST API:a workflow-dispatchiin ja pollaa ajettavan workflow'n tilaa synkronisesti (`GET /api/v1/repos/{owner}/{repo}/actions/runs/{id}`). Tämä vastaa Jenkinsin `buildJob()`-kutsun semantiikkaa, mutta toteutetaan curl + pollaus -silmukalla. -### 5. Raportit ovat selailtavia URL:n takana +### 6. Raporttien hallinta erillisellä palvelulla -Testiraportit (Cucumber HTML, Jacoco HTML, JUnit XML) viedään MinIO:hon, jonka staattinen web-hosting renderöi ne selaimessa. URL linkitetään Git-committiin. +Raporttien selailtavuudesta ja elinkaaresta vastaa erillinen palvelu, joka +asennetaan git-pages Helm-chartilla. Raportit ovat julkisia URL:lla +(osoite tunnettava). URL linkitetään Git-committiin. -**Miksi:** Jenkins-versiossa linkki Cucumber-raporttiin oli kriittinen feature — kehittäjä klikkasi commitin statusviestistä ja näki heti mitkä testit epäonnistuivat. Gitea Actionsin sisäänrakennettu artifact-järjestelmä ei tue HTML-selailtavuutta (vain ZIP-lataus). MinIO täyttää tämän aukon: se on kevyt, Kubernetes-natiivi, ja sen S3 API on standardi. URL-rakenne `{BASE}/{repo_slug}/{commit_short}/{report_type}/` on ennustettavissa ilman erillistä URL-generaattoria. +**Miksi:** Jenkins-versiossa linkki Cucumber-raporttiin oli kriittinen +feature. Gitea Actionsin artifact-järjestelmä ei tue HTML-selailtavuutta +(vain ZIP-lataus). Erillinen palvelu mahdollistaa hallitun retention ja +pääsyn ilman CI-alustan rajoitteita. -### 6. Yksi CI-alusta, yksi integraatiopiste +### 7. Yksi CI-alusta, yksi integraatiopiste Kirjasto tukee vain Giteaa. Ei GitLab-, BitBucket- tai GitHub-abstraktioita. @@ -64,7 +95,7 @@ Kirjasto tukee vain Giteaa. Ei GitLab-, BitBucket- tai GitHub-abstraktioita. **Mitä tarkoittaa tulevaisuudessa:** Jos toinen alusta tulee ajankohtaiseksi, Gitea-versiota käytetään joko pohjana redesignille tai mallina erilliselle toteutukselle. Rajapintoja ei suunnitella etukäteen alustariippumattomiksi — se on ennenaikaista optimointia. -### 7. Cross-repo commit traceability +### 8. Cross-repo commit traceability Kun build-ketju ylittää reporajat (mikropalvelu → deployment → integraatiotestit → e2e-testit), jokainen vaihe raportoi kahteen suuntaan: omaan committiinsa ja takaisin root-committiin, josta ketju käynnistyi. @@ -128,18 +159,7 @@ sequenceDiagram --- -## Teknologiavalinnat (seurauksina ylläolevista periaatteista) - -| Valinta | Miksi | -|---------|------| -| **Gitea Actions reusable workflows** | Periaate 2: natiivein tapa jakaa CI-logiikkaa ilman omaa runtimea | -| **Gitea REST API** (`/api/v1/...`) | Periaate 1: commit-statusraportointi. Periaate 4: workflow-dispatch ja status-pollaus. Periaate 7: cross-repo statusraportointi useaan committiin | -| **MinIO** (S3-yhteensopiva) | Periaate 5: HTML-selailtavat raportit ilman ulkoista palvelinta. Kubernetes-natiivi, yksi binääri | -| **YAML** konfiguraatioformaattina | Periaate 3: repo omistaa konffinsa. YAML on luettava, versioitava ja tuttu Jenkins-versiosta | -| **curl + jq + bash** integraatiokerroksena | Periaate 2: ei custom action -runtimea. Gitea REST API:a kutsutaan suoraan workflow-stepistä | -| **Gitea organization secrets/variables** | Periaate 3: infra-tason asetukset (MinIO-URL, tokenit) eivät kuulu reposuuteen | - ---- +## Mitä tietoisesti hylättiin ## Mitä tietoisesti hylättiin diff --git a/docs/report-hosting.md b/docs/report-hosting.md index 92e9aa5..c9af9c8 100644 --- a/docs/report-hosting.md +++ b/docs/report-hosting.md @@ -1,199 +1,6 @@ -# Raporttivarasto — MinIO +# Raporttivarasto -> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Tämä dokumentti määrittelee testiraporttien tallennuksen, URL-rakenteen, autentikoinnin ja retention policyn. +Raporttien hostaus: `git-pages/`-Helm-chartti. Tarkempi dokumentaatio: +`git-pages/README.md` ja `git-pages/docs/`. ---- - -## 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: - -```bash -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. - -```yaml -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`: - -```bash -#!/bin/bash -# Käyttö: push-reports.sh -# 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: - -```yaml -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. +Tämä dokumentti on korvattu git-pages-kohtaisella dokumentaatiolla. diff --git a/docs/shared-scripts.md b/docs/shared-scripts.md index 0103c75..be8677a 100644 --- a/docs/shared-scripts.md +++ b/docs/shared-scripts.md @@ -1,8 +1,12 @@ # Jaetut skriptit -> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Tämä dokumentti määrittelee reusable workflow'sta kutsuttavien bash-skriptien rajapinnat, parametrit ja vastuut. +> ⚠️ **POC-vaihe.** Osa kuvatuista skripteistä (push-reports.sh, tag-commit.sh) +> on suunniteltu mutta ei toteutettu. Toteutetut: `publish-git-pages.sh`, +> `report-status.sh`, `dispatch-workflow.sh` (POC-taso). +> +> Uudelleenkirjoitus odottaa: skriptien määrä ja rajapinnat voivat muuttua. -Skriptit asuvat `gitea-ci-library/scripts/`-hakemistossa. Workflowt lataavat ne checkout-stepin jälkeen. +Skriptit asuvat `gitea-ci-library/scripts/`-hakemistossa. --- @@ -91,9 +95,9 @@ dispatch-workflow.sh "tests/integration" "test.yml" "main" \ --- -## `push-reports.sh` +## `push-reports.sh` (vanhentunut — korvattu `publish-git-pages.sh`:lla) -Puskaa raporttihakemiston MinIO:hon ja päivittää indeksisivut. +Puskaa raporttihakemiston git-pagesiin. ### Rajapinta diff --git a/docs/tech-stack.md b/docs/tech-stack.md index 1ab4de5..11217d4 100644 --- a/docs/tech-stack.md +++ b/docs/tech-stack.md @@ -1,109 +1,39 @@ # Tech Stack — Gitea Actions CI -kirjasto -> Absoluuttinen lähde sille, mitä teknologioita kirjasto käyttää ja tukee. Tämä dokumentti laaditaan `design-rationale.md`:n pohjalta. Mitään tässä listaamatonta teknologiaa ei oleteta olevan käytössä. +> ⚠️ POC-vaihe. Osa teknologiavalinnoista voi muuttua uudelleenkirjoituksen +> myötä. Katso myös `git-pages/docs/tech-stack.md`. --- ## Kirjaston oma runtime -Kirjasto itsessään on kokoelma **Gitea Actions reusable workflow** -tiedostoja (`.gitea/workflows/*.yml`). Ajonaikaiset stepit käyttävät: - | Teknologia | Versio / minimi | Käyttötarkoitus | |---|---|---| | **Gitea Actions** | 1.21+ | CI-alusta, workflow-moottori | | **Gitea act runner** | 0.2+ | Workflow'n suoritus | | **Bash** | 4.0+ | Integraatioskriptit workflow-stepeissä | -| **curl** | 7.0+ | Gitea REST API -kutsut (statusraportointi, dispatch, pollaus) | -| **jq** | 1.6+ | JSON-vastausten jäsennys REST API -kutsuista | -| **git** | 2.30+ | SCM-operaatiot (checkout, tag, push) | -| **MinIO client (mc)** | latest | Raporttien pushaus MinIO:hon ja URL-generointi | +| **curl** | 7.0+ | Gitea REST API, git-pages PATCH | +| **jq** | 1.6+ | JSON-vastausten jäsennys | ---- +## Raporttien hostaus -## Konfiguraatio - -| Teknologia | Käyttötarkoitus | -|---|---| -| **YAML** | Projektikohtainen konfiguraatio (`ci-flow-values.yaml`) | -| **Gitea organization secrets** | Tokenit ja salasanat (Gitea API -token, MinIO credentials) | -| **Gitea organization variables** | Infra-tason asetukset (MinIO base URL, SonarQube URL) | - ---- +Raportit hostataan git-pages-palvelulla (`git-pages/`-Helm-chartti). +Julkaisu: `scripts/publish-git-pages.sh` → PATCH tar. Tarkemmat +teknologiavalinnat: `git-pages/docs/tech-stack.md`. ## Tuetut ulkoiset palvelut -Kirjasto integroituu näihin ulkoisiin palveluihin workflow-stepeistä käsin. Palvelut eivät ole osa kirjastoa. - | Palvelu | Rajapinta | Käyttötarkoitus | |---|---|---| -| **Gitea REST API** | `/api/v1/` | Commit-statusraportointi, workflow-dispatch, run-status-pollaus, taggaus | -| **MinIO** | S3 API + staattinen web-hosting | Testiraporttien tallennus ja selailu | -| **SonarQube** | REST API (`/api/`) | Quality gate -pollaus, dashboard-linkitys | -| **Gitea Packages** | Container registry API | Docker-imagen push ja taggaus | - ---- - -## Tuetut build-ekosysteemit - -Kirjasto tukee näitä käyttäjäprojektien build-työkaluja. Työkalut asennetaan workflow'n ajonaikaiseen konttiin (projektin itse määrittelemään). - -| Ekosysteemi | Työkalut | Artifact-tyypit | -|---|---|---| -| **Java / Maven** | `mvn`, `java` | JAR, Docker | -| **Java / Gradle** | `gradle`, `java` | JAR, Docker | -| **Node.js / npm** | `npm`, `node` | npm-paketti, Docker | -| **Docker** | `docker`, `docker buildx` | Docker-image | - ---- - -## Tuetut testikehykset - -Kirjasto generoi ja julkaisee raportit näistä testikehyksistä. Itse testikehysten ajurit ovat käyttäjäprojektissa. - -| Testikehys | Raporttiformaatti | MinIO-kohde | -|---|---|---| -| **Cucumber** | HTML (Cucumber Reports) | `/{commit_short}/cucumber/` | -| **JUnit** | XML | `/{commit_short}/junit/` | -| **JaCoCo** | HTML | `/{commit_short}/jacoco/` | -| **Maven Site** | HTML | `/{commit_short}/site/` | -| **Mukautettu HTML** | HTML | `/{commit_short}/{report_name}/` | - ---- - -## Tuetut deployment-työkalut - -| Työkalu | Käyttötarkoitus | -|---|---| -| **Helm v3** | Kubernetes-deployment (arvot `values-{environment}.yaml`) | -| **Kubernetes** | Ajonaikainen ympäristö (testiympäristöt, tuotanto) | - ---- +| **Gitea REST API** | `/api/v1/` | Commit-status, workflow-dispatch, branch-listaus (retention) | +| **git-pages** | HTTP | Raporttien hostaus | +| **Gitea Packages** | Container registry API | Docker-imagen push | ## Mitä EI tueta (verrattuna Jenkins-versioon) -Nämä olivat Jenkins-kirjastossa, mutta on tietoisesti jätetty pois Gitea Actions -versiosta: - | Teknologia | Syy | |---|---| -| **GitLab REST API** | Ei multi-platform-tukea (periaate 6) | -| **BitBucket Server REST API** | Ei multi-platform-tukea | -| **BitBucket Cloud REST API** | Ei multi-platform-tukea | -| **Jenkins** (shared library, cucumber plugin, publishHTML, jacoco plugin, buildJob) | Ei Jenkins-riippuvuutta — Gitea Actions korvaa | -| **Artifactory** (Docker registry) | MVP:ssä ei. Factory/adapter-patternilla lisättävissä myöhemmin | -| **Nexus** (Docker registry) | MVP:ssä ei. Factory/adapter-patternilla lisättävissä myöhemmin | -| **Artifactory** (npm registry) | MVP:ssä ei. Factory/adapter-patternilla lisättävissä myöhemmin | -| **Groovy** | Jenkins-spesifi. Korvautuu Bashilla ja YAML:lla | - ---- - -## Huomautus: Docker-rekisterit - -MVP:ssä tuetaan vain **Gitea Packages** (Container registry). Arkkitehtuuriin suunnitellaan factory/adapter-pattern, jolla Artifactory ja Nexus voidaan lisätä myöhemmin ilman workflow-muutoksia. Rekisteri konfiguroidaan `ci-flow-values.yaml`:n `docker`-osiossa `type`-kentällä (vrt. Jenkins `ArtifactRepoType`-enum). - -## Huomautus: SonarQube-integraatio - -Jenkins-versio pollasi quality gatea: `GET /api/project_analyses/search` → etsi uusin analyysi → `GET /api/qualitygates/project_status?analysisId=X`. SonarQubessa on tätä parempi rajapinta. Tutkitaan arkkitehtuurivaiheessa. - -## Huomautus: Docker-in-Docker - -Gitea Actions tukee Docker-in-Dockeria natiivisti `services:`-määrittelyllä workflow-tiedostossa. Tämä vastaa Jenkinsin `podTemplate`-konttia `docker:19.03.1-dind` + `docker:19.03.1` sidecar-mallia. Projektin workflow määrittelee tarvittavat kontit itse — reusable workflow ei pakota tiettyä konttivalikoimaa. +| **MinIO** | Korvattu git-pagesilla | +| **Multi-Git-platform** | Vain Gitea | +| **Jenkins** (shared library, plugins) | Gitea Actions korvaa | +| **Artifactory/Nexus** | MVP:ssä ei, factory/adapter-pattern valmiina | diff --git a/docs/workflows.md b/docs/workflows.md index 5d2cfdb..a6bd90b 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -1,6 +1,8 @@ # Reusable workflowt -> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Tämä dokumentti määrittelee jokaisen reusable workflow'n elinkaaren ja rajapinnan. +> ⚠️ **POC-vaihe.** Tämä dokumentti kuvaa suunniteltuja workflow'ta +> (ci-feature, ci-master, deploy, test). POCissa on toteutettu vain +> `ci-engine.yml`. Uudelleenkirjoitus odottaa. --- @@ -29,8 +31,7 @@ start → unit-test → code-coverage → html-reports → end | Parametri | Pakollinen | Kuvaus | |-----------|------------|--------| | `config-file` | Kyllä | Polku `ci-flow-values.yaml`:aan (yleensä `ci-flow-values.yaml`) | -| `maven-image` | Ei | Maven-kontin image (esim. `maven:3.9-eclipse-temurin-21`) | -| `node-image` | Ei | Node-kontin image (jos npm-projekti) | +| `containers` | Ei | Kuvaus konteista: avain = nimi, arvo = image. Steppi valitsee missä kontissa ajaa. | ### Steppi-kaavio @@ -42,9 +43,8 @@ flowchart TD aja testit, generoi raportit"] UNIT --> COV["code-coverage jacoco / vastaava"] - COV --> HTML["publish-html - pushaa raportit MinIO:hon - generoi index.html"] + COV --> HTML["publish-reports + vie raportit git-pagesiin"] HTML --> END(["end POST lopullinen status"]) @@ -84,8 +84,7 @@ unit-test → quality-gate → build-jar → build-docker → push-docker → ta | Parametri | Pakollinen | Kuvaus | |-----------|------------|--------| | `config-file` | Kyllä | Polku `ci-flow-values.yaml`:aan | -| `maven-image` | Ei | Maven-kontti | -| `docker-image` | Ei | Docker-in-Docker -image (esim. `docker:26-dind`) | +| `containers` | Ei | Kuvaus konteista: avain = nimi, arvo = image | ### isContainerBuilt-check @@ -125,9 +124,8 @@ flowchart TD CHECK -- "kyllä" --> CTF["continueToTestFlow"] TAG --> CTF - CTF --> HTML["publish-html - pushaa Maven Site - MinIO:hon"] + CTF --> HTML["publish-reports + vie raportit git-pagesiin"] HTML --> END(["end lopullinen status"]) diff --git a/git-pages/README.md b/git-pages/README.md index 70b8714..9b47223 100644 --- a/git-pages/README.md +++ b/git-pages/README.md @@ -36,6 +36,11 @@ helm upgrade --install git-pages ./git-pages \ -f "$VALUES" ``` +Helm ajaa asennuksen jälkeen init-jobin, joka PUTtaa paikanpitäjäsivun +git-pagesiin. Tämä luo tarvittavan `.index`-tiedoston — sen jälkeen +Gitea Actions -scriptit voivat käyttää suoraan PATCHia ilman +PUT-fallbackia. + --- ## Vie publish-token Gitea Actions-secretiin (per repo) diff --git a/git-pages/docs/architecture.md b/git-pages/docs/architecture.md index 812ba75..8e82bb4 100644 --- a/git-pages/docs/architecture.md +++ b/git-pages/docs/architecture.md @@ -23,42 +23,39 @@ TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit). | Komponentti | Rooli | |-------------|-------| | **git-pages Pod** | Codeberg git-pages `0.9.1`, filesystem-storage `/app/data` | -| **PVC** | Raporttisisältö (`{owner}/{repo}/reports/{sha8}/…`) | +| **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` | -| **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) | +| `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 peilaa suoraan Gitean commit-polun rakennetta, lisäten raportin nimen: +Julkinen osoite: ``` -https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/commit/14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb/cucumber/index.html - └────────────── selvä URL ──────────────┘ └──────────────────────── Gitea-yhteensopiva polku ────────────────────────┘ +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) polku vastaa URL:ia: +Levyllä (apex index-site): ``` -/app/data/ - {owner}/ - {repo}/ - commit/ - {sha}/ - {raportin-nimi}/ - index.html - .meta # branch, sha, published_at +/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. --- @@ -78,10 +75,10 @@ flowchart TB CM["cert-manager\nTLS"] end - subgraph cluster["git-pages"] - GP["git-pages Pod"] + subgraph cluster["git-pages Pod"] + GP["git-pages\n(kontti)"] + RT["retention sidecar\n(kontti)\nHTTP API localhost:3000"] PVC["PVC /app/data"] - CJ["CronJob retention"] end PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK @@ -89,8 +86,8 @@ flowchart TB TRAEFIK --> GP CM --> TRAEFIK GP --> PVC - CJ -->|"read branches"| GITEA - CJ --> PVC + RT -->|"reads .git-pages/manifest.json\nHTTP localhost"| GP + RT -->|"check branches"| GITEA ``` --- @@ -119,15 +116,15 @@ Katso [design-rationale.md — Luku-auth](design-rationale.md#luku-auth). ## Retention -CronJob `git-pages-retention` (oletus kerran päivässä): +Sidecar-kontti samassa podissa, ajaa retention-cleanup.sh 24h välein: -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 +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` — `read:repository` PAT. +Gitea API: `GET /api/v1/repos/{owner}/{repo}/branches/{branch}` — `read:repository` PAT. Katso [secrets.md](secrets.md). --- @@ -138,7 +135,8 @@ Katso [secrets.md](secrets.md). |--------|------------|------|--------| | 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 | +| 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. diff --git a/git-pages/docs/design-rationale.md b/git-pages/docs/design-rationale.md index 74f16b0..669458a 100644 --- a/git-pages/docs/design-rationale.md +++ b/git-pages/docs/design-rationale.md @@ -143,8 +143,8 @@ Ei toteutettu. Julkaisu- ja luku-reitit pysyvät erillisinä; OIDC lisätään v ### Retention -CronJob `git-pages-retention` (kerran päivässä) skannaa PVC:n ja poistaa vanhentuneet -raportit. Julkaisija kirjoittaa `reports/{sha8}/.meta` (branch, sha, published_at). +Sidecar samassa podissa (HTTP localhost:3000), ajaa retention-cleanup.sh +24h välein: | Sääntö | Konfiguroitavissa? | Kuvaus | |--------|-------------------|--------| @@ -152,13 +152,15 @@ raportit. Julkaisija kirjoittaa `reports/{sha8}/.meta` (branch, sha, published_a | **maxAgeDays** | Kyllä (`dev-values`) | Aktiivisen branchin raportit vanhemmat kuin N päivää | | **keepMin** | Kyllä (`dev-values`) | Aktiivisella branchilla pidetään vähintään N uusinta | -Poistettujen branchien siivous ei tarvitse parametreja. Jäljelle jääneille branchille -säännöt tulevat `retention.rules` (`default` + `branches.{name}`). +Poistettujen branchien siivous ei tarvitse parametreja. Jäljelle jääneille +branchille säännöt tulevat `retention.rules` (`branches.default` + +`branches.{name}`). -**Puutteet:** tagattuja commiteja ei suojata erikseen. RWO-PVC vaatii lyhyen katkon -(deployment skaalataan 0:ksi ajon ajaksi). +Ei PVC-skaalausta — sidecar lukee manifestin HTTP:lla ja poistaa whiteout +PATCHilla. Ei K8s API -oikeuksia. -Secret: `git-pages-retention-gitea` — Gitea PAT branch-listaan. Ks. [secrets.md](secrets.md). +Secret: `git-pages-retention-gitea` — Gitea PAT branch-tarkistukseen. +Ks. [secrets.md](secrets.md). --- diff --git a/git-pages/docs/implementation-notes.md b/git-pages/docs/implementation-notes.md new file mode 100644 index 0000000..c980080 --- /dev/null +++ b/git-pages/docs/implementation-notes.md @@ -0,0 +1,43 @@ +# Implementation Notes + +Teknisiä huomioita git-pages 0.9.1:n käyttäytymisestä, joita ei ole ilmeistä +dokumentaatiosta. + +## Storage v2 (Protobuf manifest) + +Git-pages 0.9.1 käyttää v2-arkkitehtuuria. Kaikki sisältö on pakattu +Protobuf-manifestiin (`site/{host}/.index`), ei flat-FS:nä. Tästä seuraa: + +- Tiedostoja ei voi etsiä tai poistaa `find`/`rm`-komennoilla +- `.git-pages/manifest.json` listaa kaikki tiedostot (ProtoJSON) +- `.git-pages/archive.tar` antaa koko sisällön (saattaa truncata HTTP/2:ssa) + +## Host-header + +Git-pages valitsee sivuston Host-headerin perusteella. Ilman oikeaa Hostia +palauttaa 404. + +- Ulkoiset requestit: Traefik välittää alkuperäisen Hostin automaattisesti +- Sidecar/localhost: `-H "Host: ci-reports.helm-dev.keskikuja.site"` + +## PATCH ja directory-entryt + +Jos PATCH-tar sisältää directory-entryn (tyyppi directory, tar typeflag '5'), +se **korvaa** koko hakemiston dokumentaation mukaan. Tar saa sisältää vain +file- ja symlink-entryjä, jotta PATCH toimii odotetusti. + +## Whiteout — tiedostojen poisto + +Ainoa tapa poistaa tiedostoja ilman koko sivuston PUT-korvausta: + +- Tarissa character device entry (`CHRTYPE`, tar typeflag '4') +- `devmajor=0`, `devminor=0` +- PATCH:ataan sivuston juureen + +## .init — ensimmäinen julkaisu + +Ensimmäinen julkaisu vaatii PUTin, joka luo `.index`-tiedoston. Tämän jälkeen +PATCH riittää. + +Helm-chartin post-install -job hoitaa tämän automaattisesti: +consumerien publish-scriptien ei tarvitse tuntea asennuksen tilaa. diff --git a/git-pages/docs/secrets.md b/git-pages/docs/secrets.md index 883ed4d..054eac0 100644 --- a/git-pages/docs/secrets.md +++ b/git-pages/docs/secrets.md @@ -92,9 +92,9 @@ graph TD subgraph "Retention Flow" R1["K8s Secret
git-pages-retention-gitea"] R2["Gitea PAT
CI-REPORTS_READ_FOR_RETENTION"] - R1 -->|token| CJ["CronJob"] - R2 -->|API auth| GITEA["Gitea API"] - CJ -->|read branches| GITEA + R1 -->|token| SC["Sidecar"] + SC -->|API auth| GITEA["Gitea API"] + SC -->|read branches| GITEA end ``` @@ -157,26 +157,26 @@ GET/HEAD-reitillä ei ole Middlewarea. Luku on julkinen, jos URL tunnetaan. ```mermaid sequenceDiagram - participant CronJob as CronJob
git-pages-retention + participant Sidecar as Retention Sidecar participant K8sSecret as K8s Secret
git-pages-retention-gitea participant GiteaAPI as Gitea API - participant PVC as PVC /app/data + participant GP as git-pages (localhost:3000) - Note over CronJob: 1. Lue PAT - CronJob->>K8sSecret: lue token - K8sSecret-->>CronJob: Gitea PAT + Note over Sidecar: 1. Lue PAT + Sidecar->>K8sSecret: lue token + K8sSecret-->>Sidecar: Gitea PAT - Note over CronJob: 2. Skaalaa deployment 0:aan - CronJob->>PVC: lue .meta-tiedostot + Note over Sidecar: 2. Lue manifest + Sidecar->>GP: GET .git-pages/manifest.json + GP-->>Sidecar: sisällysluettelo - Note over CronJob: 3. Kysy branch-lista - CronJob->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches - GiteaAPI-->>CronJob: branch names + Note over Sidecar: 3. Kysy branch + Sidecar->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches/BRANCH + GiteaAPI-->>Sidecar: 200 / 404 - Note over CronJob: 4. Vertaa ja poista - CronJob->>PVC: poista vanhentuneet - - Note over CronJob: 5. Skaalaa deployment 1:een + Note over Sidecar: 4. Luo whiteout-tar + PATCH + Sidecar->>GP: PATCH / (whiteout) + GP-->>Sidecar: 200 OK ``` **Huomio:** Retention-PAT:in omistajalla on oltava lukuoikeus KAIKKIIN repoihin, diff --git a/git-pages/templates/init-job.yaml b/git-pages/templates/init-job.yaml new file mode 100644 index 0000000..ef6403b --- /dev/null +++ b/git-pages/templates/init-job.yaml @@ -0,0 +1,48 @@ +{{- if .Values.initJob.enabled }} +apiVersion: batch/v1 +kind: Job +metadata: + name: {{ include "git-pages.fullname" . }}-init + labels: + {{- include "git-pages.componentLabels" . | nindent 4 }} + annotations: + "helm.sh/hook": post-install, post-upgrade + "helm.sh/hook-delete-policy": hook-succeeded,before-hook-creation +spec: + backoffLimit: 5 + template: + metadata: + labels: + app.kubernetes.io/name: {{ include "git-pages.name" . }}-init + app.kubernetes.io/instance: {{ .Release.Name }} + spec: + restartPolicy: Never + containers: + - name: init + image: "{{ .Values.initJob.image.repository }}:{{ .Values.initJob.image.tag }}" + imagePullPolicy: {{ .Values.initJob.image.pullPolicy }} + command: + - bash + - -c + - | + set -euo pipefail + apt-get update -qq && apt-get install -y -qq curl tar >/dev/null + echo "Init: waiting for git-pages..." + until curl -sf \ + -H "Host: {{ .Values.ingress.host }}" \ + -o /dev/null "http://git-pages:3000/.git-pages/health" + do sleep 2; done + echo "Init: creating placeholder site..." + WORK=$(mktemp -d) + mkdir -p "$WORK/__init__" + echo "initialized" > "$WORK/__init__/index.html" + tar cf /tmp/init.tar -C "$WORK" __init__ + curl -sf -X PUT "http://git-pages:3000/" \ + -H "Host: {{ .Values.ingress.host }}" \ + -H "Content-Type: application/x-tar" \ + --data-binary @/tmp/init.tar -o /dev/null + echo "Init: done" + env: + - name: PAGES_INSECURE + value: "1" +{{- end }} diff --git a/git-pages/values.yaml b/git-pages/values.yaml index 0187f1b..29f4ede 100644 --- a/git-pages/values.yaml +++ b/git-pages/values.yaml @@ -37,6 +37,15 @@ ingress: certificate: enabled: true +# Post-install init job: creates placeholder site so .index exists. +# Consumers can use PATCH directly without PUT fallback. +initJob: + enabled: true + image: + repository: debian + tag: bookworm-slim + pullPolicy: IfNotPresent + # Optional Helm-managed secret — prefer manual create (see docs/secrets.md). publishAuth: create: false diff --git a/scripts/publish-git-pages.sh b/scripts/publish-git-pages.sh index 2e3fca3..e6c3456 100755 --- a/scripts/publish-git-pages.sh +++ b/scripts/publish-git-pages.sh @@ -50,15 +50,6 @@ publish() { HTTP_CODE=$(publish PATCH) -if [ "$HTTP_CODE" = "503" ]; then - HTTP_CODE=$(curl -sS -X PUT "$PUBLISH_SITE_URL" \ - -u "${GIT_PAGES_PUBLISH_USER}:${GIT_PAGES_PUBLISH_TOKEN}" \ - -H "Content-Type: application/x-tar" \ - --data-binary @"$TAR" \ - -o /tmp/git-pages-publish-response.txt \ - -w "%{http_code}") -fi - case "$HTTP_CODE" in 200|201|204) ;; *)