Feature/docker kuntoon (#11)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com>
Reviewed-on: #11

docs/adr/0006-directory-ownership.md

@@ -6,8 +6,8 @@ Provider-repossa (`gitea-ci-library`) kansioiden omistajuus on seuraava:
 
 | Kansio / Tiedosto | Omistaja | Tyyppi |
 |-------------------|----------|--------|
-| `.gitea/workflows/` | Sekoitettu | Providerin reusable workflowt + consumerin pipeline |
-| `.gitea/workflows/gitea-env.conf` | Consumer | KEY=VALUE config |
+| `.gitea/workflows/` | Sekoitettu | Providerin reusable workflowt + consumerin example-pipeline |
+| `.gitea/workflows/example-gitea-env.conf` | Consumer | KEY=VALUE config |
 | `.gitea/scripts/` | Consumer | Consumer-skriptit |
 | `scripts/` | Provider | Providerin sisäiset työkalut |
 
@@ -30,12 +30,12 @@ uses: org/repo/scripts/workflow.yml@branch
 ```
 
 Tästä syystä providerin reusable workflowt (`config-provider.yml`,
-`build-feature.yml`) ovat samassa `.gitea/workflows/`-kansiossa consumerin
-pipeline-tiedostojen (`ci.yml`) kanssa.
+`check-version.yml`, `docker-build-push.yml`) ovat samassa `.gitea/workflows/`-kansiossa
+consumerin esimerkkipipeline-tiedostojen (`example-*`) kanssa.
 
 Erottelu on nimessä ja dokumentaatiossa, ei kansiorakenteessa:
-- `config-provider.yml`, `build-feature.yml` — providerin tarjoamia
-- `ci.yml` — consumerin omistamia
+- `config-provider.yml`, `check-version.yml`, `docker-build-push.yml` — providerin tarjoamia
+- `example-feature.yml`, `example-main.yml`, `example-*.yml` — consumer-esimerkkejä
 
 ## Providerin `scripts/` (juuressa)
 
@@ -52,7 +52,7 @@ Consumerin omat skriptit, osana consumerin pipeline-logiikkaa.
 Kutsutaan consumerin workflowista ilman tupla checkouttia:
 `.gitea/scripts/bats-report.sh`.
 
-## Consumerin `.gitea/workflows/gitea-env.conf`
+## Consumerin `.gitea/workflows/example-gitea-env.conf`
 
 Consumerin konfiguraatiotiedosto. Providerin `config-provider.yml`
 lukee tämän ja muuntaa JSONiksi, mutta consumer omistaa sisällön.
@@ -61,8 +61,7 @@ lukee tämän ja muuntaa JSONiksi, mutta consumer omistaa sisällön.
 
 - Provider voi muuttaa `scripts/` ja `config-provider.yml` sisältöä
   ilman consumerin hyväksyntää (versiovaihdon yhteydessä)
-- Consumer voi muuttaa `.gitea/workflows/ci.yml`,
-  `.gitea/workflows/build-feature.yml` ja `.gitea/scripts/` sisältöä
+- Consumer voi muuttaa `example-*.yml` ja `.gitea/scripts/` sisältöä
   ilman providerin muutoksia
 - Providerin workflowt käyttävät `.ci/scripts/...` -polkua (tupla checkout)
 - Consumerin workflowt käyttävät `.gitea/scripts/...` -polkua (natiivi checkout)

docs/adr/0007-status-reporting-pattern.md

@@ -0,0 +1,85 @@
+# 7. Statusraportoinnin pattern
+
+## Päätös
+
+Gitea Actionsin natiivi job-status on ensisijainen. Commit-status API:a
+(`report-status.sh`) käytetään **vain** kun työvaihe tuottaa ulkoisen linkin
+(testiraportti, Docker registry), jota natiivistaatus ei tue.
+
+### Tool-jobit (validate, check-version, tag-commit)
+
+Ei API-kutsuja. Luotetaan Gitean omaan job-statukseen.
+
+```yaml
+- uses: actions/checkout@v4
+
+- name: Do work
+  run: do-something
+```
+
+### Test-jobit (bats, cucumber)
+
+API:a käytetään raporttilinkin upottamiseksi commit-näkymään.
+
+```
+testit → publish (always) → status (always, exit-koodin mukaan)
+```
+
+```yaml
+- name: Run tests
+  shell: bash
+  run: |
+    run-tests
+    EXIT=$?
+    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
+    exit ${EXIT}
+
+- name: Publish reports
+  if: always()
+  run: bash .ci/scripts/publish-git-pages.sh bats
+
+- name: Report status
+  if: always()
+  shell: bash
+  run: |
+    if [ "${EXIT}" = "0" ]; then
+      bash .ci/scripts/report-status.sh success "Link to Bats reports" unit-tests bats
+    else
+      bash .ci/scripts/report-status.sh failure "Link to Bats reports" unit-tests bats
+    fi
+```
+
+### Build & push -jobit (docker-build-push)
+
+API:a käytetään Docker registry -linkin upottamiseksi.
+
+```
+build → push → SUCCESS (registry-linkillä) / FAILURE
+```
+
+## Periaatteet
+
+1. Gitea Actionsin natiivi job-status on ensisijainen — myös PENDING/Running-tila
+   tulee natiivisti. API:a käytetään vain custom-linkin tarpeeseen (ADR 0004).
+2. `run`-komennon on nostettava virhe ylös — oli kyse tool-callista tai
+   testivirheestä (ADR 0008).
+3. Test-jobit käyttävät `if: always()` publish- ja status-stepeissä — raportti
+   julkaistaan ja status asetetaan aina, riippumatta testin lopputuloksesta.
+4. Testiraportit julkaistaan myös virhetilanteessa, mikäli ne ovat syntyneet.
+5. Commit-statuksen duplikaatio natiivijob-statuksen kanssa hyväksytään
+   testijobeille — se on ainoa mekanismi upottaa raporttilinkki commit-näkymään.
+6. Tool-jobit eivät käytä API:a lainkaan — ne luottavat Gitean natiiviin
+   job-statukseen.
+
+## Tausta
+
+Aiemmin commit-status API:a käytettiin jokaisessa työvaiheessa, myös niissä
+joilla ei ollut raporttia linkitettäväksi (validate, check-version, tag-commit).
+Tämä tuotti duplikaatiota: Gitea näytti sekä natiivin `CI Main / Validate CI config
+Successful` että API-statuksen `ci-validate CI config valid`. Kehittäjälle
+molemmat kertoivat saman asian.
+
+Käytännön pakko kuitenkin pakottaa API:n käyttöön testijobeissa: ilman
+raporttilinkkiä kukaan ei löydä testituloksia. Gitean natiivi job-status
+linkittää aina jobin lokiin — ei ulkoiseen raporttiin. Tämä on paras
+saatavilla oleva kompromissi.

docs/adr/0008-exit-code.md

@@ -0,0 +1,73 @@
+# 8. Exit code — ainoa onnistumisen mittari
+
+## Päätös
+
+Jokaisen `run`-stepin on nostettava virheellinen exit-koodi ylös sellaisenaan.
+Exit-koodia ei saa "syödä" missään tilanteessa. Onnistumisen ja epäonnistumisen
+päättely tapahtuu **ainoastaan** exit-koodin perusteella — ei tiedostojen
+olemassaolon, stdout-tulosteen tai minkään muun heuristiikan perusteella.
+
+## Periaatteet
+
+1. Exit-koodi on ainoa totuus. `0` = onnistui, kaikki muut = epäonnistui.
+2. Exit-koodia ei saa syödä. Pipe (`|`) viimeisenä komentona `tee`:hen syö
+   exit-koodin — `docker run … | tee file` palauttaa aina 0.
+3. Data transfer -pipet ovat sallittuja (`tar c . | docker run … tar x`),
+   koska niiden exit-koodilla ei ole semanttista merkitystä.
+4. Testien tai työkalujen ajaminen ei saa päättyä pipeen.
+5. `set -o pipefail` ei ole riittävä suojaus — PIPESTATUS resetoituu herkästi.
+
+## Sallitut patternit
+
+```yaml
+# Oikein: suora ajo, exit koodi $?:iin
+- name: Do work
+  run: |
+    some-command
+    EXIT=$?
+    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
+    exit ${EXIT}
+
+# Oikein: stdout talteen ilman pipeä
+- name: Do work
+  run: |
+    some-command > results.txt 2>&1
+    EXIT=$?
+    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
+    exit ${EXIT}
+
+# Oikein: docker run ilman pipeä
+- name: Run in container
+  run: |
+    docker run --rm image command > output.txt 2>&1
+    EXIT=$?
+    exit ${EXIT}
+```
+
+## Kielletyt patternit
+
+```yaml
+# Väärin: pipe syö exit-koodin
+- run: docker run … | tee results.txt
+
+# Väärin: pipe syö exit-koodin
+- run: tar … | docker … | tee file
+
+# Väärin: onnistumisen päättely tiedoston olemassaolosta
+- run: |
+    some-command || true
+    [ -f success.txt ] && exit 0 || exit 1
+```
+
+## Tausta
+
+Gitea Actionsissa `run`-stepin tila määräytyy viimeisen komennon exit-koodista.
+Pipe (`|`) asettaa `$?`:ksi viimeisen komennon tuloksen — jos viimeinen komento
+on `tee`, tulos on aina 0 riippumatta siitä mitä aiemmat komennot palauttivat.
+
+Tämä on aiheuttanut tuotannossa tilanteita, joissa testit feilasivat mutta jobi
+näytti vihreää, koska `tee` söi exit-koodin. Virhe havaittiin vasta kun raportteja
+alettiin lukea manuaalisesti — commit-status valehteli.
+
+Ratkaisu on yksiselitteinen: exit-koodi talteen `$?`-muuttujaan ennen kuin mikään
+muu komento ehtii muuttaa sitä, ja stepin viimeinen komento on aina `exit ${EXIT}`.