# Reusable workflowt

> Provider-workflowt tarjoavat ydintoiminnallisuuden. Consumer kokoaa ne
> haluamakseen pipelineksi. Esimerkkitoteutus: `example-*`-tiedostot.

---

## Yhteiset konventiot

Kaikki workflowt:
- Käyttävät `concurrency:`-ryhmää estämään saman branchin rinnakkaiset ajot
- Provider-workflowt lukevat konfiguraation inputtina (`env_json`)
- Statusraportointi: tool-jobit natiivilla, test-jobit API:lla raporttilinkin takia (ADR 0007)
- Exit-koodi aina ylös, ei pipeä (ADR 0008)

---

## Provider-workflowt

### `config-provider.yml` — Konfiguraation lataus ja validointi

**Trigger:** `workflow_call`

**Inputs:**

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `config_path` | Kyllä | Polku `.conf`-tiedostoon |

**Secrets:**

| Secret | Pakollinen | Kuvaus |
|--------|------------|--------|
| `GITEA_TOKEN` | Kyllä | Validointia varten |
| `GIT_PAGES_PUBLISH_TOKEN` | Kyllä | Validointia varten |

**Outputs:**

| Output | Kuvaus |
|--------|--------|
| `env_json` | JSON-muotoiset ympäristömuuttujat |
| `config_path` | Sama polku takaisin (DRY downstream-käyttöön) |

**Steppi-kaavio:**
```
checkout → validate CI config → parse conf to JSON
```

### `check-version.yml` — Version ja artifactin tarkistus

**Trigger:** `workflow_call` — käytetään vain main-haarassa

**Inputs:** `env_json`

**Outputs:** `artifact_exists` (true/false), `version` (string)

**Steppi-kaavio:**
```
checkout → laske versio package.json + git-tageista → output
```

### `docker-build-push.yml` — Docker build & push

**Trigger:** `workflow_call`

**Inputs:**

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `env_json` | Kyllä | Konffi `gitea-env.conf`:stä |
| `version` | Kyllä | Version string (check-version output) |

**`env_json`-avaimet:**

| Avain | Pakollinen | Kuvaus |
|-------|------------|--------|
| `DOCKER_REGISTRY` | Kyllä | Registry (esim. `gitea.app.keskikuja.site/niko`) |
| `DOCKER_IMAGE_NAME` | Kyllä | Kuvan nimi ilman registry-polkua |
| `DOCKER_UI_URL` | Ei | Registry UI -linkki raportointia varten |
| `DOCKERFILE` | Ei | Dockerfile-polku, oletus `Dockerfile` |
| `GITEA_API_URL` | Kyllä | Gitean API-URL |
| `GIT_TAG_PREFIX` | Ei | Tag-prefix (esim. `docker/`) |

**Secrets:** `GITEA_TOKEN`, `DOCKER_USERNAME`, `DOCKER_PASSWORD`

**Steppi-kaavio:**
```
build-push (build + push, labelit: commit+date) → tag-commit (git-tagin luonti)
```

**Huomio:** Ei käytä `container:`-direktiiviä — ajaa suoraan runnerilla,
joten `actions/checkout` toimii ilman node-asennuksia.

---

### `helm-build-push.yml` — Helm chart build & push

**Trigger:** `workflow_call`

**Inputs:**

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `env_json` | Kyllä | Konffi `gitea-env.conf`:stä |
| `version` | Kyllä | Version string (check-version output) |
| `chart_path` | Ei | Polku Chart.yaml-hakemistoon, oletus `.` |

**`env_json`-avaimet:**

| Avain | Pakollinen | Kuvaus |
|-------|------------|--------|
| `HELM_REGISTRY` | Kyllä | OCI-registry (esim. `gitea.app.keskikuja.site/niko`) |
| `HELM_UI_URL` | Ei | Registry UI -linkki raportointia varten |
| `GITEA_API_URL` | Kyllä | Gitean API-URL |
| `GIT_TAG_PREFIX` | Ei | Tag-prefix (esim. `helm/`) |

**Secrets:** `GITEA_TOKEN`, `HELM_USER`, `HELM_PASSWORD`

**Steppi-kaavio:**
```
build-push (helm package → helm push OCI) → tag-commit (git-tagin luonti)
```

**Steppien kuvaus `build-push`-jobissa:**
1. **Node.js-asennus** — `apk add --no-cache nodejs` (vaaditaan `actions/checkout`-actionia varten)
2. **Checkout** — sovellusrepo ja gitea-ci-library `.ci/`-polkuun
3. **Package** — `helm package` versiolla `$VERSION`
4. **Push OCI** — `helm push` registryyn autentikoinnilla
5. **Report status** — commit-status + UI-linkki

