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. 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

Cross-job config propagation (validated 2026-06-13)

Workflow env: on ainoa natiivi mekanismi, joka tekee arvoista näkyviä kaikissa jobeissa automaattisesti. Ketju:

feature-env.conf  →  config-provider.yml  →  env_json (single JSON string output)
                                                 ↓
                                        ci.yml with: env_json
                                                 ↓
                                        build-feature.yml workflow env:
                                          fromJson(inputs.env_json).KEY
                                                 ↓
                                        kaikki jobit → $KEY

Avainkomponentit:

• config-provider.yml — reusable workflow, lukee conf-tiedoston → yksi JSON output
• needs + with: — jobs.<job_id>.with tukee needs-kontekstia, joten ${{ needs.load-config.outputs.env_json }} toimii
• workflow env: — ainoa tapa jakaa arvot kaikkiin jobeihin. fromJson(inputs.env_json).KEY purkaa yksittäiset arvot
• Per-job env: — sisältää vain secretit (GITEA_TOKEN, GIT_PAGES_PUBLISH_TOKEN), ei config-arvoja

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