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

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

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