masteria varten haarat kuntoon

docs/ci-pipeline-practices.md

@@ -147,7 +147,73 @@ Tämä takaa:
 
 Julkaisu (`publish-git-pages.sh`) jää edelleen omaksi stepikseen `if: always()`:lla.
 
-## 8. Inline Logic Threshold
+## 8. Pipeline Exit Code Safety (validated 2026-06-14)
+
+Pipeline (`cmd1 | cmd2 | cmd3`) asettaa `$?`:ksi **viimeisen** komennon exit-koodin. Jos `tee` tai muu aina-onnistuva komento on viimeisenä, testin todellinen exit-koodi katoaa.
+
+### Dangerous patterns
+
+| Pattern | `$?` captures | Result |
+|---------|---------------|--------|
+| `docker run … \| tee file` | `tee`:n exit (0) | ❌ test error kadotettu |
+| `tar \| docker \| tee` | `tee`:n exit (0) | ❌ test error kadotettu |
+| `docker run … 2>&1 \| tee file` | `tee`:n exit (0) | ❌ stderr-ohjaus ei auta |
+| `set -o pipefail` + pipeline | viimeisen epäonnistuneen exit | ⚠️ pipefail riippuu bash-versiosta ja PIPESTATUS resetoituu helposti |
+
+### Safe patterns
+
+| Pattern | `$?` captures | Verified |
+|---------|---------------|----------|
+| `docker run … > file 2>&1` | suoraan kontin exit | ✅ lokaali + CI |
+| `docker volume` + `tar \| alpine tar x` (data transfer) + `docker run > file` | suoraan kontin exit | ✅ lokaali + CI |
+
+### Why volume-based approach works
+
+Kolmen erillisen komennon ketju ilman testiä putkittavaa pipeä:
+
+```
+docker volume create ws           # 1. volyymi
+tar c . | docker run … alpine …   # 2. data volyymiin (tämä on pipe, mutta data transfer)
+docker run -v ws:/data … > file   # 3. testit → exit koodi $?:iin puhtaana
+```
+
+Vaihe 2 on pipe, mutta se on **data transfer** — sen exit-koodilla ei ole väliä. Vaihe 3 on suora `docker run > file` ilman pipeä, joten `$?` on aina kontin exit.
+
+### Debug-näkyvyys ilman tee:tä
+
+`tee` antaa real-time logit, mutta tappaa exit-koodin. Ratkaisu: jaa kahteen steppiin:
+
+```yaml
+- name: Run tests
+  run: |
+    docker run … > results.txt 2>&1
+    EXIT=$?
+    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
+    exit ${EXIT}
+
+- name: Publish reports
+  if: always()
+  run: publish.sh
+
+- name: Set commit status
+  if: always()
+  run: |
+    [ "${EXIT}" = "0" ] && report-status.sh success … || report-status.sh failure …
+```
+
+`if: always()` julkaisee raportit ja asettaa commit statuksen riippumatta testin lopputuloksesta. `GITHUB_ENV`:iin talletettu exit-koodi on luettavissa myöhemmissä stepeissä.
+
+### Oppitunti
+
+Pienikin muutos — kuten `| tee` lisääminen debug-näkyvyyttä varten — voi murtaa error propagationin huomaamatta. Ainoa tapa varmistua on testata lokaalisti kontissa:
+
+```bash
+docker run … > results.txt 2>&1
+EXIT=$?
+echo $EXIT   # pitää olla 1 jos testit failaa
+```
+
+## 9. Inline Logic Threshold
 
 Logiikka workflow YAML:ssa on hauras: YAML:n sisennys, heredocit ja
 kenoviivat tuottavat helposti toimimattomia steppejä.