--- 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: : ``` 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: | > 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-.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//`-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//`-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//`-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: ``` .ci-feature.yml ← feature-haaran reititin .ci-main.yml ← main-haaran reititin ..yml ← yksittäinen testi tai operaatio .ci-container-build-.yml ← CI-kontin build-workflow .gitea-env.conf ← komponenttikohtainen konfiguraatio ``` Single repossa `` 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@`. 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.