# Consumer Guide — Kirjaston käyttöönotto > Anna tämä dokumentti AI:lle kun haluat ottaa `gitea-ci-library`:n käyttöön > uudessa projektissa tai muokata olemassa olevia pipelineja. --- ## Rakenneperiaate **Pipeline-tiedostot (`ci-feature.yml`, `ci-main.yml`) eivät saa sisältää varsinaista logiikkaa.** Ne ovat puhtaita reitittimiä: pelkkiä `uses:`-kutsuja `if`- ja `needs`-ehdoilla. Kaikki testien ajaminen, buildaus ja raportointi kuuluu omiin `workflow_call`-tiedostoihinsa. ``` ci-unit-tests.yml ← testien ajaminen (varsinainen logiikka) ci-acc-tests.yml ← hyväksymätestit (varsinainen logiikka) ci-feature.yml ← reititin: load-config → test-workflow't → summary ci-main.yml ← reititin: load-config → check-version → testit → build → summary ``` Provider tarjoaa 3 reusable workflow'ta ja joukon skriptejä. Consumer omistaa orkestroinnin: mitä palikoita käytetään, missä järjestyksessä, millä branch-ehdoilla. Consumer ei kopioi providerin koodia — se viittaa `uses:`-direktiivillä. --- ## Vaihe 1: Konfiguraatiotiedosto Luo `.gitea/workflows/gitea-env.conf`: ```ini GITEA_API_URL=https://gitea.example.com GIT_PAGES_URL=https://reports.example.com ``` Jos buildaat Docker-kontteja, lisää: ```ini DOCKER_REGISTRY=gitea.example.com/myorg DOCKER_IMAGE_NAME=my-service DOCKER_UI_URL=https://gitea.example.com/myorg/-/packages/container/my-service #DOCKERFILE=Dockerfile.platform # valinnainen, oletus Dockerfile ``` Salaisuudet määritellään Gitean Settings → Secrets -näkymässä: | Secret | Pakollinen | |---|---| | `GITEA_TOKEN` | Aina | | `GIT_PAGES_PUBLISH_TOKEN` | Aina | | `DOCKER_USERNAME` | Vain jos buildaat kontteja (ei pakollinen kaikissa registryissä) | | `DOCKER_PASSWORD` | Vain jos buildaat kontteja | --- ## Vaihe 2: Test-workflow't (varsinainen logiikka) Jokainen testityyppi omaan `workflow_call`-tiedostoonsa. Tässä esimerkki Maven-yksikkötesteistä. Luo `.gitea/workflows/ci-unit-tests.yml`: ```yaml name: Unit Tests on: workflow_call: inputs: env_json: required: true type: string secrets: GITEA_TOKEN: required: true GIT_PAGES_PUBLISH_TOKEN: required: true env: GITEA_API_URL: ${{ fromJson(inputs.env_json).GITEA_API_URL }} GIT_PAGES_URL: ${{ fromJson(inputs.env_json).GIT_PAGES_URL }} GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} GIT_PAGES_PUBLISH_TOKEN: ${{ secrets.GIT_PAGES_PUBLISH_TOKEN }} jobs: test: runs-on: ubuntu-latest container: maven:3.9-eclipse-temurin-21 steps: - uses: actions/checkout@v4 - uses: actions/checkout@v4 with: repository: org/gitea-ci-library path: .ci - name: Run tests shell: bash run: | mvn test EXIT=$? echo "EXIT=${EXIT}" >> "${GITHUB_ENV}" exit ${EXIT} - name: Publish reports if: always() run: bash .ci/scripts/publish-git-pages.sh junit - name: Report status if: always() shell: bash run: | if [ "${EXIT}" = "0" ]; then bash .ci/scripts/report-status.sh success "Link to JUnit reports" unit-tests junit else bash .ci/scripts/report-status.sh failure "Link to JUnit reports" unit-tests junit fi ``` Hyväksymätesteille vastaava tiedosto `ci-acc-tests.yml` (Cucumber, Playwright tms.), jossa oma `container:`, oma testikomento ja oma `suite`-nimi. **Tärkeää:** `mvn test` korvataan omalla testikomennolla. `container:` ja `publish-git-pages.sh`-suite ovat projektikohtaisia. Muu runko pysyy samana. --- ## Vaihe 3: Feature-haaran CI (puhdas reititin) Luo `.gitea/workflows/ci-feature.yml`. **Ei sisällä yhtään `run:`-steppiä** — pelkkiä `uses:`-kutsuja: ```yaml name: CI Feature on: push: branches-ignore: - main workflow_dispatch: jobs: load-config: uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1 secrets: inherit with: config_path: .gitea/workflows/gitea-env.conf unit-tests: needs: [load-config] uses: ./.gitea/workflows/ci-unit-tests.yml@main secrets: inherit with: env_json: ${{ needs.load-config.outputs.env_json }} acc-tests: needs: [load-config] uses: ./.gitea/workflows/ci-acc-tests.yml@main secrets: inherit with: env_json: ${{ needs.load-config.outputs.env_json }} report-summary: needs: [load-config, unit-tests, acc-tests] if: always() uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@v1 with: env_json: ${{ needs.load-config.outputs.env_json }} suites: junit cucumber ``` --- ## Vaihe 4: Main-haaran CI (puhdas reititin) Luo `.gitea/workflows/ci-main.yml`. **Ei sisällä yhtään `run:`-steppiä**: ```yaml name: CI Main on: push: branches: - main workflow_dispatch: jobs: load-config: uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1 secrets: inherit with: config_path: .gitea/workflows/gitea-env.conf check-version: needs: [load-config] uses: org/gitea-ci-library/.gitea/workflows/check-version.yml@v1 secrets: inherit with: env_json: ${{ needs.load-config.outputs.env_json }} unit-tests: needs: [load-config, check-version] if: needs.check-version.outputs.artifact_exists != 'true' uses: ./.gitea/workflows/ci-unit-tests.yml@main secrets: inherit with: env_json: ${{ needs.load-config.outputs.env_json }} acc-tests: needs: [load-config, check-version] if: needs.check-version.outputs.artifact_exists != 'true' uses: ./.gitea/workflows/ci-acc-tests.yml@main secrets: inherit with: env_json: ${{ needs.load-config.outputs.env_json }} build-push: needs: [load-config, check-version, unit-tests, acc-tests] if: needs.check-version.outputs.artifact_exists != 'true' uses: org/gitea-ci-library/.gitea/workflows/docker-build-push.yml@v1 secrets: inherit with: env_json: ${{ needs.load-config.outputs.env_json }} version: ${{ needs.check-version.outputs.version }} report-summary: needs: [load-config, unit-tests, acc-tests] if: always() uses: org/gitea-ci-library/.gitea/workflows/report-summary.yml@v1 with: env_json: ${{ needs.load-config.outputs.env_json }} suites: junit cucumber ``` Mihin kiinnittää huomiota: - `check-version` on **idempotentti** — jos commitilla on jo tagi, kaikki sen jälkeiset jobit skipataan (`if: artifact_exists != 'true'`) - `needs`-ketju takaa järjestyksen ja virheiden propagointin - Artifakti voi olla **mitä tahansa** — `docker-build-push.yml` on yksi esimerkki. Voit korvata sen Maven-deploylla, npm-publishilla, tai millä tahansa omalla build-workflow'lla. Rajapinta on `version`-input. --- ## Versionhallinta `check-version.yml` lukee version automaattisesti prioriteettijärjestyksessä: | # | Lähde | Formaatti | Esimerkki | |---|---|---|---| | 1 | `VERSION`-tiedosto | Plain text | `0.2` | | 2 | `package.json` | `.version` | `"version": "0.2.0"` | | 3 | `pom.xml` | `` | `0.2.0` | `major.minor` otetaan tästä. Patch (kolmas numero) lasketaan automaattisesti git-tageista. Esim. jos `VERSION` on `0.2` ja tagit ovat `0.2.0`, `0.2.1`, niin seuraava on `0.2.2`. --- ## Testien lisääminen — oma työkalu Kopioi `ci-unit-tests.yml`:n rakenne uudelle testityypille ja muuta: - `container:` — oma testikonttisi - Testikomento — oma testityökalusi (`npm test`, `pytest`, `go test`, ...) - `publish-git-pages.sh ` — oma suite-nimi - `report-status.sh ... ` — oma uniikki konteksti Lisää uusi jobi reititintiedostoihin (`ci-feature.yml`, `ci-main.yml`) samalla `uses:`-kaavalla. Testijobit ajetaan rinnakkain — ne kaikki `needs: [load-config]` ilman keskinäisiä riippuvuuksia. ### Tärkeimmät säännöt 1. **Exit-koodi aina ylös:** ```bash run-tests EXIT=$? echo "EXIT=${EXIT}" >> "${GITHUB_ENV}" exit ${EXIT} ``` 2. **Ei pipeä testikomennon perään.** `command | tee file` syö exit-koodin. Käytä `command > file 2>&1` jos haluat logit talteen. 3. **Status vain jos on raportti.** Testijobit käyttävät commit-status API:a raporttilinkin takia. Tool-jobit luottavat Gitean natiiviin job-statukseen. 4. **`if: always()`** publish- ja status-stepeissä — raportti julkaistaan ja status asetetaan vaikka testit feilaisivat. ### Raporttien generointi `publish-git-pages.sh ` odottaa hakemiston `reports/${SHA8}//` olevan olemassa. Sen sisältö sellaisenaan julkaistaan git-pagesiin. `report-status.sh` linkittää statuksen suoraan tähän hakemistoon — selain avaa sieltä `index.html`:n. Test-workflow'n vastuulla on tuottaa raportit oikeaan polkuun. Kaksi tyypillistä patternia: **Pattern 1: Yksi raporttitiedosto (Cucumber)** Testityökalu tuottaa suoraan HTML-raportin. Yksinkertaisin tapaus: ```bash mkdir -p "reports/${GITHUB_SHA:0:8}/cucumber" npx cucumber-js \ --format html:"reports/${GITHUB_SHA:0:8}/cucumber/index.html" ``` **Pattern 2: Monta raporttitiedostoa (Bats + coverage)** Eri työkalut tuottavat eri tiedostoja. Generoi `index.html` joka linkittää ne yhteen: ``` reports/${SHA8}/bats/ ├── index.html ← generoitu: linkit alla oleviin ├── results.txt ← bats-testien stdout ├── coverage/ ← bashcov-coverage HTML │ └── index.html └── ... ``` ```bash mkdir -p "reports/${GITHUB_SHA:0:8}/bats" # Aja testit → results.txt bats tests/ > "reports/${GITHUB_SHA:0:8}/bats/results.txt" 2>&1 # Generoi coverage → coverage-hakemisto bashcov -- bats tests/ # Generoi index.html joka linkittää kaikkiin raportteihin cat > "reports/${GITHUB_SHA:0:8}/bats/index.html" <<'EOF'

