feat: implement quality-gate and publish-artifact pipelines

- Rename build-feature.yml → quality-gate.yml (merge-portti) - Create build_publish-artifact.yml: check → qg → build → push → tag - Add minimal Dockerfile for dogfood container build - Simplify quality-gate.yml cucumber job (remove prepare step, TOOL_OK) - Standardize test scripts in package.json for Docker-based local + CI runs - Update ci.yml: main branch uses build_publish-artifact.yml - Update docs/workflows.md: feature section rewritten with provider model - Add .gitignore entries for coverage/ and reports/
2026-06-14 05:43:15 +03:00
parent 1128545d6b
commit 23874f59b6
7 changed files with 389 additions and 141 deletions
@@ -1,8 +1,7 @@
 # Reusable workflowt

-> ⚠️ **POC-vaihe.** Tämä dokumentti kuvaa suunniteltuja workflow'ta
-> (ci-feature, ci-master, deploy, test). POCissa on toteutettu
-> `build-feature.yml`. Uudelleenkirjoitus odottaa.
+> ⚠️ **POC-vaihe.** Toteutettu: `quality-gate.yml`. Suunnitteilla:
+> `ci-master.yml`, `deploy.yml`, `test.yml`.

 ---

@@ -16,136 +15,271 @@ Kaikki workflowt:

 ---

-## `ci-feature.yml` — Feature-branch
+## `quality-gate.yml` — Merge-portti

-**Trigger:** `push` mihin tahansa branchiin paitsi `master`
+**Trigger:** `workflow_call` — consumer kutsuu `uses:`-direktiivillä

-**Elinkaari:**
+**Rooli:** Laatuportti, joka ajetaan branch protection -sääntönä ennen PR:n
+sulkemista mainiin. Pipeline on ajettava (`run > 1`) eikä yhtään jobia
+saa failata.

-```
-start → unit-test → code-coverage → html-reports → end
-```
+**Provider-Consumer-malli (ADR 0005):** Provider tarjoaa orkestroinnin
+(validointi, raporttien julkaisu, commit-status). Consumer omistaa
+pipeline-stepit — valitsee testityökalunsa, mahdolliset laatu- ja
+tietoturva-analyy sit sekä niiden järjestyksen. Alla oleva esimerkki
+kuvaa tyypillistä Java-mikropalvelua Mavenilla; consumer korvaa nämä
+omalla tekniikkapinollaan.

-### Inputs
+### Inputs (providerin rajapinta)

-| Parametri | Pakollinen | Kuvaus |
-|-----------|------------|--------|
-| `config-file` | Kyllä | Polku `ci-flow-values.yaml`:aan (yleensä `ci-flow-values.yaml`) |
-| `containers` | Ei | Kuvaus konteista: avain = nimi, arvo = image. Steppi valitsee missä kontissa ajaa. |
+| Parametri | Pakollinen | Tyyppi | Kuvaus |
+|-----------|------------|--------|--------|
+| `env_json` | Kyllä | string | JSON-muotoiset ympäristömuuttujat (`GITEA_API_URL`, `GIT_PAGES_URL`) |
+| `*` | — | — | Consumer lisää omat parametrinsa (`maven-image`, `docker-image`, jne.) |

