# 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.

```yaml
- 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)
```

```yaml
- 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.