Feature/ci container (#15)

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

.gitea/workflows/ci-container-build-push.yml

@@ -0,0 +1,57 @@
+name: CI Container Build & Push
+on:
+  workflow_call:
+    inputs:
+      env_json:
+        required: true
+        type: string
+      dockerfile_path:
+        required: true
+        type: string
+      image_name:
+        required: true
+        type: string
+      tag:
+        required: true
+        type: string
+    secrets:
+      DOCKER_USERNAME:
+        required: false
+      DOCKER_PASSWORD:
+        required: true
+
+env:
+  DOCKER_REGISTRY: ${{ fromJson(inputs.env_json).DOCKER_REGISTRY || '' }}
+  IMAGE_NAME: ${{ inputs.image_name }}
+  TAG: ${{ inputs.tag }}
+  DOCKERFILE: ${{ inputs.dockerfile_path }}
+
+jobs:
+  build-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build and push CI container
+        env:
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME || github.actor }}
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+        run: |
+          NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          docker build \
+            --label "git.commit=${{ github.sha }}" \
+            --label "git.commitBy=${{ github.actor }}" \
+            --label "build.date=${NOW}" \
+            -f "${DOCKERFILE}" \
+            -t "${IMAGE_NAME}:${TAG}" .
+
+          REGISTRY="${DOCKER_REGISTRY:?DOCKER_REGISTRY not set in env.conf}"
+          REGISTRY_HOST="${REGISTRY%%/*}"
+
+          FULL_IMAGE="${REGISTRY}/${IMAGE_NAME}:${TAG}"
+          echo "Pushing ${FULL_IMAGE} ..."
+
+          docker tag "${IMAGE_NAME}:${TAG}" "$FULL_IMAGE"
+          echo "$DOCKER_PASSWORD" | docker login "$REGISTRY_HOST" -u "$DOCKER_USERNAME" --password-stdin
+          docker push "$FULL_IMAGE"
+          docker logout "$REGISTRY_HOST"

.gitea/workflows/example-build-ci-bats.yml

@@ -0,0 +1,21 @@
+name: Build CI Bats Container (Manual)
+on: workflow_dispatch
+
+jobs:
+  load-config:
+    name: Load config
+    uses: niko/gitea-ci-library/.gitea/workflows/config-provider.yml@main
+    secrets: inherit
+    with:
+      config_path: .gitea/workflows/example-gitea-env.conf
+
+  build-push:
+    name: Build & Push
+    needs: [load-config]
+    uses: niko/gitea-ci-library/.gitea/workflows/ci-container-build-push.yml@main
+    secrets: inherit
+    with:
+      env_json: ${{ needs.load-config.outputs.env_json }}
+      dockerfile_path: Dockerfile.ci-bats
+      image_name: ci-bats
+      tag: latest

.gitea/workflows/example-build-ci-cucumber.yml

@@ -0,0 +1,21 @@
+name: Build CI Cucumber Container (Manual)
+on: workflow_dispatch
+
+jobs:
+  load-config:
+    name: Load config
+    uses: niko/gitea-ci-library/.gitea/workflows/config-provider.yml@main
+    secrets: inherit
+    with:
+      config_path: .gitea/workflows/example-gitea-env.conf
+
+  build-push:
+    name: Build & Push
+    needs: [load-config]
+    uses: niko/gitea-ci-library/.gitea/workflows/ci-container-build-push.yml@main
+    secrets: inherit
+    with:
+      env_json: ${{ needs.load-config.outputs.env_json }}
+      dockerfile_path: Dockerfile.ci-cucumber
+      image_name: ci-cucumber
+      tag: latest

.gitea/workflows/example-feature.yml

@@ -35,7 +35,7 @@ jobs:
     name: Report Summary
     needs: [load-config, bats, cucumber]
     if: always()
-    uses: niko/gitea-ci-library/.gitea/workflows/example-report-summary.yml@main
+    uses: niko/gitea-ci-library/.gitea/workflows/report-summary.yml@main
     with:
       env_json: ${{ needs.load-config.outputs.env_json }}
       suites: bats cucumber

.gitea/workflows/example-main.yml

@@ -53,9 +53,16 @@ jobs:
 
   report-summary:
     name: Report Summary
-    needs: [load-config, bats, cucumber]
+    needs: [load-config, build-push]
     if: always()
