dokumetti päivitys

docs/adr/0006-directory-ownership.md

@@ -16,6 +16,19 @@ Provider-repossa (`gitea-ci-library`) kansioiden omistajuus on seuraava:
 Gitea Actions vaatii, että `uses:`-direktiivillä kutsuttavat workflowt
 ovat muodossa `{owner}/{repo}/.gitea/workflows/{file}@{ref}`.
 
+**Tämä on Gitea Actionsin asettama tekninen rajoite.** Toimivia
+polkuja ovat vain:
+
+```
+# ✅ kelpaa
+uses: org/repo/.gitea/workflows/file.yml@branch
+
+# ❌ eivät kelpaa
+uses: org/repo/workflows/file.yml@branch
+uses: org/repo/.gitea/workflows/path/file.yml@branch
+uses: org/repo/scripts/workflow.yml@branch
+```
+
 Tästä syystä providerin reusable workflowt (`config-provider.yml`,
 `ci-engine.yml`) ovat samassa `.gitea/workflows/`-kansiossa consumerin
 pipeline-tiedostojen (`ci.yml`, `build-feature.yml`) kanssa.

docs/ci-pipeline-practices.md

@@ -52,24 +52,50 @@ Käytäntö:
 
 ### Cross-job config propagation (validated 2026-06-13)
 
-Workflow `env:` on ainoa natiivi mekanismi, joka tekee arvoista näkyviä kaikissa jobeissa automaattisesti. Ketju:
+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 (single JSON string output)
+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:
-                                          fromJson(inputs.env_json).KEY
+                                        GITEA_API_URL: ${{ fromJson(inputs.env_json).GITEA_API_URL }}
+                                          (4)
                                                  ↓
-                                        kaikki jobit → $KEY
+                                        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, 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
+- **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