From c85933b28d76521036d3550c2a5faefe65d04f40 Mon Sep 17 00:00:00 2001 From: moilanik Date: Sat, 13 Jun 2026 08:05:39 +0300 Subject: [PATCH] pipeline dokumentaatiota --- docs/ci-pipeline-practices.md | 47 +++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/ci-pipeline-practices.md diff --git a/docs/ci-pipeline-practices.md b/docs/ci-pipeline-practices.md new file mode 100644 index 0000000..42a01f6 --- /dev/null +++ b/docs/ci-pipeline-practices.md @@ -0,0 +1,47 @@ +> **⚠️ STATUS: ALERT DRAFT** — Ei ole validoitu. Voi sisältää virheellisiä tai puutteellisia käytäntöjä. + +# CI Pipeline Practices + +## 1. Error Taxonomy + +| Taso | Esimerkki | Status URL | Job status | +|---|---|---|---| +| Tool failure | npx ei löydy, python3 puuttuu | Gitea Actions logi | fail | +| Test failure | assertio feilaa, testi palauttaa nollasta poikkeavan | Raportti git-pagesissa | fail | +| Suite failure | Build ei päässyt ajoon | Raportti git-pagesissa | fail | + +- Tool ja test erotetaan omiin steppeihin +- Tool check: `--help` ei riitä, lataa `--dry-run` moduulit +- Tool fail → linkki Gitea logiin; test fail → linkki raporttiin +- Jobin status tulee exit-koodista (`exit $?`), ei raporttitiedostojen olemassaolosta + +## 2. Job Reporting + +- Jokainen suite julkaisee raporttinsa omaan alihakemistoonsa: `reports/{SHA8}/{suite}/` +- Commit status URL osoittaa suoraan suitelinkkiin +- Raportit tuotetaan ja julkaistaan aina (`if: always()`) — testin lopputuloksesta riippumatta +- Linkkejä summary-sivuille ei tarvita — kukaan ei sinne pääse ilman suoraa URLia +- Index.html suitetason raporttiin generoidaan aina, linkittää kaikkiin suiten tiedostoihin + +## 3. Docker-in-Docker Volume Mount + +Runner-kontti ja Docker daemon näkevät eri polut. `-v "$PWD":/path` ei toimi — runner-näkökulman polku ei ole daemonin näkökulman polku. + +Kolme toimivaa vaihtoehtoa: +- `container:` keyword — runner hoitaa mountin oikein +- `docker volume create -- docker run -v volume:/data -- docker run -v volume:/data` +- `tar c . | docker run --rm -i -v volume:/data alpine tar x -C /data` + +## 4. Pipeline Provides All Dependencies + +- Ei luottamusta runnerin esiasennettuihin työkaluihin +- `apk add`, `npm install`, `apt-get install` — kaikki pipelinesta +- Erityisesti: `curl`, `lsof`, `jq`, `python3` unohtuvat helposti +- Node-version päivitettävä jos paketti vaatii uudempaa (`node:20` → `node:22`) +- Jos kontin entrypoint on `sh` (Alpine ash), käytä `--entrypoint bash` + +## 5. Rakenne + +- Rinnakkaiset jobit (bats + cucumber) — tuloksia saa heti kun valmistuu +- Jokainen testisetti omassa jobissaan +- Finalize/build voi kerätä yhteenvedon (ei julkaista summarya jos kenelläkään ei ole linkkiä)