gitea-ci-library/skills/consumer-pipelines/SKILL.md

---
name: consumer-pipelines
description: |
  Creating or modifying consumer CI pipelines, .gitea/workflows/ files,
  reusable test workflows, monorepo CI configuration, or CI routing files
  (ci-feature.yml, ci-main.yml, ci-*.yml). Activates when the user asks to
  build, fix, or change consumer-side Gitea Actions pipelines that use
  gitea-ci-library providers.
activation-gate: |
  User mentions consumer pipelines, ci-feature.yml, ci-main.yml, test
  workflows, .gitea/workflows/ files, monorepo CI, routing files, or asks
  to create/modify CI pipelines on top of gitea-ci-library.
category: ci
impact: high
---

# Consumer Pipelines — Pipeline Standards

Säännöt joilla consumer-projektit rakentavat CI-pipelinejä `gitea-ci-library`-kirjaston päälle.
Nämä eivät ole provider-kirjaston sääntöjä — ne kuvaavat miten consumerin kuuluu käyttää kirjastoa oikein.

Katso tarkat mallipohjat ja esimerkit `REFERENCE.md`:stä.

## 1. Reitittimen puhtaus

Reitittimet (`ci-feature.yml`, `ci-main.yml`) eivät sisällä `run:`-steppejä. Ne koostuvat vain:

```yaml
uses:
needs:
if:
secrets: inherit
with:
  env_json:
  <parametrit>:
```

Jokainen job vastaa yhtä loogista testiä tai operaatiota. Reititin on orkestraattori — kaikki suorittava
logiikka on omassa `workflow_call`-tiedostossaan.

Katso täydellinen esimerkki `REFERENCE.md`:stä.

## 2. Yksi asia per tiedosto

Ei monoliittista `ci-tests.yml`. Jokainen testityyppi tai operaatio on oma `workflow_call`-tiedostonsa.

**Miksi:**
- Testit ajetaan rinnakkain (ei keinotekoisia riippuvuuksia)
- Yhden testin fail ei estä muita
- Testattavissa itsenäisesti `workflow_dispatch`:llä
- Diff näyttää heti mitä testiä muutettiin

## 3. Exit-koodin käsittely

`set -e` on oletuksena käytössä Gitea Actions -stepeissä — ensimmäinen feilaava komento pysäyttää stepin
ja exit-koodi välittyy natiivisti. Ylimääräistä `EXIT=$?` + `echo >> GITHUB_ENV` -käärettä ei tarvita.

```yaml
- name: Run tests
  shell: bash
  run: |
    <testikomento> > results.txt 2>&1
```

**Miksi ei pipeä (`| tee`):** `|` syö exit-koodin. Käytä redirectiä `>`.

**Yksi asia per step:** Älä koskaan niputa useaa komentoa samaan `run:`-blockiin. `bash -e` pysäyttää
koko stepin ensimmäisellä failaavalla komennolla, ja loput jäävät ajamatta. Sama pätee post-process-steppeihin.

## 4. Konttipolitiikka

1. **Julkiset registry-kontit kiinteällä versiolla** — `alpine/helm:3.19.0`, `node:22`, `maven:3.9-eclipse-temurin-21`.
   Toistettavuus ja turvallisuus eivät saa riippua ulkoisesta `latest`:sta.
2. **Projektin omat CI-kontit `latest`-tägillä** — buildattu `ci-container-build-<kontti>.yml`:llä.
   Kontin build-pipeline päivittää `latest`:n automaattisesti. Rebuild = käyttöönotto
   kaikissa pipelineissa ilman versioviittauksien päivittelyä.
3. **Ei koskaan `curl`-latauksia CI-ajon sisällä** — työkalujen asennus CI-stepeissä hidastaa,
   epäluotettavaa, ja vaikeuttaa toistettavuutta.
4. **Konttikuva hallitaan workflow'ssa, ei kutsujassa** — jos workflow vaatii tietyn
   konttikuvan, se määritellään oletuksena (`default:`) workflow'n inputissa.
   Kutsujan ei tarvitse tietää eikä välittää image-nimeä ellei halua ylikirjoittaa.

CI-kontin build-workflow'n template: `skills/ci-container-build/SKILL.md`.