-### Steppi-kaavio
+### Secrets
+
+| Secret | Pakollinen | Kuvaus |
+|--------|------------|--------|
+| `GITEA_TOKEN` | Kyllä | Gitea API-kutsuihin (commit-status) |
+| `GIT_PAGES_PUBLISH_TOKEN` | Kyllä | Raporttien julkaisuun git-pagesiin |
+
+### Steppi-kaavio (Java-esimerkki)

 ```mermaid
 %%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
 flowchart TD
-    START(["checkout + start
-    POST INPROGRESS"]) --> UNIT["unit-test
-    aja testit, generoi raportit"]
-    UNIT --> COV["code-coverage
-    jacoco / vastaava"]
-    COV --> HTML["publish-reports
-    vie raportit git-pagesiin"]
-    HTML --> END(["end
-    POST lopullinen status"])
+    VAL["validate
+    provider: tarkista
+    CI-konfiguraatio"] --> TEST["test
+    consumer: mvn test
+    → testiraportit + coverage"]

-    FAIL("fail") -. "catch" .-> END
+    VAL --> AI_SCAN["ai-scan \[optional\]
+    consumer: tietoturva-
+    tai laatu-skannaus"]

-    style START fill:#2563eb,color:#ffffff
-    style UNIT fill:#059669,color:#ffffff
-    style COV fill:#059669,color:#ffffff
-    style HTML fill:#7c3aed,color:#ffffff
-    style END fill:#2563eb,color:#ffffff
+    TEST --> SONAR["sonarqube \[optional\]
+    consumer: mvn sonar:sonar
+    → laatupoikkeamat"]
+    TEST --> PUB["publish-reports
+    provider: vie raportit
+    git-pagesiin"]
+
+    SONAR --> PUB
+    AI_SCAN --> PUB
+
+    PUB --> STATUS["commit-status
+    provider: aseta status
+    linkillä raporttiin"]
+
+    FAIL("fail") -. "if: always()" .-> PUB
+
+    style VAL fill:#2563eb,color:#ffffff
+    style TEST fill:#059669,color:#ffffff
+    style SONAR fill:#7c3aed,color:#ffffff
+    style AI_SCAN fill:#7c3aed,color:#ffffff
+    style PUB fill:#0891b2,color:#ffffff
+    style STATUS fill:#f59e0b,color:#111827
    style FAIL fill:#dc2626,color:#ffffff
    linkStyle default stroke:#9ca3af,stroke-width:3px
 ```

+Consumerin omat stepit (test, sonarqube, ai-scan) ovat esimerkki.
+Vastaava rakenne toimii millä tahansa kielellä tai työkalulla.
+
+### Optionaaliset laatu- ja tietoturvaskannaukset
+
+Consumer voi lisätä pipelineen omia skannaussteppejä testien rinnalle.
+Nämä ajetaan rinnakkain `validate`-vaiheen jälkeen ja syöttävät
+raporttinsa providerin `publish-reports`-palveluun. Jokainen skannaus
+on oma Gitea Actions -jobinsa.
+
+```mermaid
+%%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
+flowchart LR
+    VAL["validate"] --> SAST["sast
+    semgrep / codeql"]
+    VAL --> SCA["sca
+    snyk / owasp dc"]
+    VAL --> SECRETS["secret-scan
+    gitleaks"]
+    VAL --> LICENSE["license
+    fossa / scancode"]
+    VAL --> AI_REVIEW["ai-review
+    code quality"]
+
+    SAST --> PUB
+    SCA --> PUB
+    SECRETS --> PUB
+    LICENSE --> PUB
+    AI_REVIEW --> PUB
+
+    PUB["publish-reports + commit-status"]
+
+    style VAL fill:#2563eb,color:#ffffff
+    style SAST fill:#7c3aed,color:#ffffff
+    style SCA fill:#7c3aed,color:#ffffff
+    style SECRETS fill:#7c3aed,color:#ffffff
+    style LICENSE fill:#7c3aed,color:#ffffff
+    style AI_REVIEW fill:#7c3aed,color:#ffffff
+    style PUB fill:#0891b2,color:#ffffff
+    linkStyle default stroke:#9ca3af,stroke-width:3px
+```
+
+| Kategoria | Esimerkki | Kuvaus |
+|-----------|-----------|--------|
+| **SAST** | Semgrep, CodeQL | Staattinen analyysi — bugit ja haavoittuvuudet koodista |
+| **SCA** | Snyk, OWASP Dependency-Check | Riippuvuuksien tunnetut haavoittuvuudet |
+| **Secret scan** | Gitleaks, TruffleHog | API-avaimet, tokenit ja salasanat repossa |
+| **Lisenssit** | FOSSA, ScanCode | Riippuvuuksien lisenssien yhteensopivuus |
+| **AI review** | — | Automaattinen koodikatselmointi |
+
 ### Error handling

-Workflow käyttää Gitea Actionsin natiivia `jobs.<id>.continue-on-error` ja `if: failure()` -ehtoja. Ei erillistä `fail(e)`-kutsua kuten Jenkinsissä. Epäonnistunut steppi asettaa statuksen `failure` ja jatkaa `end`-steppiin, joka raportoi lopullisen statuksen.
+Providerin julkaisu- ja status-stepit käyttävät `if: always()`-ehtoa,
+jotta raportit ja commit-status päivittyvät myös failaavista ajoista.
+Consumerin omat stepit voivat vapaasti päättää `continue-on-error`- tai
+`if: failure()`-logiikastaan. Provider ei määrittele virheidenkäsittelyä
+consumerin pipelineen.

