aloitus dokumentaatio

2026-06-08 06:04:49 +03:00
parent 92479ebb9c
commit 66e1c98a8c
9 changed files with 1547 additions and 0 deletions
@@ -0,0 +1,257 @@
+# Reusable workflowt
+
+> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Tämä dokumentti määrittelee jokaisen reusable workflow'n elinkaaren ja rajapinnan.
+
+---
+
+## Yhteiset konventiot
+
+Kaikki workflowt:
+- Käyttävät `concurrency:`-ryhmää estämään saman branchin rinnakkaiset ajot (vastaa Jenkins `disableConcurrentBuilds()`)
+- Lukevat konfiguraation `ci-flow-values.yaml`:sta
+- Raportoivat jokaisen vaiheen Gitea-commitin statukseen `report-status.sh`:lla
+- Käyttävät projektilta saatuja `with:`-parametreja konttien määrittelyyn (kirjasto ei pakota konttiversioita)
+
+---
+
+## `ci-feature.yml` — Feature-branch
+
+**Trigger:** `push` mihin tahansa branchiin paitsi `master`
+
+**Elinkaari:**
+
+```
+start → unit-test → code-coverage → html-reports → end
+```
+
+### Inputs
+
+| Parametri | Pakollinen | Kuvaus |
+|-----------|------------|--------|
+| `config-file` | Kyllä | Polku `ci-flow-values.yaml`:aan (yleensä `ci-flow-values.yaml`) |
+| `maven-image` | Ei | Maven-kontin image (esim. `maven:3.9-eclipse-temurin-21`) |
+| `node-image` | Ei | Node-kontin image (jos npm-projekti) |
+
+### Steppi-kaavio
+
+```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-html
+    pushaa raportit MinIO:hon
+    generoi index.html"]
+    HTML --> END(["end
+    POST lopullinen status"])
+
+    FAIL("fail") -. "catch" .-> END
+
+    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
+    style FAIL fill:#dc2626,color:#ffffff
+    linkStyle default stroke:#9ca3af,stroke-width:3px
+```
+
+### 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.
+
+---
+
+## `ci-master.yml` — Master / release-branch
+
+**Trigger:** `push` `master`-branchiin tai `workflow_dispatch`
+
+**Elinkaari:**
+
+```
+start → isContainerBuilt? ──kyllä──→ continueToTestFlow
+       │
+       ei
+       ↓
+unit-test → quality-gate → build-jar → build-docker → push-docker → tag-commit → continueToTestFlow → end
+```
+
+### Inputs
+
+| Parametri | Pakollinen | Kuvaus |
+|-----------|------------|--------|
+| `config-file` | Kyllä | Polku `ci-flow-values.yaml`:aan |
+| `maven-image` | Ei | Maven-kontti |
+| `docker-image` | Ei | Docker-in-Docker -image (esim. `docker:26-dind`) |
+
+### 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
+```
+
+Jos `container_already_built == true`, build- ja push-steppit skipataan. Siirrytään suoraan `continueToTestFlow`:hun.
+
+### Steppi-kaavio
+
+```mermaid
+%%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
+flowchart TD
+    START(["start"]) --> CHECK{"isContainerBuilt?
+    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"]
+    PUSH --> TAG["tag-commit
+    tagittaa commitin
+    versiolla"]
+    
+    CHECK -- "kyllä" --> CTF["continueToTestFlow"]
+    TAG --> CTF
+    CTF --> HTML["publish-html
+    pushaa Maven Site
+    MinIO:hon"]
+    HTML --> END(["end
+    lopullinen status"])
+
+    FAIL("fail") -. "catch" .-> END
+
+    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 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 FAIL fill:#dc2626,color:#ffffff
+    linkStyle default stroke:#9ca3af,stroke-width:3px
+```
+
+### Concurrency
+
+```yaml
+concurrency:
+  group: master-${{ github.repository }}
+  cancel-in-progress: false
+```
+
+Vain yksi master-build kerrallaan per repo. Ei cancel-in-progress — käynnissä olevan buildin annetaan valmistua.
+
+---
+
+## `deploy.yml` — GitOps-deployment
+
+**Trigger:** `workflow_dispatch` (aina dispatchataan toisesta workflow'sta)
+
+**Elinkaari:**
+
+```
+start → read-yaml → update-value → commit → push → report-cross-repo → end
+```
+
+### Inputs (dispatch-parametrit)
+
+| Parametri | Kuvaus |
+|-----------|--------|
+| `environment` | Ympäristön nimi (korvaa `{.environment}`) |
+| `version` | Uusi konttiversio |
+| `root_commit` | Mikropalvelun commit josta deploy käynnistyi |
+| `root_repo` | Mikropalvelun repo |
+| `root_build_url` | URL mikropalvelun buildiin |
+
+### Mitä deploy tekee
+
+1. Lukee `{projectFolder}/{fileName}` YAML-tiedoston (korvaa `{.environment}` → `environment`)
+2. Päivittää `{property}`-avaimen arvoksi `{version}`
+3. `git add`, `git commit -m "deploy {version} to {environment}"`
+4. `git push origin HEAD:master`
+5. Raportoi statuksen:
+   - Helm-repon committiin: **"from {root_commit}"**, URL → root-build
+   - Mikropalvelun committiin (`root_commit`): **"deployed to {environment}"**, URL → Helm-commit
+6. Palauttaa Helm-commitin hashin (`outputs.commit`)
+
+### Concurrency
+
+```yaml
+concurrency:
+  group: deploy-${{ github.repository }}-${{ inputs.environment }}
+  cancel-in-progress: false
+```
+
+---
+
+## `test.yml` — Test flow -steppi
+
+**Trigger:** `workflow_dispatch` (dispatchataan deploy-workflow'n jälkeen)
+
+**Elinkaari:**
+
+```
+start → version-check → run-tests → push-reports → report-cross-repo → end
+```
+
+### Inputs (dispatch-parametrit)
+
+| Parametri | Kuvaus |
+|-----------|--------|
+| `environment` | Testiympäristö |
+| `version` | Testattava konttiversio |
+| `tags` | Cucumber-tagit |
+| `versionApiUrl` | URL version tarkistukseen |
+| `versionCheckScript` | Polku version check -skriptiin |
+| `root_commit` | Mikropalvelun commit |
+| `root_repo` | Mikropalvelun repo |
+| `deploy_commit` | Helm-repon commit (deployattu versio) |
+| `deploy_repo` | Helm-repo |
+
+### Version check
+
+Ennen testejä varmistetaan, että ympäristössä pyörii oikea versio:
+
+```yaml
+- name: Check deployed version
+  if: inputs.versionCheckScript || inputs.versionApiUrl
+  run: |
+    if [ -n "${{ inputs.versionCheckScript }}" ]; then
+      bash "${{ inputs.versionCheckScript }}" "${{ inputs.versionApiUrl }}" "${{ inputs.version }}"
+    fi
+```
+
+Version check -skripti pollaa Fibonacci-backoffilla — ks. [config-model.md](config-model.md).
+
+### Cross-repo-raportointi
+
+Testien jälkeen raportoidaan kolmeen committiin:
+
+1. Testi-repon oma commit: testin status
+2. Mikropalvelun commit (`root_commit`): "testit OK/epäonnistui"
+3. Helm-repon commit (`deploy_commit`): "testattu v{version}"
+
+### Concurrency
+
+```yaml
+concurrency:
+  group: test-${{ inputs.environment }}
+  cancel-in-progress: false
+```