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