gitea-ci-library/docs/ai-context.md

AI Context: Gitea Actions CI -kirjasto

Updated: 2026-06-15 (siivottu, provider/consumer-erottelu valmis)

Project Overview

Gitea Actions reusable workflow -kirjasto mikropalveluiden build-, testaus-, raportointi-, deployment- ja test flow -prosessien orkestrointiin. Korvaa ci-jenkins-library:n Gitea-natiivilla toteutuksella. Mikropalvelut käyttävät kirjastoa uses:-direktiivillä.

Monorepo: kaksi erillistä kokonaisuutta

1. Juuri (gitea-ci-library)

Provider-kirjasto: reusable workflowt, scriptit, ADRt, dokumentaatio. Consumer kutsuu provider-workflowta uses:-direktiivillä.

2. git-pages/ — oma kokonaisuus

Helm-chartti Codeberg git-pagesille. Täysin itsenäinen — oma dokumentaatio, omat tekniset valinnat, oma design-rationale. Kaikki git-pages-spesifi tieto kuuluu git-pages/docs/-alle, ei juuren docs/-kansioon.

Repository Structure

Path	Purpose
.gitea/workflows/config-provider.yml	Provider: lataa + validoi config-tiedoston, tuottaa env_json
.gitea/workflows/check-version.yml	Provider: tarkistaa onko commitille jo artifact, laskee version
.gitea/workflows/docker-build-push.yml	Provider: buildaa + puskea Docker-imagen, tagittaa commitin
.gitea/workflows/example-*	Consumer-esimerkki: tämän repon oma CI (dogfood)
scripts/	Provider-skriptit: report-status.sh, publish-git-pages.sh, ci-validate.sh
.gitea/scripts/	Consumer-skriptit: bats-coverage.sh, bats-report.sh
docs/	Arkkitehtuuri, ADRt (0004–0008)
docs/adr/	Architecture Decision Records
git-pages/	Raporttien hostaus (Helm-chartti)
tests/	Bats-testit skripteille

Provider workflowt (4 kpl)

Workflow	Input	Output	Kuvaus
config-provider.yml	config_path	env_json, config_path	Validoi ja jäsentää .conf → JSON. Sama kutsu hoitaa validoinnin.
check-version.yml	env_json	artifact_exists, version	Tarkistaa git-tagit ja package.json:n, laskee seuraavan version. Vain main-haarassa.
docker-build-push.yml	env_json, version	—	Buildaa Docker-imagen, puskea rekisteriin, tagittaa commitin.
report-summary.yml	env_json, suites	—	Generoi GITHUB_STEP_SUMMARY-taulukon raporttilinkeillä (Gitea 1.27+)

Example-tiedostot (consumer-referenssi)

Tiedosto	Laukaisin	Flow
example-feature.yml	push [ei main]	load-config → bats + cucumber → report-summary
example-main.yml	push [main]	load-config → check-version → bats + cucumber → report-summary → docker-build-push
example-bats-tests.yml	workflow_call	Unit-testit Batsilla, raportit git-pagesiin, status linkillä
example-cucumber-tests.yml	workflow_call	Hyväksymätestit Cucumberilla, raportit git-pagesiin, status linkillä
example-gitea-env.conf	—	KEY=VALUE config tälle repolle

Key Technical Decisions

• Provider & Consumer -malli: example-*-tiedostot ovat consumer-esimerkkejä, provider-workflowt reusableja. ADR 0005.
• Vain Gitea, vain reusable workflowt: ei custom actioneita, ei multi-platform
• Commit-status API vain raporttilinkeille: Tool-jobit luottavat natiiviin. Test-jobit käyttävät API:a koska se on ainoa tapa upottaa raporttilinkki. ADR 0004, 0007.
• Exit-koodi on ainoa onnistumisen mittari: Ei pipeä, ei tiedostoheuristiikkaa. ADR 0008.
• Raportit git-pagesissa: HTML selailtavissa, retention automaattinen
• GITHUB_STEP_SUMMARY: Summary-näkymä raporttilinkeille Gitea 1.27:ssä (forward-compat)

Common Commands

• Helm-asennus: helm upgrade --install git-pages ./git-pages -n <ns> -f <values>
• Julkaisu: bash scripts/publish-git-pages.sh <report-dir>
• Status: bash scripts/report-status.sh <state> <desc> <context> [suite] [url]

What NOT to Do

• Älä lisää tukea muille Git-alustoille
• Älä lisää Docker custom actioneita ilman pakottavaa syytä
• Älä kirjoita git-pages-spesifiä tietoa juuren docs/-kansioon
• Älä käytä commit-status API:a jollei ole raporttia linkitettäväksi (ADR 0007)
• Älä käytä pipeä run-komennon viimeisenä — se syö exit-koodin (ADR 0008)