# AI Context: Gitea Actions CI -kirjasto

**Updated**: 2026-06-08

## 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ä ja konfiguroivat itsensä `ci-flow-values.yaml`:lla.

## Architecture
- 4 reusable workflow'ta: `ci-feature.yml`, `ci-master.yml`, `deploy.yml`, `test.yml`
- 4 jaettua bash-skriptiä (`scripts/`): `report-status.sh`, `dispatch-workflow.sh`, `push-reports.sh`, `tag-commit.sh`
- Raportit MinIO:ssa (S3 + static web), OIDC-autentikointi Traefikin kautta
- Cross-repo commit traceability Gitea REST API:n kautta
- `report-service/`-moduuli samassa repossa: raporttiskriptit, retention CronJob, index.html-generointi
- Normatiivinen arkkitehtuuri: `docs/architecture.md`, perustelut `docs/design-rationale.md`

## Repository Structure
| Path | Purpose |
|---|---|
| `.gitea/workflows/` | Reusable workflow -tiedostot (`ci-feature.yml`, `ci-master.yml`, `deploy.yml`, `test.yml`) |
| `scripts/` | Jaetut bash-skriptit |
| `report-service/` | Raporttipalvelun koodi (retention, indeksigenerointi) |
| `docs/` | Arkkitehtuuri-, vaatimus- ja konfiguraatiodokumentaatio |
| `docs/tickets/` | Toteutustiketit (0001–0012), yksi per feature-branch |
| `docs/test-plan/` | TDD-opas: 3-kerrosmalli, kehityslooppi, mock, kontekstikuratointi |
| `docs/test-plan/tdd-guide.md` | Testivetoisen kehityksen menetelmädokumentti |
| `tests/` | Bats-testit skripteille ja workflow-validointi |
| `tests/features/` | Cucumber `.feature`-tiedostot (yksi per tiketti, tägätty @mock/@real/@ticket-NNNN) |
| `tests/helpers/` | Jaettu mock-palvelin (Gitea API + MinIO) |
| `.gitea/workflows/ci.yml` | Kirjaston oma CI — dogfood (käyttää itse itseään) |

## Key Technical Decisions
- **Vain Gitea.** Ei multi-platform-tukea (GitLab, BitBucket, GitHub)
- **Ei omaa runtimea.** Reusable workflowt, ei Docker custom actioneita (ellei pakko)
- **Konfiguraatio repoon.** `ci-flow-values.yaml` projektin juuressa, infra-asetukset Gitea org secrets/variables
- **Vaiheittainen test flow.** Ei rinnakkaista suoritusta — deterministinen, debuggattava
- **Raportit MinIO:ssa.** Gitea artifact-järjestelmä ei tue HTML-selailtavuutta
- **Docker-rekisterit:** MVP:ssä vain Gitea Packages. Factory/adapter-pattern valmiina Artifactorylle/Nexukselle
- **MVP-scope:** `doNotDowngrade` ei mukana, vain Gitea Packages docker-rekisterinä

## Tech Stack
- **Runtime:** Bash 4.0+, curl 7.0+, jq 1.6+, git 2.30+, MinIO client (`mc`)
- **Alusta:** Gitea Actions 1.21+, Gitea act runner 0.2+
- **Integraatiot:** Gitea REST API (`/api/v1/`), MinIO S3 API, SonarQube REST API
- **Tuetut build-ekosysteemit:** Java/Maven, Java/Gradle, Node.js/npm
- **Tuetut testikehykset:** Cucumber, JUnit, JaCoCo, Maven Site, custom HTML

## Common Commands
- Workflow-triggerit: `push` branchiin tai `workflow_dispatch`
- Skriptien kutsuminen tapahtuu workflow-stepeistä, ei paikallisesti
- `ci-flow-values.yaml` validointi: skeema `docs/config-model.md`:ssa
- Bats-testit: `bats tests/` — ajaa kaikki skripti- ja workflow-testit
- Testit vaativat: `bats` (Bash Automated Testing System), `jq`, `yq`

## Development Process
- TDD: Red-Green-Refactor jokaiselle tiketille. Testit ensin, toteutus vasta kun testi epäonnistuu.
- Ominaisuusbranchit: `feature/NNNN-tiketin-nimi` (esim. `feature/0001-report-status-sh`)
- Yksi tiketti per sessio. Tiketit riippuvuusjärjestyksessä 0001 → 0012.
- Ennen jokaista tikettiä: lataa `docs/test-plan/tdd-guide.md` + tiketin Required context -skillin lisäksi
- Dogfood: `.gitea/workflows/ci.yml` — kirjaston oma CI käyttää omia reusable workflow'itaan

## What NOT to Do
- Älä lisää tukea muille Git-alustoille (GitLab, BitBucket, GitHub)
- Älä lisää Docker custom actioneita ilman pakottavaa syytä
- Älä siirrä konfiguraatiota pois reposita (`ci-flow-values.yaml`)
- Älä lisää rinnakkaista test flow -suoritusta
- Älä lisää ulkoista orkestraattoria — Gitea REST API riittää
- Älä käytä `repository_dispatch`-webhookia test flow -ketjutukseen