gitea-ci-library/docs/workflows.md

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

---

### `gitops-dispatch.yml` — GitOps-päivityksen dispatch

**Trigger:** `workflow_call`

**Inputit:**

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `env_json` | Kyllä | Konffi, josta luetaan `GITOPS_FILE`, `GITOPS_YQ_TPL`, `GITOPS_REPO`, `GIT_TAG_PREFIX` |
| `version` | Kyllä | Päivitettävä versio (check-version output) |
| `component` | Kyllä | `chart` tai `container` — tunniste summary-riville |

**Secretit:** `GITOPS_TOKEN`

**Outputit:** `summary` — pipe-formaatti: `{component}|{version}|{status}|{commit_sha}|{repo}`

**Steppi-kaavio:**
```
checkout → gitops-dispatch.sh → dispatch-workflow.sh → GITOPS_SUMMARY output
```

---

## 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 ───────────────────────────────────────────────────────┐
load-config-helm ───────────────────────────────────────────┐      │
                                                            │      │
check-version ←─────────────────────────────────────────────┘      │
  │                                                                │
  └→ bats + cucumber                                               │
       ├─ docker-build-push → gitops-container ─┐                  │
       └─ helm-build-push  → gitops-chart ──────┤                  │
                                                ├→ report-summary ←┘
       tag-maintenance ←────────────────────────┘
```

GitOps-jobit (`gitops-chart`, `gitops-container`) käyttävät
`gitops-dispatch.yml`-provider-workflowia. Kaksisuuntainen track:
dispatch-workflow.sh → GITOPS_COMMIT + GITOPS_SUMMARY.
Katso [skills/gitops-update/SKILL.md](../skills/gitops-update/SKILL.md).

### `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ä), `gitops` (optional JSON array)

**GitOps-tuki:** Jos `gitops` input on annettu (JSON array objekteilla
`component`, `version`, `status`, `commit`, `repo`), workflow lisää
GitOps-päivitystaulukon testiraporttien perään. Jokaiselle riville
muodostuu linkki GitOps-repon committiin.

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
(kaksisuuntainen track):

| Status | Mihin repo | Context | Linkki |
|---|---|---|---|
| ✅ | **GitOps-repo** | `source/{repo}` | Code-repon committiin |
| ✅ | **Code-repo** (dispatchin jälkeen) | `gitops/{repo} {RUN_ID}` | GitOps-repon committiin |

**Input-ympäristömuuttujat (ajetaan GitOps-repon workflow'ssa):**

| 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-repo slug |
| `GITEA_API_URL` | Kyllä | Gitean API-URL |
| `GITEA_TOKEN` | Kyllä | Gitea API-token (write GitOps-repoon) |
| `GITOPS_BRANCH` | Ei | GitOps-repon branch (oletus `main`) |
| `GIT_TAG_PREFIX` | Ei | Komponentin tag-prefix status-nimeämiseen |

**Commit-status (GitOps-repoon):**
| Kenttä | Formaatti | Esimerkki |
|--------|-----------|-----------|
| Context | `source/{repo}` | `source/gitea-ci-library` |
| Description | `Install to {env} {version}` | `Install to dev 0.2.0` |
| Target URL | Linkki code-repon committiin | `/org/repo/commit/sha` |

`{env}` parsitaan `INPUT_FILE`:stä (`dev/Chart.yaml` → `dev`).

**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. Jos muutoksia: commit + push `[skip ci]`, muuten status `— no change`
6. Asettaa commit-statuksen GitOps-repoon (source-konteksti, linkki code-repoon)

**Scriptiä ei ajeta code reposta.** Se ajaa GitOps-repon workflow'ssa.

### Code-repon commit-status (dispatchin jälkeen)

GitOps-päivityksen valmistuttua `dispatch-workflow.sh` tulostaa
`GITOPS_COMMIT=<sha>` (GitOps-repon commitin SHA). Code repo asettaa
oman commit-statusinsa linkillä GitOps-committiin:

| Kenttä | Formaatti | Esimerkki |
|--------|-----------|-----------|
| Context | `gitops/{repo} {RUN_ID}` | `gitops/gitea-ci-library 473` |
| Description | `Install to {env} {version}` | `Install to dev 0.2.0` |
| Target URL | Linkki GitOps-repon committiin | `/niko/gitea-ci-gitops-tests/commit/def456` |

### Loppuraportti (GITHUB_STEP_SUMMARY)

`report-summary.yml` (optio `gitops`-inputti) lisää GitOps-rivit
GITHUB_STEP_SUMMARYyn:

| Component | Version | Status | GitOps commit |
|---|---|---|---|
| helm | 0.2.0 | success | [link](...) |

Kokonainen esimerkki molemmista puolista: [skills/gitops-update/SKILL.md](../skills/gitops-update/SKILL.md)
ja [.gitea/workflows/example-main.yml](../.gitea/workflows/example-main.yml).

---