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

AI Context: Gitea Actions CI -kirjasto

Updated: 2026-06-19 (provider/consumer dual role, Project Skills -aktivointi)

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- ja consumer-kirjasto: reusable workflowt, scriptit, ADRt, dokumentaatio, ja consumer-esimerkit (dogfood). 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/ci-container-build-push.yml	Provider: buildaa + puskea CI-työkalukontin
.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)
skills/consumer-pipelines/	Consumer-pipeline-standardit (ks. Project Skills). Koskee vain consumer-puolta
skills/ci-container-build/	CI-kontin build-workflow'n template (ks. Project Skills)
docs/adr/	Architecture Decision Records
git-pages/	Raporttien hostaus (Helm-chartti)
tests/	Bats-testit skripteille

Provider workflowt (6 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.
ci-container-build-push.yml	env_json, dockerfile_path, image_name, tag	—	Buildaa CI-työkalukontin, puskea rekisteriin. Ei versiointia eikä git-tägäystä.
report-summary.yml	env_json, suites	—	Generoi GITHUB_STEP_SUMMARY-taulukon raporttilinkeillä (Gitea 1.27+)
helm-build-push.yml	env_json, version	—	Pakkaa + puskea Helm chartin OCI-registryyn, tagittaa commitin. Tekninen velka: asentaa node.js:n runtime-vaiheessa (apk add --no-cache nodejs ennen checkouttia) koska alpine/helm-kontissa ei ole nodea. Rikkoo Offline Container -periaatetta. Ratkaistaan myöhemmin: proper multi-tool CI-kontti (helm + nodejs + git) docker hubiin. Ei consumerin ongelma.

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

Provider & Consumer Dual Role

Tämä repo on yhtä aikaa sekä provider että consumer. Eri puolilla on eri säännöt:

• Provider-puoli: .gitea/workflows/*.yml (pl. example-*), scripts/ — reusable workflowt joita muut projektit kutsuvat. Saa käyttää docker run -komentoja (esim. docker-build-push.yml). Consumer-pipeline-standardit (skills/consumer-pipelines/) eivät koske provideria.
• Consumer-puoli: .gitea/workflows/example-*, .gitea/scripts/ — tämän repon oma CI (dogfood), toimii consumer-esimerkkinä. Käyttää @main-refiä provider-viittauksissa (sama repo). Noudattaa skills/consumer-pipelines/-sääntöjä.
• Ulkoiset consumerit käyttävät @v1-tagia provider-viittauksissa.

Project Skills (skills/)

Tämä projekti sisältää omia .ai/skills/-järjestelmästä riippumattomia skillejä skills/-kansiossa. Jokainen alihakemisto sisältää SKILL.md:n jossa on activation-gate-kenttä.

Sääntö: Uuden tehtävän alussa skannaa skills/*/SKILL.md ja arvioi jokaisen activation-gate annettua tehtävää vasten. Jos gate matchaa, lataa skill aktiiviseksi ohjeeksi ennen toimenpiteitä.

Skill	Gate	Kuvaus
skills/consumer-pipelines/	Consumer-pipeline-muutokset	Consumer-pipeline-standardit: reitittimen puhtaus, exit-koodi, konttipolitiikka, raportointi, nimeäminen. Koskee vain consumer-puolta.
skills/ci-container-build/	CI-kontin build	CI-kontin build-workflown template ja Dockerfile-ohjeet

Key Technical Decisions

• Provider & Consumer -malli: Tämä repo on sekä provider että consumer. Provider-workflowt reusableja muille, example-*-tiedostot tämän repon oma consumer-CI (dogfood). 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)