gitea-ci-library/docs/adr/0007-status-reporting-pattern.md

7. Statusraportoinnin pattern

Päätös

Jokaisen jobin on raportoitava lopputulos commit-statukseen. Käytössä on kaksi patternia, jotka eroavat toisistaan vain raporttien julkaisun osalta.

Tool-jobit (validate, build, push, tag, check-version, report-index)

PENDING → työvaihe → SUCCESS (if: success) / FAILURE (if: failure)

- name: Set Gitea status to PENDING
  run: bash .ci/scripts/report-status.sh pending "Validating..." ci-validate

- name: Do work
  run: some-command

- name: Report status SUCCESS
  if: success()
  run: bash .ci/scripts/report-status.sh success "OK" ci-validate

- name: Report status FAILURE
  if: failure()
  run: bash .ci/scripts/report-status.sh failure "FAILED" ci-validate

Test-jobit (bats, cucumber)

PENDING → testit → publish (always) → status (always, exit-koodin mukaan)

- name: Set Gitea status to PENDING
  run: bash .ci/scripts/report-status.sh pending "Running tests..." ci-tests

- name: Run tests
  shell: bash
  run: |
    run-tests
    EXIT=$?
    echo "EXIT=${EXIT}" >> "${GITHUB_ENV}"
    exit ${EXIT}

- name: Publish reports
  if: always()
  run: bash .ci/scripts/publish-git-pages.sh suite

- name: Report status
  if: always()
  shell: bash
  run: |
    if [ "${EXIT}" = "0" ]; then
      bash .ci/scripts/report-status.sh success "Tests OK" ci-tests suite
    else
      bash .ci/scripts/report-status.sh failure "Tests FAILED" ci-tests suite
    fi

Periaatteet

1. Ennen varsinaista työvaihetta asetetaan status pending — näin commit-näkymässä näkyy heti, että jobi on käynnissä.
2. run-komennon on nostettava virhe ylös — oli kyse tool-callista (docker, curl, bash) tai testien ajamisessa tapahtuneesta testivirheestä.
3. Tool-jobit käyttävät if: success() ja if: failure() — jobin sisäinen tila ratkaisee suoraan kumman steppi ajetaan.
4. Test-jobit käyttävät if: always() publish- ja status-stepeissä — raportti julkaistaan ja status asetetaan aina, riippumatta testin lopputuloksesta.
5. Testiraportit julkaistaan myös virhetilanteessa, mikäli ne ovat syntyneet.
6. Status-linkki ohjaa testiraporttiin (suite-parametri) jos raportti on olemassa, muuten Gitea Actions -logiin.

Tausta

Aiemmassa quality-gate.yml:ssä käytettiin if: always() + sisäistä if/elseä myös tool-jobeissa (steps.<id>.outcome-tarkistus). Tämä on tarpeetonta kompleksisuutta työvaiheille, jotka eivät tuota erillistä raporttia — jobin oma tila (success/failure) on riittävä ehto.

Test-jobit tarvitsevat if: always():n koska raportti on julkaistava ja status asetettava silloinkin kun testit epäonnistuvat. Status-viestin URL osoittaa suoraan raporttiin git-pagesissa, mikä on kriittinen feature virheenjäljityksessä.

Pipeline-status jokaiselle vaiheelle on välttämätön, koska Gitean branch protection -säännöt käyttävät commit-statusta merge-estona. Jokainen ci-*-konteksti voi toimia vaadittuna statuksena PR:n sulkemiselle — jos yksikin status on failure, merge estyy. Tämä korvaa Jenkinsin disableConcurrentBuilds()- ja build gate -logiikan Gitea-natiivilla mekanismilla.

Status-näkymä toimii myös master-haaran terveyden monitorina: Git UI:sta näkee suoraan yhdellä silmäyksellä onko uusin commit vihreä. Ei tarvitse avata CI-järjestelmän dashboardia.