gitea-ci-library/docs/architecture.md

Architecture — Gitea Actions CI -kirjasto

Hub-dokumentti. Komponentit, niiden roolit ja rajapinnat. Yksityiskohtaiset kuvaukset linkitetyissä detail-dokumenteissa.

Tämä dokumentti on normatiivinen — se määrittelee mikä on rakennettava. design-rationale.md kertoo miksi.

---

Yleiskuvaus

Kirjasto on kokoelma Gitea Actions reusable workflow -tiedostoja, jotka orkestroivat mikropalveluiden build-, testaus-, raportointi-, deployment- ja test flow -prosessit. Projekti käyttää kirjastoa uses:-direktiivillä .gitea/workflows/*.yml-tiedostossaan ja määrittelee konfigurationsa ci-flow-values.yaml-tiedostossa.

Kirjasto on Gitea-spesifi. Se hyödyntää Gitean REST API:a commit-statusraportointiin, workflow-dispatchiin ja run-pollaukseen. Raportit tallennetaan MinIO:hon, josta ne ovat selailtavissa HTML-muodossa.

---

Komponentit

Reusable workflowt (4 kpl)

Workflow	Tiedosto	Rooli
Feature flow	ci-feature.yml	Testaa feature-branchin, generoi raportit, raportoi statuksen committiin. Ei buildaa konttia.
Master flow	ci-master.yml	Testaa, buildaa kontin, pushaa rekisteriin, tagittaa commitin, ketjuttaa test flow'n.
Deployment flow	deploy.yml	GitOps-deployment: päivittää YAML-arvoa, committaa, pushaa, raportoi cross-repo-statuksen.
Test flow	test.yml	Vastaanottaa dispatchin, ajaa testit, generoi raportit, raportoi statuksen.

Yksityiskohtaiset kuvaukset: workflows.md

Jaetut skriptit

Skripti	Rooli
report-status.sh	POSTaa build-statuksen Gitea /api/v1/repos/{owner}/{repo}/statuses/{sha}
dispatch-workflow.sh	Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista
push-reports.sh	Puskaa testiraportit MinIO:hon ja generoi URL:n
tag-commit.sh	Tagittaa commitin versiolla Gitea REST API:n kautta

Yksityiskohtaiset kuvaukset: shared-scripts.md

Konfiguraatio

Artefakti	Sijainti	Rooli
ci-flow-values.yaml	Projektin repo	Projektikohtainen konfiguraatio (docker, sonar, deployment, test-flow)
Gitea org secrets	Gitea organization	Tokenit ja salasanat
Gitea org variables	Gitea organization	Infra-tason asetukset (MinIO URL, SonarQube URL)

Yksityiskohtaiset kuvaukset: config-model.md

Ulkoiset palvelut

Palvelu	Rooli
Gitea REST API	Commit-statusraportointi, workflow-dispatch, run-pollaus, taggaus
Gitea Packages	Docker-imagen ja NPM-paketin säilytys
Gitea act runner	Suorittaa workflowt. Konteista, DinD:stä ja label-järjestelmästä: runner.md
MinIO	Testiraporttien tallennus ja staattinen web-hosting
SonarQube	Koodin laadun analyysi ja quality gate

---

Järjestelmäkaavio

%%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
flowchart TB
    subgraph PROJ["Projektin repo"]
        WF[".gitea/workflows/ci.yml
        uses: gitea-ci-library/ci-master@v1"]
        CONF["ci-flow-values.yaml"]
    end

    subgraph LIB["gitea-ci-library (reusable workflowt)"]
        FEATURE["ci-feature.yml"]
        MASTER["ci-master.yml"]
        DEPLOY["deploy.yml"]
        TEST["test.yml"]
    end

    subgraph SCRIPTS["Jaetut skriptit"]
        REPORT["report-status.sh"]
        DISPATCH["dispatch-workflow.sh"]
        PUSHREP["push-reports.sh"]
        TAG["tag-commit.sh"]
    end

    subgraph EXT["Ulkoiset palvelut"]
        GITEA["Gitea API
        + Packages"]
        MINIO["MinIO
        (S3 + static web)"]
        SONAR["SonarQube"]
    end

    subgraph HELM["Helm-repo"]
        VALUES["values-{env}.yaml"]
    end

    subgraph TESTREPO["Testi-repo"]
        TESTWF[".gitea/workflows/test.yml"]
    end

    WF -- "kutsuu" --> MASTER
    WF -- "lukee" --> CONF
    MASTER -- "käyttää" --> SCRIPTS
    DEPLOY -- "käyttää" --> SCRIPTS
    TEST -- "käyttää" --> SCRIPTS
    REPORT -- "POST status" --> GITEA
    DISPATCH -- "dispatch + poll" --> GITEA
    PUSHREP -- "S3 upload" --> MINIO
    TAG -- "POST tag" --> GITEA
    MASTER -- "quality gate" --> SONAR
    DEPLOY -- "muokkaa" --> VALUES
    DEPLOY -- "commit + push" --> HELM
    DISPATCH -- "dispatch" --> TESTWF
    TESTWF -- "raportoi" --> GITEA
    MINIO -- "URL commit-statusviestiin" --> GITEA

    style PROJ fill:#1e3a5f,color:#f9fafb,stroke:#64748b
    style LIB fill:#1f2937,color:#f9fafb,stroke:#64748b
    style SCRIPTS fill:#064e3b,color:#f9fafb,stroke:#64748b
    style EXT fill:#5c1a1a,color:#f9fafb,stroke:#64748b
    style HELM fill:#4a1a6b,color:#f9fafb,stroke:#64748b
    style TESTREPO fill:#4a1a6b,color:#f9fafb,stroke:#64748b
    style WF fill:#2563eb,color:#ffffff
    style CONF fill:#f59e0b,color:#111827
    style FEATURE fill:#2563eb,color:#ffffff
    style MASTER fill:#2563eb,color:#ffffff
    style DEPLOY fill:#2563eb,color:#ffffff
    style TEST fill:#2563eb,color:#ffffff
    style REPORT fill:#059669,color:#ffffff
    style DISPATCH fill:#059669,color:#ffffff
    style PUSHREP fill:#059669,color:#ffffff
    style TAG fill:#059669,color:#ffffff
    style GITEA fill:#dc2626,color:#ffffff
    style MINIO fill:#dc2626,color:#ffffff
    style SONAR fill:#dc2626,color:#ffffff
    style VALUES fill:#9333ea,color:#ffffff
    style TESTWF fill:#9333ea,color:#ffffff
    linkStyle default stroke:#9ca3af,stroke-width:3px

---

Tietovuot

1. Commit-statusraportointi

Workflow-steppi → report-status.sh → POST Gitea API → commitin status päivittyy
                                                    ↘ URL → raporttiin / buildiin

Jokainen vaihe (test, build, push) POSTaa oman statusviestinsä uniikilla key-arvolla. Samaan committiin kertyy useita rinnakkaisia statuksia.

2. Cross-repo traceability

Mikropalvelu (root-build)  →  Helm (deployment)  →  Testi (integraatio)
       ↓                           ↓                       ↓
  Status omaan committiin    Status omaan committiin  Status omaan committiin
       ↑                           ↑                       ↑
  Status root-committiin ←  Status root-committiin ←  Status root-committiin
  (deployattu, testattu)   (mistä kontti tuli)       (mitä testattiin)

Root-build-viite kulkee workflow_dispatchin inputs-parametrina koko ketjun läpi.

3. Raporttien URL-generointi

push-reports.sh → mc cp ./reports/ minio/bucket/{repo}/{commit_short}/{report}/
                → URL = {MINIO_BASE}/{repo}/{commit_short}/{report}/index.html
                → report-status.sh POSTaa URL:n commit-statusviestiin

4. Test flow -ketjutus

ci-master.yml → test-flow-taulukko (ci-flow-values.yaml)
              → for each step:
                  dispatch-workflow.sh {test-repo} {inputs}
                  poll Gitea API run status
                  success? → next step
                  failure? → stop

---

Laajennuspisteet

Piste	Mekanismi	Tila
Docker-rekisterit	Factory/adapter — ci-flow-values.yaml → docker.type → valitsee pusherin	MVP: Gitea Packages. Artifactory, Nexus myöhemmin
Testikehykset	push-reports.sh tukee mitä tahansa hakemistoa → MinIO	Cucumber, JUnit, JaCoCo, Maven Site, custom
Build-ekosysteemit	Workflow'n container: määrittelee projektin itse	Maven, Gradle, npm, mikä tahansa
SonarQube	Rajapinta vaihdettavissa — parempi kuin pollaus tutkitaan	Quality gate -tarkistus

---

Top-level rajoitteet

• Kaikki integraatio Gitea REST API:n kautta — ei suoria tietokantakytkentöjä, ei jaettua filesysteemiä
• Workflowt eivät jaa tilaa keskenään paitsi workflow_dispatchin inputs-parametrien kautta
• Raporttien URL on deterministinen: {MINIO_BASE}/{repo_slug}/{commit_short}/{report}/
• Cross-repo-statusraportoinnissa root-build on aina se mikropalvelun commit, josta ketju käynnistyi

Repo-jako

Repo	Sisältö
gitea-ci-library	Reusable workflowt, jaetut skriptit, report-service/-moduuli (raporttiskriptit, retention CronJob, index.html-generointi)
Deployment / infra -repo (olemassa oleva)	MinIO Kubernetes-manifestit, Traefik OIDC middleware, ConfigMap, ingress

gitea-ci-library/report-service/ on oma moduulinsa samassa repossa — ei erillistä repositoriota, mutta selkeä sisäinen raja workflow-skriptien ja raporttipalvelun koodin välillä. Moduuli sisältää docs/-hakemiston deploy-esimerkeillä, mutta varsinainen deployment hoidetaan GitOps/Helm-repon kautta kuten muutkin palvelut.