---
+### Merge-portti

-## `ci-master.yml` — Master / release-branch
+Branch protection -säännössä Giteassa vaaditaan ennen PR:n sulkemista:
+- **Pipeline on ajettu** (`run > 1`, ei "never run" -tila)
+- **Kaikki commit-statukset vihreitä** — validate, testit, laatuportit
+- Jos joku steppi failaa, status asettuu `failure`-tilaan ja PR:n
+  sulkeminen estyy

-**Trigger:** `push` `master`-branchiin tai `workflow_dispatch`
+### Optionaalinen PR-ympäristö (preview app)
+
+Consumer voi halutessaan buildata kontin ja deployata sen väliaikaiseen
+PR-ympäristöön. Tämä on optionaalinen continuation-haara, joka
+aktivoituu ehdolla:
+
+- PR:ssä on tietty label (esim. `preview`)
+- Commit message sisältää triggerisanan (esim. `[preview]`)

 **Elinkaari:**

-```
-start → isContainerBuilt? ──kyllä──→ continueToTestFlow
-       │
-       ei
-       ↓
-unit-test → quality-gate → build-jar → build-docker → push-docker → tag-commit → continueToTestFlow → end
+```mermaid
+%%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
+flowchart LR
+    QG["quality-gate
+    testit + skannaukset
+    ok"] --> BUILD["build-container
+    tag: pr-42"]
+    BUILD --> DEPLOY["deploy-pr-env
+    väliaikainen ympäristö"]
+
+    DEPLOY --> STATUS["commit-status
+    linkki PR-ympäristöön"]
+
+    PR_CLOSE["PR merged / closed"] --> CLEANUP["cleanup-pr-env
+    tuhoa ympäristö"]
+
+    style QG fill:#059669,color:#ffffff
+    style BUILD fill:#0891b2,color:#ffffff
+    style DEPLOY fill:#7c3aed,color:#ffffff
+    style STATUS fill:#f59e0b,color:#111827
+    style PR_CLOSE fill:#dc2626,color:#ffffff
+    style CLEANUP fill:#dc2626,color:#ffffff
+    linkStyle default stroke:#9ca3af,stroke-width:3px
 ```

-### Inputs
+1. Quality-gate läpäisty (testit + skannaukset ok)
+2. Buildaa kontti, tagi sisältää PR-numeron (`pr-42`)
+3. Deployaa PR-ympäristöön (preview/review app)
+4. Asettaa commit-statuksen linkillä ympäristöön
+5. **PR:n sulkeutuessa** (merge/close): cleanup-job tuhoaa ympäristön

-| Parametri | Pakollinen | Kuvaus |
-|-----------|------------|--------|
-| `config-file` | Kyllä | Polku `ci-flow-values.yaml`:aan |
-| `containers` | Ei | Kuvaus konteista: avain = nimi, arvo = image |
+Tämä on **consumerin vastuulla** — provider tarjoaa tarvittavat
+skriptit (`publish-git-pages.sh`, `report-status.sh`), mutta
+trigger-ehto, kontin buildaus ja ympäristön hallinta kuuluvat
+consumerin pipelineen.

-### isContainerBuilt-check
+---

-```yaml
- name: Check if container already built
-  run: |
-    TAG=$(git tag --points-at HEAD | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
-    if [ -n "$TAG" ]; then
-      echo "container_already_built=true" >> $GITHUB_ENV
-      echo "container_version=$TAG" >> $GITHUB_ENV
-    fi
+## `ci-master.yml` — Main-branch build
+
+**Trigger:** `workflow_call` — kutsutaan main-branchiin pushattaessa
+
+**Rooli:** Buildaa artifaktin (kontti, JAR, npm-paketti tms.) ja julkaisee
+sen rekisteriin. Jos sama commit on jo buildattu (version tag on olemassa),
+build skipataan ja siirrytään suoraan test flow'hun.
+
+**Provider-Consumer-malli (ADR 0005):** Provider orkestroi idempotent
+build-logiikan (`isArtifactBuilt`-tarkistus), mutta consumer omistaa
+build-stepit — valitsee työkalut ja artifaktityypin.
+
+### isArtifactBuilt-check
+
+Ennen buildia tarkistetaan, onko tälle commitille jo olemassa versiotagi:
+
+```bash
+TAG=$(git tag --points-at HEAD | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+if [ -n "$TAG" ]; then
+  echo "artifact_already_built=true" >> $GITHUB_ENV
+  echo "artifact_version=$TAG" >> $GITHUB_ENV
+fi
 ```

-Jos `container_already_built == true`, build- ja push-steppit skipataan. Siirrytään suoraan `continueToTestFlow`:hun.
+Jos tagi löytyy, build- ja push-stepit skipataan. Committia vastaan on
+jo olemassa artifakti rekisterissä — uudelleenbuildaus aiheuttaisi
+versiokonflikteja ja tuhlaisi CI-aikaa.

 ### Steppi-kaavio

 ```mermaid
 %%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
 flowchart TD
-    START(["start"]) --> CHECK{"isContainerBuilt?
+    CHECK{"isArtifactBuilt?
    git tag --points-at HEAD"}
-    
-    CHECK -- "ei" --> UNIT["unit-test"]
-    UNIT --> SONAR["quality-gate
-    SonarQube"]
-    SONAR --> JAR["build-jar
-    ArtifactType.JAR"]
-    JAR --> DOCKER["build-docker
-    ArtifactType.DOCKER
-    + Docker-labelit"]
-    DOCKER --> PUSH["push-docker
-    ArtifactType.DOCKER"]
+
+    CHECK -- "ei" --> QG["quality-gate
+    testit + skannaukset"]
+    QG --> BUILD["build-artifact
+    consumer: docker build /
+    mvn package / npm build"]
+    BUILD --> PUSH["push registry
+    gitea packages /
+    docker registry"]
    PUSH --> TAG["tag-commit
    tagittaa commitin
-    versiolla"]
-    
-    CHECK -- "kyllä" --> CTF["continueToTestFlow"]
-    TAG --> CTF
-    CTF --> HTML["publish-reports
-    vie raportit git-pagesiin"]
-    HTML --> END(["end
-    lopullinen status"])
+    versiolla (esim. 1.2.3.${RUN})"]

-    FAIL("fail") -. "catch" .-> END
+    CHECK -- "kyllä" --> K8S["continueToTestFlow
+    (future: K8s-testit
+    test plan -mukaan)"]
+    TAG --> K8S
+
+    FAIL("fail") -. "quality-gate
+    ei läpäisty" .-> END
+
+    K8S --> END(["end
+    commit-status"])

-    style START fill:#2563eb,color:#ffffff
    style CHECK fill:#f59e0b,color:#111827
-    style UNIT fill:#059669,color:#ffffff
-    style SONAR fill:#7c3aed,color:#ffffff
-    style JAR fill:#0891b2,color:#ffffff
-    style DOCKER fill:#0891b2,color:#ffffff
+    style QG fill:#059669,color:#ffffff
+    style BUILD fill:#0891b2,color:#ffffff
    style PUSH fill:#dc2626,color:#ffffff
    style TAG fill:#f59e0b,color:#111827
-    style CTF fill:#f59e0b,color:#111827
-    style HTML fill:#7c3aed,color:#ffffff
-    style END fill:#2563eb,color:#ffffff
+    style K8S fill:#7c3aed,color:#ffffff
    style FAIL fill:#dc2626,color:#ffffff
+    style END fill:#2563eb,color:#ffffff
    linkStyle default stroke:#9ca3af,stroke-width:3px
 ```

+### Elinkaari
+
+1. **isArtifactBuilt?** — tarkista onko tagi olemassa
+2. **quality-gate** — jos ei tagia, aja `quality-gate.yml` (testit, skannaukset)
+3. **build-artifact** — jos quality-gate läpäisty, buildaa artifakti
+4. **push registry** — julkaise rekisteriin (Gitea Packages, Docker registry, jne.)
+5. **tag-commit** — tagittaa commitin versiolla (esim. `1.2.3.<run_number>`)
+6. **continueToTestFlow** — *(future)* aja K8s-testit test plan -mukaan
+7. **commit-status** — aseta lopullinen status
+
 ### Concurrency

 ```yaml
@@ -154,7 +288,8 @@ concurrency:
  cancel-in-progress: false
 ```

-Vain yksi master-build kerrallaan per repo. Ei cancel-in-progress — käynnissä olevan buildin annetaan valmistua.
+Vain yksi master-build kerrallaan per repo. Ei cancel-in-progress —
+käynnissä olevan buildin annetaan valmistua.

 ---