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	Kyllä	Polku Chart.yaml-hakemistoon
extra_dependency_paths	Ei	Pilkulla erotellut polut subcharttien dependeinceille, joille ajetaan helm dependency update ennen päächartin buildia

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. Resolve extra subchart dependencies — helm dependency update jokaiselle extra_dependency_paths-polulle (vain jos input on annettu)
4. Package — helm dependency update + helm package versiolla $VERSION
5. Push OCI — helm push registryyn autentikoinnilla
6. 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.

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 ja .gitea/workflows/example-main.yml.

---