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

---

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

- 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 }}

---