-    uses: niko/gitea-ci-library/.gitea/workflows/example-report-summary.yml@main
+    uses: niko/gitea-ci-library/.gitea/workflows/report-summary.yml@main
     with:
       env_json: ${{ needs.load-config.outputs.env_json }}
       suites: bats cucumber
+
+  tag-maintenance:
+    name: Move provider version tag
+    needs: [build-push]
+    if: success()
+    uses: niko/gitea-ci-library/.gitea/workflows/tag-maintenance.yml@main
+    secrets: inherit

.gitea/workflows/example-manual-hello.yml

@@ -0,0 +1,11 @@
+name: Hello World (Manual)
+on:
+  workflow_dispatch:
+  push:
+    # branches: [ main ] # Tai [ feature/ci-container ]
+    branches: [feature/ci-container]
+jobs:
+  greet:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Hello"

.gitea/workflows/tag-maintenance.yml

@@ -0,0 +1,38 @@
+name: Tag Maintenance
+on:
+  workflow_call:
+    secrets:
+      GITEA_TOKEN:
+        required: true
+
+jobs:
+  move-tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Read current provider version
+        id: version
+        run: echo "TAG=$(cat CURRENT_PROVIDER_VERSION | tr -d '[:space:]')" >> "$GITHUB_OUTPUT"
+
+      - name: Move tag to commit
+        run: |
+          TAG="${{ steps.version.outputs.TAG }}"
+          SHA="${{ github.sha }}"
+
+          curl -sf -X DELETE \
+            -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
+            "${{ gitea.server_url }}/api/v1/repos/${{ github.repository }}/tags/${TAG}" || true
+
+          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+            -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            "${{ gitea.server_url }}/api/v1/repos/${{ github.repository }}/tags" \
+            -d "{\"tag_name\": \"${TAG}\", \"message\": \"Release ${TAG}\", \"target\": \"${SHA}\"}")
+
+          if [ "$HTTP_CODE" = "201" ]; then
+            echo "${TAG} tag moved to ${SHA}"
+          else
+            echo "ERROR: failed to move ${TAG} tag (HTTP $HTTP_CODE)" >&2
+            exit 1
+          fi

CURRENT_PROVIDER_VERSION

@@ -0,0 +1 @@
+v1

Dockerfile.ci-bats

@@ -0,0 +1,3 @@
+FROM bats/bats:latest
+RUN apk add --no-cache lsof python3 jq curl ruby && \
+    gem install bashcov -v 3.3.0

Dockerfile.ci-cucumber

