217 lines
8.6 KiB
Markdown
217 lines
8.6 KiB
Markdown
# 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](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](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](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](runner.md) |
|
|
| **MinIO** | Testiraporttien tallennus ja staattinen web-hosting |
|
|
| **SonarQube** | Koodin laadun analyysi ja quality gate |
|
|
|
|
---
|
|
|
|
## Järjestelmäkaavio
|
|
|
|
```mermaid
|
|
%%{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_dispatch`in `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_dispatch`in `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.
|