POC: test reusable workflow job visibility in Gitea Actions (#5)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com>
Reviewed-on: #5

docs/ci-pipeline-practices.md

@@ -0,0 +1,62 @@
+# 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. Env variable scope (validated 2026-06-13)
+
+`env:` — oli se workflow- tai job-tasolla — toimii vain **natiiveissa shell-stepeissä** ja `docker run -e VAR` -komennoissa. `docker run` ilman `-e`-lippua **ei peri** `env:`-muuttujia.
+
+Tämä on validioitu POC-ajolla: `tmp/poc-env-scope.yml`
+
+| Sijainti | Native shell | `docker run` ilman `-e` | `docker run -e VAR` |
+|----------|-------------|------------------------|---------------------|
+| workflow `env:` | ✅ perii | ❌ tyhjä | ✅ perii |
+| job `env:` | ✅ perii | ❌ tyhjä | ✅ perii |
+| `GITHUB_ENV` | ✅ perii | ❌ tyhjä | ✅ perii |
+
+Käytäntö:
+- Workflow-tason `env:` sopii arvoille, joita tarvitaan natiivistepeissä (publish, status, reportointi)
+- Jos `docker run` tarvitsee env-arvoja, välitä ne eksplisiittisesti `-e VAR`-lipulla
+- `GITHUB_ENV` on validi tapa välittää arvoja stepien välille samassa jobissa, mutta ei leviä `docker run`-kontteihin ilman `-e`-lippua
+
+## 5. 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`
+
+## 6. 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ä)