@@ -0,0 +1,6 @@
+FROM node:22
+RUN apt-get update -qq && \
+    apt-get install -y -qq --no-install-recommends lsof jq && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/* && \
+    npm install -g @cucumber/cucumber

README.md

@@ -2,6 +2,8 @@
 
 Reusable workflow -kirjasto Gitea Actionsille. Lisätietoja: [docs/](docs/)
 
+**Consumer-käyttöönotto:** [docs/consumer-guide.md](docs/consumer-guide.md) — vaiheittainen ohje uuden projektin liittämiseen
+
 ## Provider-binding — miten consumer löytää providerin
 
 Consumer kutsuu provideria `uses:`-viittauksella. Ei discoveryä — polku kovakoodataan consumerin

docs/adr/0009-breaking-changes-forbidden.md

@@ -0,0 +1,53 @@
+# 9. Breaking changes kielletty
+
+## Päätös
+
+Providerin `v1`-tagin osoittamaa rajapintaa ei koskaan rikota.
+Consumerin `uses:`-kutsut säilyvät yhteensopivina — uusi versiotagi
+(`v2`, `v3`) luodaan VAIN jos taaksepäin yhteensopimaton muutos on
+pakottava. Käytännössä: `v1` on pysyvä, ja sitä ylläpidetään
+eteenpäin.
+
+## Rajapinnan määritelmä
+
+Providerin rajapinta = `config-provider.yml` ja `check-version.yml`
+workflow_call-inputit ja -outputit:
+
+- Inputtien nimet, tyypit ja required-arvot eivät muutu
+- Outputtien nimet eivät katoa
+- Secret-nimet eivät muutu
+- Workflow-tiedoston nimi ja polku eivät muutu
+
+Sisäinen toteutus (scriptit, checkout-logiikka, build-vaiheet) voi
+muuttua vapaasti — consumer ei ole niistä riippuvainen.
+
+## Versiotagin siirto
+
+Tagi `v1` siirretään automaattisesti uusimpaan onnistuneeseen
+main-commitin CI-ajoon (`tag-maintenance.yml`). Tagin nimi luetaan
+tiedostosta `CURRENT_PROVIDER_VERSION`.
+
+Jos breaking change joskus tulee pakottavaksi:
+1. Päivitä `CURRENT_PROVIDER_VERSION` → `v2`
+2. Luo uusi `v2`-tagi manuaalisesti (osoittaa uuteen rajapintaan)
+3. `tag-maintenance.yml` alkaa ylläpitää `v2`:ta eteenpäin
+4. `v1`-tagia **ei poisteta** — se jää osoittamaan viimeistä
+   v1-yhteensopivaa committia. `v1`:tä käyttävät consumerit
+   jatkavat toimintaansa ilman muutoksia.
+5. Uudet consumerit ottavat käyttöön `@v2`:n.
+
+Aktiivisesti ylläpidetään vain yhtä tagia (`CURRENT_PROVIDER_VERSION`).
+Vanhat tagit säilyvät paikoillaan taaksepäin yhteensopivuutta varten.
+
+## Perustelu
+
+Yhden aktiivisen tagin ylläpito on yksinkertaisempaa kuin usean
+rinnakkaisen version aktiivinen hallinta. Homelab-ympäristössä
+consumerit ovat saman ylläpitäjän hallinnassa — eri tiimien
+rinnakkaisia aktiiviversioita ei tarvita.
+
+Breaking changen sattuessa vanha tagi säilyy — vanhat consumerit
+eivät hajoa. Uusi tagi otetaan käyttöön uusissa consumereissa.
+
+Breaking changen kielto pakottaa suunnittelemaan rajapinnat
+huolellisesti etukäteen.

docs/adr/0010-pipeline-router-no-commands.md

@@ -0,0 +1,43 @@
+# 10. Pipeline-reititin — ei komentoja
+
+## Päätös
+
+CI-pipelinetiedostot (`ci-main.yml`, `ci-feature.yml`) ovat puhtaita
+**reitittimiä**. Ne eivät saa sisältää `run:`-komentoja, inline-skriptejä
+tai varsinaista build-/test-logiikkaa. Niiden ainoa sallittu sisältö on:
+
+- `uses:` — viittaus reusable workflow'hun
+- `needs:` — riippuvuus toisen jobin valmistumiseen
+- `if:` — ehdollinen suoritus
+- `secrets: inherit` — salaisuuksien välitys
+
+## Mikä ei kuulu reitittimeen
+
+- `run:`-komennot
+- Inline-skriptit (shell, Python, tms.)
+- `actions/checkout` (paitsi providerin sisäinen infrastruktuuri)
+- Build-työkalut, testikomennot, Docker-komennot
+- Raporttien generointi
+
+## Missä logiikka on
+
+| Kerros | Tiedosto | Sisältö |
+|---|---|---|
+| Reititin | `ci-main.yml`, `ci-feature.yml` | Vain `uses:`-kutsut |
+| Workflow_call | `ci-unit-tests.yml`, `ci-acc-tests.yml`, … | Varsinainen testi-/build-logiikka |
+| Provider | `config-provider.yml`, `check-version.yml`, … | Jaettu infrastruktuuri |
+| Skriptit | `scripts/` | Apufunktiot (status, publish, validointi) |
+
+## Perustelu
+
+Reitittimen ja toteutuksen erottelu:
+
+- Reititin kertoo **mitä** ajetaan ja **missä järjestyksessä** — luettavissa
+  yhdellä silmäyksellä ilman teknistä taustaa
+- Toteutus (workflow_call) kertoo **miten** — tekninen henkilö voi keskittyä
+  yhteen tiedostoon kerrallaan
+- Providerin reusable workflow't eivät koskaan sisällä inline-logiikkaa —
+  skriptit ovat omissa tiedostoissaan
+
+Tämä on sama periaate kuin web-sovelluksissa: reititin ei sisällä
+business-logiikkaa, vain HTTP-verbit ja polut.

docs/ai-context.md

@@ -34,13 +34,14 @@ kuuluu `git-pages/docs/`-alle, ei juuren `docs/`-kansioon.
 | `git-pages/` | Raporttien hostaus (Helm-chartti) |
 | `tests/` | Bats-testit skripteille |
 
-### Provider workflowt (3 kpl)
+### Provider workflowt (4 kpl)
 
 | Workflow | Input | Output | Kuvaus |
 |---|---|---|---|
 | `config-provider.yml` | `config_path` | `env_json`, `config_path` | Validoi ja jäsentää `.conf` → JSON. Sama kutsu hoitaa validoinnin. |
 | `check-version.yml` | `env_json` | `artifact_exists`, `version` | Tarkistaa git-tagit ja `package.json`:n, laskee seuraavan version. Vain main-haarassa. |
 | `docker-build-push.yml` | `env_json`, `version` | — | Buildaa Docker-imagen, puskea rekisteriin, tagittaa commitin. |
+| `report-summary.yml` | `env_json`, `suites` | — | Generoi `GITHUB_STEP_SUMMARY`-taulukon raporttilinkeillä (Gitea 1.27+) |
 
 ### Example-tiedostot (consumer-referenssi)
 
@@ -50,7 +51,6 @@ kuuluu `git-pages/docs/`-alle, ei juuren `docs/`-kansioon.
 | `example-main.yml` | push [main] | load-config → check-version → bats + cucumber → report-summary → docker-build-push |
 | `example-bats-tests.yml` | workflow_call | Unit-testit Batsilla, raportit git-pagesiin, status linkillä |
 | `example-cucumber-tests.yml` | workflow_call | Hyväksymätestit Cucumberilla, raportit git-pagesiin, status linkillä |
-| `example-report-summary.yml` | workflow_call | `GITHUB_STEP_SUMMARY`-taulukko raporttilinkeillä (Gitea 1.27+) |
 | `example-gitea-env.conf` | — | KEY=VALUE config tälle repolle |
 
 ## Key Technical Decisions

docs/architecture.md

@@ -33,7 +33,7 @@ Tarkemmin: ADR 0005.
 | `example-main.yml` | Consumer | Main-haaran CI: load-config → check-version → bats + cucumber → summary → docker |
 | `example-bats-tests.yml` | Consumer | Unit-testit Batsilla |
 | `example-cucumber-tests.yml` | Consumer | Hyväksymätestit Cucumberilla |
-| `example-report-summary.yml` | Consumer | `GITHUB_STEP_SUMMARY`-taulukko (Gitea 1.27+) |
+| `report-summary.yml` | Provider | `GITHUB_STEP_SUMMARY`-taulukko raporttilinkeillä (Gitea 1.27+) |
 | `publish-git-pages.sh` | Provider-skripti | PATCH tar git-pagesiin |
 | `report-status.sh` | Provider-skripti | POSTaa commit-status (vain custom-linkkiin) |
 | `ci-validate.sh` | Provider-skripti | Validoi `.conf`-tiedoston ja tarkistaa secretit |

docs/config-model.md

@@ -87,7 +87,7 @@ JSON-muotoisen `env_json`:n.
 Kutsu:
 ```yaml
 load-config:
-    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@main
+    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1
     secrets: inherit
     with:
       config_path: .gitea/workflows/gitea-env.conf

docs/consumer-guide.md

@@ -137,7 +137,7 @@ on:
 
 jobs:
   load-config:
-    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@main
+    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1
     secrets: inherit
     with:
       config_path: .gitea/workflows/gitea-env.conf
@@ -159,7 +159,7 @@ jobs:
   report-summary:
     needs: [load-config, unit-tests, acc-tests]
     if: always()
-    uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@main
+    uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@v1
     with:
       env_json: ${{ needs.load-config.outputs.env_json }}
       suites: junit cucumber
@@ -181,14 +181,14 @@ on:
 
 jobs:
   load-config:
-    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@main
+    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1
     secrets: inherit
     with:
       config_path: .gitea/workflows/gitea-env.conf
 
   check-version:
     needs: [load-config]
-    uses: org/gitea-ci-library/.gitea/workflows/check-version.yml@main
+    uses: org/gitea-ci-library/.gitea/workflows/check-version.yml@v1
     secrets: inherit
     with:
       env_json: ${{ needs.load-config.outputs.env_json }}
@@ -212,7 +212,7 @@ jobs:
   build-push:
     needs: [load-config, check-version, unit-tests, acc-tests]
     if: needs.check-version.outputs.artifact_exists != 'true'
-    uses: org/gitea-ci-library/.gitea/workflows/docker-build-push.yml@main
+    uses: org/gitea-ci-library/.gitea/workflows/docker-build-push.yml@v1
     secrets: inherit
     with:
       env_json: ${{ needs.load-config.outputs.env_json }}
@@ -221,7 +221,7 @@ jobs:
   report-summary:
     needs: [load-config, unit-tests, acc-tests]
     if: always()
-    uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@main
+    uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@v1
     with:
       env_json: ${{ needs.load-config.outputs.env_json }}
       suites: junit cucumber
@@ -388,3 +388,59 @@ hajota vanhemmilla versioilla.
 | `report-status.sh` | POSTaa commit-statuksen linkillä |
 | `publish-git-pages.sh` | Julkaisee raporttihakemiston git-pagesiin |
 | `ci-validate.sh` | Validoi `.conf`-tiedoston (kutsutaan `config-provider.yml`:stä) |
+
+---
+
+## ADR-yhteenveto — consumerin kannalta oleelliset säännöt
+
+Nämä säännöt on formalisoitu [docs/adr/](docs/adr/)-hakemistossa. Tässä tiivistelmä
+consumer-näkökulmasta:
+
+### Reititin ei sisällä suorittavaa koodia (ADR 0010)
+
+`ci-feature.yml` ja `ci-main.yml` ovat **puhtaita reitittimiä**:
+- **Vain** `uses:`, `needs:` ja `if:` sallittu
+- **Ei** `run:`-komentoja, ei inline-skriptejä, ei `actions/checkout`
+
+Kaikki suorittava koodi on omissa `workflow_call`-tiedostoissaan:
+- `ci-unit-tests.yml` — testikomento, publish, status
+- `ci-acc-tests.yml` — testikomento, publish, status
+- Provider-workflowt (`config-provider.yml`, `check-version.yml`, …)
+
+### Yksi steppi = yksi workflow_call-tiedosto
+
+Jokainen pipeline-steppi (testityyppi, build, deploy) on oma tiedostonsa.
+Ei kahta eri komentoa samassa workflow'ssa. Tämä pitää reitittimet ohuina
+ja steppitiedostot itsenäisinä — testattavissa erikseen.
+
+### Provider-versio on `@v1` (ADR 0009)
+
+Kaikki `org/gitea-ci-library/…`-viittaukset käyttävät `@v1`-tagia:
+```yaml
+uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1
+```
+`@main` on vain providerin oman repon sisäiseen dogfood-käyttöön.
+
+Breaking changet on kielletty — `v1`-rajapinta on pysyvä.
+
+### Exit-koodi on ainoa onnistumisen mittari (ADR 0008)
+
+Älä käytä pipeä (`|`) komennon perässä — se syö exit-koodin.
+Käytä redirectiä (`> file 2>&1`) jos haluat logit talteen.
+
+### Commit-status vain raporttilinkille (ADR 0007)
+
+`report-status.sh`-skriptiä käytetään VAIN kun on raportti linkitettäväksi.
+Tool-jobit (build, deploy) luottavat Gitean natiiviin job-statukseen.
+
+### Providerin checkout ei kuulu consumerille
+
+Providerin scriptit haetaan `actions/checkout`-stepillä. Consumer käyttää
+providerin määrittelemää polkua (`.ci/scripts/`). Consumer ei kopioi eikä
+muokkaa providerin tiedostoja.
+
+### Testattavuus
+
+Jokainen `workflow_call`-tiedosto on testattavissa itsenäisesti — consumer
+voi ajaa `ci-unit-tests.yml`:n paikallisesti act:lla tai Gitean
+`workflow_dispatch`:llä ilman koko pipelineä.

docs/workflows.md

@@ -108,7 +108,7 @@ raportit git-pagesiin, asettaa commit-statuksen linkillä raporttiin.
 Ajaa Cucumber-testit Node-kontissa, julkaisee raportit git-pagesiin, asettaa
 commit-statuksen linkillä raporttiin.
 
-### `example-report-summary.yml` — Raporttien koontinäkymä
+### `report-summary.yml` — Raporttien koontinäkymä
 
 **Trigger:** `workflow_call` — ajetaan `if: always()` testien jälkeen