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)

Config-arvojen vienti kaikkiin jobeihin ilman toistoa vaatii kahden mekanismin ketjuttamista:

1. needs + with: — jobs.<job_id>.with.<with_id> tukee needs-kontekstia. Tämä mahdollistaa sen, että yhden jobin outputit voidaan välittää toiselle reusable workflowille inputeina.
2. Workflow env: — ainoa natiivi mekanismi, joka tekee arvoista näkyviä kaikissa jobeissa automaattisesti (POC validioitu).

Ketju toimii näin:

feature-env.conf  →  config-provider.yml  →  env_json (yksi JSON-string)
       (1)                                    (2)
                                                 ↓
                                        ci.yml with: env_json
                                        ${{ needs.load-config.outputs.env_json }}
                                          (3)
                                                 ↓
                                        build-feature.yml workflow env:
                                        GITEA_API_URL: ${{ fromJson(inputs.env_json).GITEA_API_URL }}
                                          (4)
                                                 ↓
                                        kaikki jobit → $GITEA_API_URL, $PAGES_HOST jne.
                                          (5)

Vaiheet:

1. Consumer määrittelee arvot feature-env.conf:ssä (KEY=VALUE)
2. config-provider.yml lukee confin ja tuottaa yhden JSON-stringin outputina
3. ci.yml välittää JSONin needs + with: -ketjulla
4. build-feature.yml purkaa arvot workflow env:-tasolle fromJson():lla
5. Kaikki jobit käyttävät valmiita env-muuttujia ($PAGES_HOST jne.)

Avainkomponentit:

• config-provider.yml — reusable workflow, joka muuntaa conf-tiedoston yhdeksi JSON-outputiksi. Yksi output riittää, ei per-key outputteja.
• jobs.<job_id>.with — tukee needs-kontekstia (Gitea Actions, kuten GitHub Actions). Tämä on kriittinen yksityiskohta: ilman tätä config-arvoja ei voi välittää reusable workflowille dynaamisesti.
• workflow env: — ainoa tapa jakaa arvot kaikkiin jobeihin. fromJson(inputs.env_json).KEY purkaa yksittäiset arvot ilman toistoa.
• 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ä)