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

AI Context: Gitea Actions CI -kirjasto

Updated: 2026-06-12 (POC-vaihe, suunniteltu uudelleenkirjoitus)

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

POC on valmis: raporttien julkaisu git-pagesiin ja commit-status linkillä toimii.

Monorepo: kaksi erillistä kokonaisuutta

Tämä repo on käytännössä monorepo, jossa on kaksi itsenäistä osaa:

1. Juuri (gitea-ci-library)

Provider-kirjasto: reusable workflowt, scriptit, ADRt, dokumentaatio. Consumer kutsuu build-feature.yml-workflowa uses:-direktiivillä.

2. git-pages/ — oma kokonaisuus

Helm-chartti Codeberg git-pagesille. Täysin itsenäinen — oma dokumentaatio, omat tekniset valinnat, oma design-rationale. Kohdeltava kuten se olisi jo oma reponsa: kaikki git-pages-spesifi tieto kuuluu git-pages/docs/- alle, ei juuren docs/-kansioon.

Rajapinta juuren ja git-pagesin välillä

Ohut ja yksiselitteinen:

scripts/publish-git-pages.sh <report-dir>
  → PATCH tar osoitteeseen GIT_PAGES_URL
  → palauttaa BASE URL:n

git-pages tarjoaa:
  - HTTP endpoint (GET/PATCH/PUT)
  - retention (automaattinen)
  - TLS, BasicAuth (Traefik)

Juuri ei tiedä git-pagesin sisäisestä toiminnasta (storage v2, .index, blob-arkkitehtuuri). Git-pages ei tiedä workflowista, scripteistä tai provider-logiikasta.

Architecture (POC-tila)

• Provider & Consumer -malli: build-feature.yml on lukittu rajapinta. ADR 0005.
• Raporttien hostaus: git-pages Helm-chartilla (git-pages/), GIT_PAGES_URL määrittää perusosoitteen.
• Retention: sidecar samassa podissa, HTTP API localhost:3000, Gitea API branch-check.
• Commit-status: Gitea Actions näyttää automaattisesti. API vain custom-linkkiin. ADR 0004.
• Julkaisu: publish-git-pages.sh → PATCH tar git-pagesiin.

Repository Structure

Path	Purpose
.gitea/workflows/	Reusable workflowt (build-feature.yml, config-provider.yml)
scripts/	publish-git-pages.sh, report-status.sh, dispatch-workflow.sh
git-pages/	Oma kokonaisuus: Helm-chartti + docs + retention
docs/	Root-tason arkkitehtuuri, ADRt (0001–0005)
docs/adr/	Architecture Decision Records
tests/	Bats-testit skripteille
.gitea/workflows/ci.yml	Dogfood — kutsuu build-feature.yml:a

Tarkemmat git-pages-asiat: git-pages/docs/ (implementation-notes, architecture, design-rationale, secrets, tech-stack).

Key Technical Decisions

• Provider & Consumer: build-feature.yml lukittu rajapinta, muu koodi vapaasti muutettavissa
• Vain Gitea, vain reusable workflowt: ei custom actioneita, ei multi-platform
• Raportit git-pagesissa: HTML selailtavissa, retention automaattinen
• Git-pages omana kokonaisuutena: voi erottaa omaksi repokseen tulevaisuudessa

Tech Stack (POC)

• Runtime: Bash, curl, jq, python3 (retention whiteout)
• Alusta: Gitea Actions, Gitea act runner
• Hostaus: git-pages 0.9.1 (Codeberg), Traefik, cert-manager
• Integraatiot: Gitea REST API, Gitea Packages

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> <url> <context>

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 — kuuluu git-pages/docs/-alle
• Älä POSTaa commit-status APIin jokaiselle vaiheelle — natiivi riittää