Bats Test Reports

EOF ``` Yhteistä molemmille: `publish-git-pages.sh `-kutsun jälkeen raportit ovat julkisesti selailtavissa. `report-status.sh`-kutsu `suite`-parametrilla linkittää commit-statuksen suoraan `index.html`:ään. Jos testit feilasivat, raportti generoidaan silti — se kertoo MITKÄ testit feilasivat. Siksi publish- ja status-stepit käyttävät `if: always()`. --- ## Branch protection (PR-gate) Gitean Settings → Branches → Add Rule: - **Branch:** `main` - **Enable Require Status Checks:** päälle - **Status checks:** valitse `unit-tests`, `acc-tests` --- ## Raporttien koonti (Gitea 1.27+) Kun Gitea päivittyy versioon 1.27, `GITHUB_STEP_SUMMARY`-tuki mahdollistaa raporttilinkkien koontinäkymän suoraan Gitea UI:ssa. `report-summary`-jobi on mukana molemmissa reititinesimerkeissä yllä — forward-compatibeli, ei hajota vanhemmilla versioilla. --- ## Provider-rajapinnat — referenssi ### Workflowt | Workflow | Käyttötarkoitus | |---|---| | `config-provider.yml` | Lataa + validoi `.conf`, tuottaa `env_json` | | `check-version.yml` | Tarkistaa onko commit buildattu, laskee version | | `docker-build-push.yml` | Buildaa + puskea Docker-imagen, tagittaa | | `report-summary.yml` | `GITHUB_STEP_SUMMARY`-taulukko raporttilinkeillä | ### Skriptit (kutsutaan `.ci/scripts/`-polun kautta) | Skripti | Käyttötarkoitus | |---|---| | `report-status.sh` | POSTaa commit-statuksen linkillä | | `publish-git-pages.sh` | Julkaisee raporttihakemiston git-pagesiin | | `ci-validate.sh` | Validoi `.conf`-tiedoston (kutsutaan `config-provider.yml`:stä) | --- ## ADR-yhteenveto — consumerin kannalta oleelliset säännöt Nämä säännöt on formalisoitu [docs/adr/](docs/adr/)-hakemistossa. Tässä tiivistelmä consumer-näkökulmasta: ### Reititin ei sisällä suorittavaa koodia (ADR 0010) `ci-feature.yml` ja `ci-main.yml` ovat **puhtaita reitittimiä**: - **Vain** `uses:`, `needs:` ja `if:` sallittu - **Ei** `run:`-komentoja, ei inline-skriptejä, ei `actions/checkout` Kaikki suorittava koodi on omissa `workflow_call`-tiedostoissaan: - `ci-unit-tests.yml` — testikomento, publish, status - `ci-acc-tests.yml` — testikomento, publish, status - Provider-workflowt (`config-provider.yml`, `check-version.yml`, …) ### Yksi steppi = yksi workflow_call-tiedosto Jokainen pipeline-steppi (testityyppi, build, deploy) on oma tiedostonsa. Ei kahta eri komentoa samassa workflow'ssa. Tämä pitää reitittimet ohuina ja steppitiedostot itsenäisinä — testattavissa erikseen. ### Provider-versio on `@v1` (ADR 0009) Kaikki `org/gitea-ci-library/…`-viittaukset käyttävät `@v1`-tagia: ```yaml uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@v1 ``` `@main` on vain providerin oman repon sisäiseen dogfood-käyttöön. Breaking changet on kielletty — `v1`-rajapinta on pysyvä. ### Exit-koodi on ainoa onnistumisen mittari (ADR 0008) Älä käytä pipeä (`|`) komennon perässä — se syö exit-koodin. Käytä redirectiä (`> file 2>&1`) jos haluat logit talteen. ### Commit-status vain raporttilinkille (ADR 0007) `report-status.sh`-skriptiä käytetään VAIN kun on raportti linkitettäväksi. Tool-jobit (build, deploy) luottavat Gitean natiiviin job-statukseen. ### Providerin checkout ei kuulu consumerille Providerin scriptit haetaan `actions/checkout`-stepillä. Consumer käyttää providerin määrittelemää polkua (`.ci/scripts/`). Consumer ei kopioi eikä muokkaa providerin tiedostoja. ### Testattavuus Jokainen `workflow_call`-tiedosto on testattavissa itsenäisesti — consumer voi ajaa `ci-unit-tests.yml`:n paikallisesti act:lla tai Gitean `workflow_dispatch`:llä ilman koko pipelineä.