moilanik
87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
**⚠️ 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ä)
|