gitea-ci-library/docs/consumer-guide.md

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:

GITEA_API_URL=https://gitea.example.com
GIT_PAGES_URL=https://reports.example.com

Jos buildaat Docker-kontteja, lisää:

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:

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:

name: CI Feature
on:
  push:
    branches-ignore:
      - main
  workflow_dispatch:

jobs:
  load-config:
    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@main
    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@main
    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ä:

name: CI Main
on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  load-config:
    uses: org/gitea-ci-library/.gitea/workflows/config-provider.yml@main
    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@main
    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@main
    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@main
    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	<version>	<version>0.2.0</version>

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 <suite> — oma suite-nimi
• report-status.sh ... <context> <suite> — 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:

   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 <suite> odottaa hakemiston reports/${SHA8}/<suite>/ 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:

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
  └── ...

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'
<!DOCTYPE html>
<html><body>
<h1>Bats Test Reports</h1>
<ul>
  <li><a href="results.txt">Test results (raw)</a></li>
  <li><a href="coverage/index.html">Code coverage</a></li>
</ul>
</body></html>
EOF

Yhteistä molemmille: publish-git-pages.sh <suite>-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ä)