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

name, description, activation-gate, category, impact

name	description	activation-gate	category	impact
consumer-pipelines	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.	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.	ci	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:

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.

- 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 Offline Container -vaatimus (DoD)

CI-kontin (ja kaikkien pipeline-konttien) on oltava täysin itseriittoisia:

Kontti ei lataa mitään pipeline-vaiheessa (workflow run -stepit) eikä kontin runtime-prosessissa (container: / docker run). Kaikki riippuvuudet pre-cachataan docker build -vaiheessa. Ainoa sallittu lataushetki on docker build.

Esimerkkejä rikkomuksista:

• apk add, apt-get install, npm install, go mod download, pip install pipeline-stepissä
• curl <url> | tar xz runtime-vaiheessa
• Node.js-konttikuva ilman nodea (joudutaan asentamaan lennossa)

4.2 Kielikohtainen pre-cache

Kun kontissa testataan kielikohtaista koodia, kaikki riippuvuudet on pre-cachattava Dockerfilessä, ei pipeline-stepissä:

Kieli	Pre-cache Dockerfilessä
Go	COPY go.mod go.sum ./ → RUN go mod download
Java/Maven	COPY pom.xml ./ → RUN mvn dependency:go-offline
Node	COPY package.json package-lock.json ./ → RUN npm ci --omit=dev
Python	COPY requirements.txt ./ → RUN pip install -r requirements.txt

Katso tarkat Dockerfile-esimerkit REFERENCE.md:stä.

4.3 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 — muuten checkout ei toimi ja pipeline failaa.

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):

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

Käyttö reitittimessä:

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):

HELM_REGISTRY: gitea.app.keskikuja.site/niko

Käyttö reitittimessä:

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

Vanhentunut käytäntö: Nykyinen helm-build-push.yml asentaa node.js:n lennossa apk add --no-cache nodejs ennen checkouttia — tämä rikkoo Offline Container -vaatimusta (4.1).

Korjaustoimenpide: Rakenna custom CI-kontti ci-container-build-skillillä jossa on helm + nodejs + git (katso pre-cache-esimerkit REFERENCE.md:stä), päivitä workflow'n container: image: osoittamaan omaan konttiin, ja poista runtime-apk.

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.