### 4.1 CI-kontin ajaminen jobissa

Ainoa sallittu tapa on `container:`-direktiivi. `docker run` komennolla kontin
käynnistäminen stepin sisällä on anti-pattern.

Katso CI-kontin template `REFERENCE.md`:stä.

**Huomio `actions/checkout@v4`:stä:** `container:`-direktiivillä kaikki stepit
ajetaan kontin *sisällä* — myös `actions/checkout@v4`. Se on JavaScript-action
joka vaatii sekä `nodejs` että `git`. Varmista että CI-kontin Dockerfilessä on molemmat.

## 5. Raporttitasot

Testi tuottaa raportin `reports/<suite>/`-hakemistoon. Yksi `ci-report.sh`-kutsu hoitaa sekä
julkaisun että commit-statuksen.

### Taso 1: Ei jälkikäsittelyä

Kun testi tuottaa raportit suoraan (kuten `pytest --html` tai `cucumber-js --format html`):
- testi kirjoittaa `reports/<suite>/`-hakemistoon
- `ci-report.sh` julkaisee ja asettaa commit-statuksen

### Taso 2: Jälkikäsittely tarvitaan

Kun testi tuottaa raakadataa (stdout, coverage-tiedostot) joka pitää muuntaa tai siirtää
`reports/<suite>/`-hakemistoon. **Jokainen operaatio omassa stepissään** `if: always()`.

Tarkat YAML-mallit molemmista tasoista: `REFERENCE.md`.

**Subdir-sääntö:** Alihakemisto näkyy indexissä VAIN jos se sisältää `index.html`:n.

## 6. Nimeäminen

Tiedostonimet `.gitea/workflows/`-kansiossa noudattavat yhtenäistä rakennetta:

```
<komponentti>.ci-feature.yml                  ← feature-haaran reititin
<komponentti>.ci-main.yml                     ← main-haaran reititin
<komponentti>.<testityyppi>.yml               ← yksittäinen testi tai operaatio
<komponentti>.ci-container-build-<kontti>.yml ← CI-kontin build-workflow
<komponentti>.gitea-env.conf                  ← komponenttikohtainen konfiguraatio
```

Single repossa `<komponentti>` jätetään pois.
Monorepossa prefiksi pitää komponentin tiedostot yhdessä.

## 7. Artifact-kuri

Gitea Actionsin `upload-artifact` jättää pysyvän tiedoston. Artifakteja ei käytetä
`workflow_call`:ien väliseen datan siirtoon ellei se ole teknisesti välttämätöntä.

**Ensisijainen ratkaisu:** jokainen testi tuottaa tarvitsemansa datan itse. Ei
`upload-artifact` + `download-artifact` -riippuvuuksia.

## 8. Report-Summary — pakollinen jokaisen pipelinen lopuksi

Jokaisen reitittimen (oli se `ci-main.yml`, `ci-feature.yml` tai mikä tahansa) viimeinen job on `report-summary`.

**Säännöt:**
- `needs:` sisältää **kaikki edeltävät jobit** — summary odottaa että kaikki on valmis (onnistui tai ei)
- `if: always()` — ajetaan aina, vaikka pipeline olisi keskeytetty tai joku jobi failannut
- `suites:` on välilyönnein eroteltu lista suiten nimistä (esim. `bats cucumber`). Tyhjä merkkijono sallittu jos testisuiteja ei ole.
- Provider (`report-summary.yml`) hoitaa summaryn logiikan — reititin vain kutsuu

**Miksi aina:**
- Gitea 1.27+ näyttää `GITHUB_STEP_SUMMARY`:n Actions UI:ssa. Ilman summarya pipeline näyttää epätäydelliseltä.
- Summaryyn voidaan myöhemmin lisätä muutakin kuin testilinkkejä (build-artefaktit, deploy-tiedot).
- Yhtenäinen rakenne jokaisessa pipeline-parissa vähentää kysymyksiä.

YAML-malli: `REFERENCE.md`.

## 9. ADR-yhteenveto — consumerin kannalta oleelliset säännöt

### Reititin ei sisällä suorittavaa koodia (ADR 0010)

