gitea-ci-library/docs/ci-pipeline-practices.md

⚠️ 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ä)