**Kompromissi:** Kontti `alpine/helm` ei sisällä node.js:ää, mutta
`actions/checkout@v4` on JavaScript-action ja vaatii sen. Siksi nodejs
asennetaan lennossa ennen checkouttia. Tämä vaatii internet-yhteyden
eikä toimi air gap -ympäristössä. Korvaa tarvittaessa custom-kontilla
(jossa helm + nodejs, ks. `skills/ci-container-build/SKILL.md`).

---

## Consumer-esimerkki (`example-*`)

### `example-feature.yml` — Feature-haaran CI

**Trigger:** `push` [branches-ignore: main]

```
load-config → bats + cucumber → report-summary (always)
```

### `example-main.yml` — Main-haaran CI

**Trigger:** `push` [branches: main]

```
load-config → check-version →
  [artifact exists] → done
  [no artifact]    → bats + cucumber → report-summary (always) → docker-build-push
```

### `example-bats-tests.yml` — Bats unit-testit

**Trigger:** `workflow_call`

Ajaa Bats-testit Docker-kontissa, generoi coveragen (`bashcov`), julkaisee
raportit git-pagesiin, asettaa commit-statuksen linkillä raporttiin.

### `example-cucumber-tests.yml` — Cucumber hyväksymätestit

**Trigger:** `workflow_call`

Ajaa Cucumber-testit Node-kontissa, julkaisee raportit git-pagesiin, asettaa
commit-statuksen linkillä raporttiin.

### `report-summary.yml` — Raporttien koontinäkymä

**Trigger:** `workflow_call` — ajetaan `if: always()` testien jälkeen

**Inputs:** `env_json`, `suites` (space-separated lista suite-nimistä)

Generoi Markdown-taulukon `GITHUB_STEP_SUMMARY`:yn kaikista julkaistuista
raporteista. Renderöityy HTML:ksi Gitea 1.27+ Summary-välilehdellä.
Forward-compatibeli — ei haittaa vanhemmilla Gitea-versioilla.

---

## Provider-skriptit

### `gitops-update.sh` — GitOps-version päivitys

**Riippuvuudet:** `yq`, `scripts/report-status.sh`, `git`

Päivittää GitOps-repon konfiguraatiotiedoston versionumeron `yq`:lla,
committaa muutoksen ja asettaa commit-statuksen molempiin repoihin.

**Input-ympäristömuuttujat:**

| Muuttuja | Pakollinen | Kuvaus |
|---|---|---|
| `INPUT_FILE` | Kyllä | Tiedosto GitOps-repossa (esim. `dev/Chart.yaml`) |
| `YQ_TPL` | Kyllä | `yq`-lauseke `{{VERSION}}`-placeholderilla |
| `VERSION` | Kyllä | Uusi versio (esim. `0.2.3`) |
| `SOURCE_REPO` | Kyllä | Lähdekoodirepo (esim. `org/app`) |
| `SOURCE_COMMIT` | Kyllä | Lähdekoodin commit-SHA |
| `GITOPS_REPO` | Kyllä | GitOps-konfiguraatiorepo (esim. `org/app-gitops`) |
| `GITEA_API_URL` | Kyllä | Gitean API-URL |
| `GITEA_TOKEN` | Kyllä | Gitea API-token |
| `GITOPS_BRANCH` | Ei | GitOps-repon branch (oletus `main`) |

**Steppikuvaus:**
1. Korvaa `YQ_TPL`:n `{{VERSION}}` versiolla
2. Muodostaa `CLONE_URL` tokenilla ja hostilla
3. Kloonaa GitOps-repon
4. Ajaa `yq eval -i` päivittääkseen tiedoston
5. Commit + push `[skip ci]`
6. Asettaa commit-statuksen: code-repoon (gitops-konteksti) ja GitOps-repoon (source-konteksti)

**Esimerkki dispatchistä:**
```yaml
- name: Update GitOps
  run: |
    export INPUT_FILE=dev/Chart.yaml
    export YQ_TPL='(.version) = "{{VERSION}}"'
    export VERSION=0.2.3
    export SOURCE_REPO=org/app
    export SOURCE_COMMIT=${{ github.sha }}
    export GITOPS_REPO=org/app-gitops
    bash scripts/gitops-update.sh
  env:
    GITEA_API_URL: ${{ vars.GITEA_API_URL }}
    GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
```

---