`ci-feature.yml` ja `ci-main.yml` koostuvat **vain** `uses:`, `needs:` ja `if:`-avainsanoista.
Ei `run:`-komentoja, ei inline-skriptejä, ei `actions/checkout`.

### Yksi steppi = yksi workflow_call-tiedosto

Jokainen job reitittimessä on oma `workflow_call`-tiedostonsa.
Ei kahta eri komentoa samassa workflow'ssa.

### Provider-versio on `@v1` (ADR 0009)

Kaikki provider-viittaukset käyttävät `@v1`-tagia. `@main` on vain providerin oman repon
sisäiseen dogfood-käyttöön. Breaking changet kielletty — `v1`-rajapinta on pysyvä.

### Paikalliset `uses:` eivät käytä refiä

Gitea act runner v1.0.8 muodostaa paikallisista `uses: ./.gitea/workflows/*.yml@main`-viittauksista
epävalidin git-refin `main@<sha>`.

Paikallisista `uses:`-direktiiveistä EI koskaan käytetä `@main`- tai muuta ref-päätettä:
- `uses: ./.gitea/workflows/chart.helm-lint.yml`  ← oikein
- `uses: ./.gitea/workflows/chart.helm-lint.yml@main` ← väärin

Ilman refiä runner käyttää workflow'ta triggeröivästä commitista.

### Exit-koodi on ainoa onnistumisen mittari (ADR 0008)

Ei pipeä (`|`) komennon perässä — se syö exit-koodin. Käytä redirectiä (`> file 2>&1`).

### Providerin checkout ei kuulu consumerille

Providerin scriptit haetaan `actions/checkout`-stepillä `.ci/`-polkuun.
Consumer ei kopioi eikä muokkaa providerin tiedostoja.

## 10. Build & Push -providerit

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

Buildaa ja pushee Docker-imagen OCI-registryyn. Ajaa suoraan runnerilla
(ei `container:`-direktiiviä), joten `actions/checkout` toimii natiivisti.

**`env_json`-avaimet (pakolliset):**

```yaml
DOCKER_REGISTRY: gitea.app.keskikuja.site/niko
DOCKER_IMAGE_NAME: my-app
```

**Käyttö reitittimessä:**

```yaml
docker-build-push:
  uses: OWNER/gitea-ci-library/.gitea/workflows/docker-build-push.yml@v1
  needs: [check-version]
  if: needs.check-version.outputs.artifact_exists == 'false'
  secrets: inherit
  with:
    env_json: ${{ needs.load-config.outputs.env_json }}
    version:  ${{ needs.check-version.outputs.version }}
```

Tarkka input/secret-lista: `docs/workflows.md`.

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

Pakkaa ja pushee Helm-chartin OCI-registryyn. Käyttää `alpine/helm`-konttia.

**`env_json`-avaimet (pakolliset):**

```yaml
HELM_REGISTRY: gitea.app.keskikuja.site/niko
```

**Käyttö reitittimessä:**

```yaml
helm-build-push:
  uses: OWNER/gitea-ci-library/.gitea/workflows/helm-build-push.yml@v1
  needs: [check-version]
  if: needs.check-version.outputs.artifact_exists == 'false'
  secrets: inherit
  with:
    env_json: ${{ needs.load-config.outputs.env_json }}
    version:  ${{ needs.check-version.outputs.version }}
    # chart_path: '.'  # oletus, vaihda jos Chart.yaml on alihakemistossa
```

**Node.js-kompromissi:** `actions/checkout@v4` on JavaScript-action.
Kontissa `alpine/helm` ei ole node.js:ää, joten se asennetaan lennossa
`apk add --no-cache nodejs` ennen checkouttia.

- Vaatii internet-yhteyden
- Ei toimi air gap -ympäristössä
- Korvaa tarvittaessa custom-kontilla (helm + nodejs):
  rakenna `ci-container-build`-skillillä ja päivitä workflow'n
  `container: image:` osoittamaan omaan konttiin

**Yksittäisten Helm-UI-linkkien raportointi:** `HELM_UI_URL` on
tarkoitettu yleiselle registry UI:lle — provider muodostaa linkin
`${HELM_UI_URL}/${CHART_NAME}/${VERSION}` automaattisesti.

Tarkka input/secret-lista: `docs/workflows.md`.