Feature/monorepo support (#18)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com> Reviewed-on: #18
2026-06-17 07:40:24 +03:00
parent 153205be40
commit f17ea7936e
7 changed files with 453 additions and 454 deletions
@@ -30,6 +30,7 @@ kuuluu `git-pages/docs/`-alle, ei juuren `docs/`-kansioon.
 | `scripts/` | Provider-skriptit: `report-status.sh`, `publish-git-pages.sh`, `ci-validate.sh` |
 | `.gitea/scripts/` | **Consumer-skriptit**: `bats-coverage.sh`, `bats-report.sh` |
 | `docs/` | Arkkitehtuuri, ADRt (0004–0008) |
+| `skills/consumer-pipelines/` | Consumer-pipeline-standardit — AI:n pakottavat säännöt consumer-CI:lle |
 | `docs/adr/` | Architecture Decision Records |
 | `git-pages/` | Raporttien hostaus (Helm-chartti) |
 | `tests/` | Bats-testit skripteille |
@@ -1,446 +0,0 @@
-# Consumer Guide — Kirjaston käyttöönotto
-
-> Anna tämä dokumentti AI:lle kun haluat ottaa `gitea-ci-library`:n käyttöön
-> uudessa projektissa tai muokata olemassa olevia pipelineja.
-
---
-
-## Rakenneperiaate
-
-**Pipeline-tiedostot (`ci-feature.yml`, `ci-main.yml`) eivät saa sisältää
-varsinaista logiikkaa.** Ne ovat puhtaita reitittimiä: pelkkiä `uses:`-kutsuja
-`if`- ja `needs`-ehdoilla. Kaikki testien ajaminen, buildaus ja raportointi
-kuuluu omiin `workflow_call`-tiedostoihinsa.
-
-```
-ci-unit-tests.yml     ← testien ajaminen (varsinainen logiikka)
-ci-acc-tests.yml      ← hyväksymätestit (varsinainen logiikka)
-ci-feature.yml        ← reititin: load-config → test-workflow't → summary
-ci-main.yml           ← reititin: load-config → check-version → testit → build → summary
-```
-
-Provider tarjoaa 3 reusable workflow'ta ja joukon skriptejä.
-Consumer omistaa orkestroinnin: mitä palikoita käytetään, missä järjestyksessä,
-millä branch-ehdoilla. Consumer ei kopioi providerin koodia — se viittaa
-`uses:`-direktiivillä.
-
---
-
-## Vaihe 1: Konfiguraatiotiedosto
-
-Luo `.gitea/workflows/gitea-env.conf`:
-
-```ini
-GITEA_API_URL=https://gitea.example.com
-GIT_PAGES_URL=https://reports.example.com
-```
-
-Jos buildaat Docker-kontteja, lisää:
-
-```ini
-DOCKER_REGISTRY=gitea.example.com/myorg
-DOCKER_IMAGE_NAME=my-service
-DOCKER_UI_URL=https://gitea.example.com/myorg/-/packages/container/my-service
-#DOCKERFILE=Dockerfile.platform   # valinnainen, oletus Dockerfile
-```
-
-Salaisuudet määritellään Gitean Settings → Secrets -näkymässä:
-
-| Secret | Pakollinen |
-|---|---|
-| `GITEA_TOKEN` | Aina |
-| `GIT_PAGES_PUBLISH_TOKEN` | Aina |
-| `DOCKER_USERNAME` | Vain jos buildaat kontteja (ei pakollinen kaikissa registryissä) |
-| `DOCKER_PASSWORD` | Vain jos buildaat kontteja |
-
---
-
-## Vaihe 2: Test-workflow't (varsinainen logiikka)
-
-Jokainen testityyppi omaan `workflow_call`-tiedostoonsa. Tässä esimerkki
-Maven-yksikkötesteistä. Luo `.gitea/workflows/ci-unit-tests.yml`:
-
-```yaml
-name: Unit Tests
-on:
-  workflow_call:
-    inputs:
-      env_json:
-        required: true
-        type: string
-    secrets:
-      GITEA_TOKEN:
-        required: true
-      GIT_PAGES_PUBLISH_TOKEN:
-        required: true
-
-env:
-  GITEA_API_URL: ${{ fromJson(inputs.env_json).GITEA_API_URL }}
-  GIT_PAGES_URL: ${{ fromJson(inputs.env_json).GIT_PAGES_URL }}
-  GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-  GIT_PAGES_PUBLISH_TOKEN: ${{ secrets.GIT_PAGES_PUBLISH_TOKEN }}
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    container: maven:3.9-eclipse-temurin-21
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/checkout@v4
-        with:
-          repository: org/gitea-ci-library
-          path: .ci
-
-      - name: Run tests
-        shell: bash
-        run: |
-          mvn test
-          EXIT=$?
-          echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
-          exit ${EXIT}
-
-      - name: Publish reports
-        if: always()
-        run: bash .ci/scripts/publish-git-pages.sh junit
-
-      - name: Report status
-        if: always()
-        shell: bash
-        run: |
-          if [ "${EXIT}" = "0" ]; then
-            bash .ci/scripts/report-status.sh success "Link to JUnit reports" unit-tests junit
-          else
-            bash .ci/scripts/report-status.sh failure "Link to JUnit reports" unit-tests junit
-          fi
-```
-
-Hyväksymätesteille vastaava tiedosto `ci-acc-tests.yml` (Cucumber, Playwright
-tms.), jossa oma `container:`, oma testikomento ja oma `suite`-nimi.
-
-**Tärkeää:** `mvn test` korvataan omalla testikomennolla. `container:` ja
-`publish-git-pages.sh`-suite ovat projektikohtaisia. Muu runko pysyy samana.
-
---
-
-## Vaihe 3: Feature-haaran CI (puhdas reititin)
-
-Luo `.gitea/workflows/ci-feature.yml`. **Ei sisällä yhtään `run:`-steppiä**
-— pelkkiä `uses:`-kutsuja:
-
-```yaml
-name: CI Feature
-on:
-  push:
-    branches-ignore:
-      - main
-  workflow_dispatch:
-
-jobs:
-  load-config:
-    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1
-    secrets: inherit
-    with:
-      config_path: .gitea/workflows/gitea-env.conf
-
-  unit-tests:
-    needs: [load-config]
-    uses: ./.gitea/workflows/ci-unit-tests.yml@main
-    secrets: inherit
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-
-  acc-tests:
-    needs: [load-config]
-    uses: ./.gitea/workflows/ci-acc-tests.yml@main
-    secrets: inherit
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-
-  report-summary:
-    needs: [load-config, unit-tests, acc-tests]
-    if: always()
-    uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@v1
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-      suites: junit cucumber
-```
-
---
-
-## Vaihe 4: Main-haaran CI (puhdas reititin)
-
-Luo `.gitea/workflows/ci-main.yml`. **Ei sisällä yhtään `run:`-steppiä**:
-
-```yaml
-name: CI Main
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-jobs:
-  load-config:
-    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@v1
-    secrets: inherit
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-
-  unit-tests:
-    needs: [load-config, check-version]
-    if: needs.check-version.outputs.artifact_exists != 'true'
-    uses: ./.gitea/workflows/ci-unit-tests.yml@main
-    secrets: inherit
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-
-  acc-tests:
-    needs: [load-config, check-version]
-    if: needs.check-version.outputs.artifact_exists != 'true'
-    uses: ./.gitea/workflows/ci-acc-tests.yml@main
-    secrets: inherit
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-
-  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@v1
-    secrets: inherit
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-      version: ${{ needs.check-version.outputs.version }}
-
-  report-summary:
-    needs: [load-config, unit-tests, acc-tests]
-    if: always()
-    uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@v1
-    with:
-      env_json: ${{ needs.load-config.outputs.env_json }}
-      suites: junit cucumber
-```
-
-Mihin kiinnittää huomiota:
- `check-version` on **idempotentti** — jos commitilla on jo tagi, kaikki
-  sen jälkeiset jobit skipataan (`if: artifact_exists != 'true'`)
- `needs`-ketju takaa järjestyksen ja virheiden propagointin
- Artifakti voi olla **mitä tahansa** — `docker-build-push.yml` on yksi
-  esimerkki. Voit korvata sen Maven-deploylla, npm-publishilla, tai millä
-  tahansa omalla build-workflow'lla. Rajapinta on `version`-input.
-
---
-
-## Versionhallinta
-
-`check-version.yml` lukee version automaattisesti prioriteettijärjestyksessä:
-
-| # | Lähde | Formaatti | Esimerkki |
-|---|---|---|---|
-| 1 | `VERSION`-tiedosto | Plain text | `0.2` |
-| 2 | `package.json` | `.version` | `"version": "0.2.0"` |
-| 3 | `pom.xml` | `<version>` | `<version>0.2.0</version>` |
-
-`major.minor` otetaan tästä. Patch (kolmas numero) lasketaan automaattisesti
-git-tageista. Esim. jos `VERSION` on `0.2` ja tagit ovat `0.2.0`, `0.2.1`,
-niin seuraava on `0.2.2`.
-
---
-
-## Testien lisääminen — oma työkalu
-
-Kopioi `ci-unit-tests.yml`:n rakenne uudelle testityypille ja muuta:
- `container:` — oma testikonttisi
- Testikomento — oma testityökalusi (`npm test`, `pytest`, `go test`, ...)
- `publish-git-pages.sh <suite>` — oma suite-nimi
- `report-status.sh ... <context> <suite>` — oma uniikki konteksti
-
-Lisää uusi jobi reititintiedostoihin (`ci-feature.yml`, `ci-main.yml`)
-samalla `uses:`-kaavalla.
-
-Testijobit ajetaan rinnakkain — ne kaikki `needs: [load-config]` ilman
-keskinäisiä riippuvuuksia.
-
-### Tärkeimmät säännöt
-
-1. **Exit-koodi aina ylös:**
-   ```bash
-   run-tests
-   EXIT=$?
-   echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
-   exit ${EXIT}
-   ```
-
-2. **Ei pipeä testikomennon perään.** `command | tee file` syö exit-koodin.
-   Käytä `command > file 2>&1` jos haluat logit talteen.
-
-3. **Status vain jos on raportti.** Testijobit käyttävät commit-status API:a
-   raporttilinkin takia. Tool-jobit luottavat Gitean natiiviin job-statukseen.
-
-4. **`if: always()`** publish- ja status-stepeissä — raportti julkaistaan
-   ja status asetetaan vaikka testit feilaisivat.
-
-### Raporttien generointi
-
-`publish-git-pages.sh <suite>` odottaa hakemiston `reports/${SHA8}/<suite>/`
-olevan olemassa. Sen sisältö sellaisenaan julkaistaan git-pagesiin.
-`report-status.sh` linkittää statuksen suoraan tähän hakemistoon — selain
-avaa sieltä `index.html`:n.
-
-Test-workflow'n vastuulla on tuottaa raportit oikeaan polkuun. Kaksi
-tyypillistä patternia:
-
-**Pattern 1: Yksi raporttitiedosto (Cucumber)**
-
-Testityökalu tuottaa suoraan HTML-raportin. Yksinkertaisin tapaus:
-
-```bash
-mkdir -p "reports/${GITHUB_SHA:0:8}/cucumber"
-npx cucumber-js \
-  --format html:"reports/${GITHUB_SHA:0:8}/cucumber/index.html"
-```
-
-**Pattern 2: Monta raporttitiedostoa (Bats + coverage)**
-
-Eri työkalut tuottavat eri tiedostoja. Generoi `index.html` joka linkittää
-ne yhteen:
-
-```
-reports/${SHA8}/bats/
-  ├── index.html          ← generoitu: linkit alla oleviin
-  ├── results.txt         ← bats-testien stdout
-  ├── coverage/           ← bashcov-coverage HTML
-  │   └── index.html
-  └── ...
-```
-
-```bash
-mkdir -p "reports/${GITHUB_SHA:0:8}/bats"
-
-# Aja testit → results.txt
-bats tests/ > "reports/${GITHUB_SHA:0:8}/bats/results.txt" 2>&1
-
-# Generoi coverage → coverage-hakemisto
-bashcov -- bats tests/
-
-# Generoi index.html joka linkittää kaikkiin raportteihin
-cat > "reports/${GITHUB_SHA:0:8}/bats/index.html" <<'EOF'
-<!DOCTYPE html>
-<html><body>
-<h1>Bats Test Reports</h1>
-<ul>
-  <li><a href="results.txt">Test results (raw)</a></li>
-  <li><a href="coverage/index.html">Code coverage</a></li>
-</ul>
-</body></html>
-EOF
-```
-
-Yhteistä molemmille: `publish-git-pages.sh <suite>`-kutsun jälkeen raportit
-ovat julkisesti selailtavissa. `report-status.sh`-kutsu `suite`-parametrilla
-linkittää commit-statuksen suoraan `index.html`:ään.
-
-Jos testit feilasivat, raportti generoidaan silti — se kertoo MITKÄ testit
-feilasivat. Siksi publish- ja status-stepit käyttävät `if: always()`.
-
---
-
-## Branch protection (PR-gate)
-
-Gitean Settings → Branches → Add Rule:
-
- **Branch:** `main`
- **Enable Require Status Checks:** päälle
- **Status checks:** valitse `unit-tests`, `acc-tests`
-
---
-
-## Raporttien koonti (Gitea 1.27+)
-
-Kun Gitea päivittyy versioon 1.27, `GITHUB_STEP_SUMMARY`-tuki mahdollistaa
-raporttilinkkien koontinäkymän suoraan Gitea UI:ssa. `report-summary`-jobi
-on mukana molemmissa reititinesimerkeissä yllä — forward-compatibeli, ei
-hajota vanhemmilla versioilla.
-
---
-
-## Provider-rajapinnat — referenssi
-
-### Workflowt
-
-| Workflow | Käyttötarkoitus |
-|---|---|
-| `config-provider.yml` | Lataa + validoi `.conf`, tuottaa `env_json` |
-| `check-version.yml` | Tarkistaa onko commit buildattu, laskee version |
-| `docker-build-push.yml` | Buildaa + puskea Docker-imagen, tagittaa |
-| `report-summary.yml` | `GITHUB_STEP_SUMMARY`-taulukko raporttilinkeillä |
-
-### Skriptit (kutsutaan `.ci/scripts/`-polun kautta)
-
-| Skripti | Käyttötarkoitus |
-|---|---|
-| `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ä.