publish -> link -> read testattu "e2e"
port forward, local publish ja luettu tämän repon linkin luomisen mallisella url julkaistu raportti
This commit is contained in:
moilanik
+28
-211
@@ -1,227 +1,44 @@
|
||||
# Design Rationale — Gitea Actions CI -kirjasto
|
||||
# Design Rationale — git-pages → Nginx + PV
|
||||
|
||||
> Miksi kirjasto on rakennettu näin. Arvot, periaatteet ja reunaehdot, joiden
|
||||
> varaan arkkitehtuuri nojaa.
|
||||
>
|
||||
> Tämä dokumentti on **normatiivinen** — arkkitehtuurin on noudatettava näitä
|
||||
> periaatteita. Jos ehdotettu muutos on ristiriidassa rationalen kanssa,
|
||||
> rationalen on muututtava ensin.
|
||||
> Päivitetty: 2026-06-28 — git-pages korvattu Nginx + upload-sidecar -arkkitehtuurilla.
|
||||
|
||||
---
|
||||
## Miksi git-pages poistettiin
|
||||
|
||||
## Miksi tämä projekti on olemassa
|
||||
Codeberg git-pages storage v2 pakottaa kaikki tiedostot yhteen `.index`-protobufiin per site. Raja on 1MB kovakoodattu. Monorepo täytti tämän — uusia raportteja ei voinut julkaista.
|
||||
|
||||
Mikropalveluarkkitehtuurissa jokainen palvelu tarvitsee CI-putken: testit,
|
||||
laatutarkistukset, buildin, kontituksen ja julkaisun. Ilman jaettua
|
||||
kirjastoa jokainen tiimi kopioi saman YAML-boilerplaten, tekee omat
|
||||
virheensä ja ylläpitää omaa versiotaan. Ajan myötä putket ajautuvat erilleen
|
||||
— toisessa on `shell: bash`, toisessa ei; toinen käyttää `set -o pipefail`,
|
||||
toinen kadottaa exit-koodin `tee`:hen.
|
||||
## Uusi arkkitehtuuri
|
||||
|
||||
Tämä kirjasto on se mitä kopioidaan. Se tarjoaa valmiit, testatut,
|
||||
dokumentoidut rakennuspalikat joista jokainen tiimi kokoaa oman putkensa.
|
||||
Palikat ovat Gitea Actionsin `uses:`-direktiivillä kutsuttavia reusable
|
||||
workflow'ta — ei asennusta, ei runtime-riippuvuutta, ei versiopäivityksiä
|
||||
projekteihin.
|
||||
- **Nginx** palvelee staattisia tiedostoja suoraan PV:ltä
|
||||
- **Upload-sidecar** (busybox httpd + CGI) ottaa vastaan PUT + tar.gz ja purkaa PV:lle
|
||||
- **URL = FS-polku** — `/{owner}/{repo}/{branch}/{sha8}/{suite}/`
|
||||
- **Branch raakana URL:ssa** — `feature/x` FS:ssä = `feature/x/`
|
||||
- **Linkki on aina 1-suuntainen** — gitea → raportti
|
||||
- **GITEA_API_URL poistuu** publish-skriptin pakollisista env-varista
|
||||
|
||||
---
|
||||
## Ratkaisun periaatteet
|
||||
|
||||
## Suunnitteluperiaatteet
|
||||
### 1. Ei välikerrosta — tiedostot suoraan PV:llä
|
||||
|
||||
### 1. Palikka-arkkitehtuuri: pieniä, vaihdettavia, yhden vastuun workflow'ta
|
||||
git-pagesin `.index`-protobuf poistuu. Tiedostot ovat suoraan PV:llä kansiorakenteessa. Nginx palvelee niitä suoraan.
|
||||
|
||||
Jokainen provider-workflow tekee yhden asian:
|
||||
### 2. Yksinkertainen upload-sidecar
|
||||
|
||||
| Workflow | Vastuu |
|
||||
|---|---|
|
||||
| `config-provider.yml` | Lataa ja validoi konfiguraatio |
|
||||
| `check-version.yml` | Tarkistaa onko commit buildattu, laskee version |
|
||||
| `docker-build-push.yml` | Buildaa, puskea ja tagittaa kontin |
|
||||
Python HTTP-serveri ottaa vastaan PUT-pyynnöt ja purkaa tar.gz:n oikeaan paikkaan. Ei monimutkaista API:a, ei tietokantaa.
|
||||
|
||||
Mikään workflow ei kutsu toista provider-workflowta. Consumer
|
||||
— siis mikropalvelun oma pipeline-tiedosto — on ainoa paikka joka
|
||||
tietää mitä palikoita tarvitaan ja missä järjestyksessä.
|
||||
### 3. Julkaisu ja luku eri porteilla
|
||||
|
||||
**Miksi:** Tämä on sama periaate kuin Unix-putkissa tai mikropalveluissa:
|
||||
pieniä, itsenäisiä komponentteja jotka tekevät yhden asian hyvin.
|
||||
Consumer voi vaihtaa yhden palikan toiseen — esimerkiksi Docker-buildin
|
||||
tilalle Maven-paketoinnin — ilman että muut palikat muuttuvat.
|
||||
Ratkaisu ei ole se että kaikki ajetaan, vaan se että jokainen tiimi
|
||||
valitsee mitä tarvitsee. Monoliittinen "kaikki yhdessä" -workflow
|
||||
pakottaisi jokaisen tiimin ajamaan tarpeettomia vaiheita.
|
||||
Eri portit mahdollistavat eri Traefik-säännöt: julkaisu vaatii BasicAuthin, luku on julkinen.
|
||||
|
||||
### 2. Gitea ensin — hyödynnä alustaa, älä taistele sitä vastaan
|
||||
### 4. Retention lukee PV:tä suoraan
|
||||
|
||||
Gitea Actions tarjoaa kolme asiaa ilmaiseksi:
|
||||
Ei HTTP API:a retentionia varten. Skripti listaa kansiot, tarkistaa branchit Giteasta, poistaa vanhat.
|
||||
|
||||
1. **Jobien visuaalinen status** — jokainen jobi näkyy automaattisesti
|
||||
commit-näkymässä checkmarkilla, spinnerillä tai ristillä.
|
||||
2. **Cross-job riippuvuudet** — `needs` hoitaa virheiden propagointin:
|
||||
jos edeltävä jobi feilaa, riippuvat jobit skipataan.
|
||||
3. **Reusable workflow -jakelu** — `uses: org/repo/.gitea/workflows/file.yml@v1`
|
||||
on natiivisti versioitu, skopattu ja välimuistitettu.
|
||||
## Rajapinnat
|
||||
|
||||
Kirjasto käyttää näitä kaikkia. Ei omaa tilakonetta, ei custom
|
||||
action -runtimea, ei ulkoista orkestraattoria.
|
||||
|
||||
**Esimerkki:** Tool-jobit eivät kutsu commit-status API:a lainkaan.
|
||||
Gitean oma job-status riittää — `success`/`failure`/`running` näkyy
|
||||
automaattisesti. API:a käytetään vain kun tarvitaan **custom-linkki**
|
||||
(testiraporttiin tai Docker registryyn), jota natiivistaatus ei tarjoa.
|
||||
Tämä linjaus on dokumentoitu ADR 0004 ja 0007:ssä.
|
||||
|
||||
### 3. Status näkyy siellä missä työ tehdään — Git-commitissa
|
||||
|
||||
Kehittäjä työskentelee Gitissä. `git log`, `git blame`, PR-näkymä —
|
||||
nämä ovat päivittäiset työkalut. CI-statuksen kuuluu näkyä siellä,
|
||||
ei erillisessä dashboardissa.
|
||||
|
||||
Gitea Actionsin natiivi job-status tekee tämän automaattisesti:
|
||||
jokainen commit näyttää välittömästi mitkä jobit on ajettu ja millä
|
||||
tuloksella. Testiraportteihin pääsee yhdellä klikkauksella commitin
|
||||
status-kuvakkeesta — koska `report-status.sh` asettaa `target_url`:n
|
||||
osoittamaan suoraan HTML-raporttiin git-pagesissa.
|
||||
|
||||
Tämä ei ole kosmeettinen yksityiskohta. Se on devops-käytännön
|
||||
ydin: palautesilmukka on lyhin mahdollinen. Commit → build → status
|
||||
näkyy samassa näkymässä jossa kehittäjä jo on.
|
||||
|
||||
### 4. Exit-koodi on ainoa totuus
|
||||
|
||||
CI-putken jokaisen `run`-stepin onnistuminen määräytyy **vain ja
|
||||
ainoastaan** exit-koodin perusteella. Ei tiedoston olemassaolon, ei
|
||||
stdout-tulosteen, ei arvauksen. `0` = ok, kaikki muu = ei ok.
|
||||
|
||||
Tämä kuulostaa itsestään selvältä, mutta YAML-pipelineissa se rikkoutuu
|
||||
helposti. Pipe (`|`) `tee`:hen syö exit-koodin. Tiedoston olemassaolon
|
||||
tarkistus (`[ -f results.xml ]`) ei kerro testien läpimenosta.
|
||||
|
||||
**Käytännössä:** Jokainen `run`-steppi ottaa exit-koodin talteen
|
||||
`$?`-muuttujaan ennen kuin mikään muu komento ehtii muuttaa sitä,
|
||||
ja stepin viimeinen rivi on `exit ${EXIT}`. Pipeä ei käytetä
|
||||
työvaiheen viimeisenä komentona. Ks. ADR 0008.
|
||||
|
||||
### 5. Pienin mahdollinen pinta-ala
|
||||
|
||||
Jokainen ylimääräinen riippuvuus on ylimääräinen vikaantumispiste.
|
||||
Kirjaston ainoat riippuvuudet:
|
||||
|
||||
- Gitea Actions (alusta)
|
||||
- `bash`, `curl`, `jq` (ubuntu-latest runnerissa valmiina)
|
||||
- Docker (runnerissa valmiina)
|
||||
- git-pages (raporttien hostaus, erillinen palvelu)
|
||||
|
||||
Ei Pythonia, ei Node.js:ää ajonaikaisesti (testit omissa konteissaan).
|
||||
Ei tietokantaa. Ei ulkoista tilanhallintaa. Kirjasto on joukko
|
||||
YAML-tiedostoja ja shell-skriptejä — samat työkalut jotka jokainen
|
||||
devops-ihminen jo osaa.
|
||||
|
||||
### 6. Konfiguraatio repoon, salaisuudet Giteaan
|
||||
|
||||
Projektikohtainen konfiguraatio (`.gitea/workflows/gitea-env.conf`)
|
||||
asuu mikropalvelun omassa repossa. Kehittäjä omistaa sen — hän tietää
|
||||
mikä on Docker-imagen nimi, mihin registryyn puskea, mikä on
|
||||
testiympäristön URL.
|
||||
|
||||
Salaisuudet (tokenit, salasanat) elävät Gitean secrets-mekanismissa,
|
||||
eivät repon tiedostoissa. `secrets: inherit` välittää ne providerin
|
||||
workflow'hun ilman että consumerin tarvitsee tietää mitä salaisuuksia
|
||||
mikäkin provider tarvitsee.
|
||||
|
||||
Poikkeus: infra-tason asetukset (`GIT_PAGES_URL`, `GITEA_API_URL`)
|
||||
ovat Gitean organization secrets/variables -mekanismissa. Ne eivät
|
||||
ole repokohtaisia.
|
||||
|
||||
### 7. Consumer omistaa orkestroinnin, provider tarjoaa palikat
|
||||
|
||||
Tämä on kirjaston tärkein arkkitehtuurinen päätös (ADR 0005).
|
||||
|
||||
Provider (`gitea-ci-library`) ei tiedä mitä testejä ajetaan, missä
|
||||
järjestyksessä, tai millä branchilla. Se tarjoaa kolme reusable
|
||||
workflow'ta ja joukon skriptejä.
|
||||
|
||||
Consumer (mikropalvelun `example-feature.yml` / `example-main.yml`)
|
||||
päättää:
|
||||
- Mitkä palikat kutsutaan
|
||||
- Missä järjestyksessä (`needs`)
|
||||
- Millä branch-ehdoilla (`if`)
|
||||
- Mitkä testikontit käytetään (input-parametrit)
|
||||
|
||||
Tämä on tarkoituksellinen vallanjako. Provider ei voi tietää jokaisen
|
||||
tiimin tarpeita — eikä sen pidäkään. Consumer ei voi muuttaa providerin
|
||||
sisäistä toteutusta — eikä sen pidäkään. Rajapinta on `workflow_call` ja
|
||||
se on molemmille osapuolille selvä.
|
||||
|
||||
### 8. Branch-kohtainen reititys, ei yhtä kaikille
|
||||
|
||||
Eri brancheilla on eri tavoite:
|
||||
|
||||
- **Feature-haara:** Onko koodi laadukasta? → testit, validointi
|
||||
- **Main-haara:** Onko tästä versiosta jo artifakti? Jos ei →
|
||||
testit + build + push + tag. Jos on → ei tehdä mitään (tai
|
||||
jatketaan klusteritesteihin).
|
||||
|
||||
Tämä logiikka elää consumerin pipeline-tiedostossa, ei providerissa.
|
||||
Se on puhdasta `if`-ehtoa ja `needs`-ketjutusta — ei skriptausta,
|
||||
ei monimutkaisia ehtoja providerin sisällä.
|
||||
|
||||
### 9. Raportit erillisellä palvelulla, linkit commitissa
|
||||
|
||||
Gitea Actionsin artifact-järjestelmä on binääriarkisto — ZIP-lataus,
|
||||
ei HTML-selailtavuutta. Testiraportit (Cucumber HTML, Bats-coverage)
|
||||
on voitava avata selaimessa yhdellä klikkauksella.
|
||||
|
||||
Ratkaisu: git-pages Helm-chartti, joka tarjoaa staattista
|
||||
tiedostohostingia HTTP:llä. `publish-git-pages.sh` vie raportit
|
||||
sinne; `report-status.sh` linkittää commit-statuksen suoraan
|
||||
raporttiin. Retention hoitaa git-pagesin sidecar automaattisesti.
|
||||
|
||||
Tulevaisuudessa `GITHUB_STEP_SUMMARY` (Gitea 1.27+) tarjoaa
|
||||
vaihtoehtoisen kanavan: jobin Summary-välilehdelle renderöityvä
|
||||
Markdown-taulukko kaikista raporttilinkeistä.
|
||||
|
||||
### 10. Vain Gitea — ei monialustatukea ilman tarvetta
|
||||
|
||||
Yhden alustan tukeminen kunnolla on vaikeampaa kuin kolmen tukeminen
|
||||
huonosti. Gitea Actionsin `uses:`-mekanismi, `needs`-semantiikka,
|
||||
`secrets: inherit`, `gitea`-konteksti — nämä ovat alustakohtaisia
|
||||
ominaisuuksia joita abstraktiokerros vain haittaisi.
|
||||
|
||||
Jos toinen alusta tulee ajankohtaiseksi, sille kirjoitetaan oma
|
||||
toteutus. Siihen asti yksi alusta riittää. Ennenaikainen yleistys
|
||||
on devopsissa yhtä haitallista kuin ohjelmistosuunnittelussa.
|
||||
|
||||
---
|
||||
|
||||
## Arkkitehtuuriset rajoitteet
|
||||
|
||||
### Mitä kirjasto EI tee
|
||||
|
||||
- **Ei ulkoista orkestraattoria.** Pipeline-ohjaus on Gitea Actionsin
|
||||
`needs`-ketjuissa ja consumerin `if`-ehdoissa.
|
||||
- **Ei custom actioneita.** Reusable workflow on kevyempi, versioitu
|
||||
ja jaeltu Gitean oman mekanismin kautta.
|
||||
- **Ei asennusta projekteihin.** Consumer viittaa `uses:`-direktiivillä
|
||||
suoraan tämän repon workflow-tiedostoihin. Ei npm-pakettia, ei
|
||||
git-submodulea, ei kopioitavia tiedostoja.
|
||||
- **Ei runtime-riippuvuuksia.** Provider-skriptit käyttävät vain
|
||||
työkaluja jotka ovat Gitea Actionsin `ubuntu-latest` runnerissa
|
||||
valmiina: `bash`, `curl`, `jq`.
|
||||
- **Ei monorepo-konfiguraatiota.** Jokainen mikropalvelu omistaa
|
||||
oman pipeline-tiedostonsa ja konfiguraationsa.
|
||||
|
||||
---
|
||||
|
||||
## Mitä tietoisesti hylättiin
|
||||
|
||||
| Hylätty | Syy |
|
||||
|---|---|
|
||||
| Monoliittinen "kaikki yhdessä" -workflow | Pakottaa kaikille samat vaiheet. Palikka-arkkitehtuuri antaa jokaiselle tiimille vain mitä se tarvitsee |
|
||||
| Oma orkestraattoripalvelin | Ylimääräinen ylläpidettävä. Gitean `needs` ja `if` riittävät |
|
||||
| Docker-pohjaiset custom actionit | Tuovat riippuvuuden Docker-rekisteriin. Reusable workflow on natiivimpi |
|
||||
| Commit-status API jokaiselle vaiheelle | Duplikointia — Gitea näyttää job-statuksen automaattisesti. API vain custom-linkeille |
|
||||
| `tee`-putki debug-näkyvyyteen | Syö exit-koodin. stdout ohjataan tiedostoon `>` ilman pipeä |
|
||||
| Multi-Git-platform-tuki | Ennenaikaista optimointia ilman tarvetta |
|
||||
| Gitea Packages raporttien hostingiin | Ei HTML-selailtavuutta — vain binäärilataus |
|
||||
| Gitea Pages + reports-branch | Race condition rinnakkaisten pushien kanssa |
|
||||
| `repository_dispatch` ketjutukseen | Lisää konfiguraatiota vastaanottaviin repoihin. Suora API-kutsu eksplisiittisempi |
|
||||
| Suunta | Protokolla | Auth | Kuvaus |
|
||||
|--------|------------|------|--------|
|
||||
| Julkaisija → Traefik | HTTPS PUT | BasicAuth `publish` | tar.gz → upload-sidecar |
|
||||
| Selain → Traefik | HTTPS GET/HEAD | — | HTML-raportti nginxiltä |
|
||||
| Retention → Gitea | HTTPS GET | PAT | branch-tarkistus |
|
||||
| Traefik → nginx | HTTP :8080 | — | sisäverkko |
|
||||
| Traefik → upload | HTTP :8081 | — | sisäverkko (BasicAuth tarkistettu) |
|
||||
|
||||
Reference in New Issue
Block a user