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

7. Statusraportoinnin pattern

Päätös

Gitea Actionsin natiivi job-status on ensisijainen. Commit-status API:a (report-status.sh) käytetään vain kun työvaihe tuottaa ulkoisen linkin (testiraportti, Docker registry), jota natiivistaatus ei tue.

Tool-jobit (validate, check-version, tag-commit)

Ei API-kutsuja. Luotetaan Gitean omaan job-statukseen.

- uses: actions/checkout@v4

- name: Do work
  run: do-something

Test-jobit (bats, cucumber)

API:a käytetään raporttilinkin upottamiseksi commit-näkymään.

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

- 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 bats

- name: Report status
  if: always()
  shell: bash
  run: |
    if [ "${EXIT}" = "0" ]; then
      bash .ci/scripts/report-status.sh success "Link to Bats reports" unit-tests bats
    else
      bash .ci/scripts/report-status.sh failure "Link to Bats reports" unit-tests bats
    fi

Build & push -jobit (docker-build-push)

API:a käytetään Docker registry -linkin upottamiseksi.

build → push → SUCCESS (registry-linkillä) / FAILURE

Periaatteet

1. Gitea Actionsin natiivi job-status on ensisijainen — myös PENDING/Running-tila tulee natiivisti. API:a käytetään vain custom-linkin tarpeeseen (ADR 0004).
2. run-komennon on nostettava virhe ylös — oli kyse tool-callista tai testivirheestä (ADR 0008).
3. Test-jobit käyttävät if: always() publish- ja status-stepeissä — raportti julkaistaan ja status asetetaan aina, riippumatta testin lopputuloksesta.
4. Testiraportit julkaistaan myös virhetilanteessa, mikäli ne ovat syntyneet.
5. Commit-statuksen duplikaatio natiivijob-statuksen kanssa hyväksytään testijobeille — se on ainoa mekanismi upottaa raporttilinkki commit-näkymään.
6. Tool-jobit eivät käytä API:a lainkaan — ne luottavat Gitean natiiviin job-statukseen.

Tausta

Aiemmin commit-status API:a käytettiin jokaisessa työvaiheessa, myös niissä joilla ei ollut raporttia linkitettäväksi (validate, check-version, tag-commit). Tämä tuotti duplikaatiota: Gitea näytti sekä natiivin CI Main / Validate CI config Successful että API-statuksen ci-validate CI config valid. Kehittäjälle molemmat kertoivat saman asian.

Käytännön pakko kuitenkin pakottaa API:n käyttöön testijobeissa: ilman raporttilinkkiä kukaan ei löydä testituloksia. Gitean natiivi job-status linkittää aina jobin lokiin — ei ulkoiseen raporttiin. Tämä on paras saatavilla oleva kompromissi.