gitea-ci-library/docs/workflows.md

# 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
```