gitea-ci-library/docs/shared-scripts.md

# Jaetut skriptit

> Provider-skriptit asuvat `scripts/`-hakemistossa. Consumer-skriptit
> asuvat `.gitea/scripts/`-hakemistossa. ADR 0006.

---

## `report-status.sh`

POSTaa commit-statuksen Gitea REST APIin. Käytetään **vain** kun tarvitaan
custom-linkki (testiraportti, Docker registry). Tool-jobit luottavat
Gitean natiiviin job-statukseen. ADR 0007.

### Rajapinta

```bash
report-status.sh <state> <description> <context> [suite] [custom_url]
```

| Parametri | Pakollinen | Kuvaus |
|---|---|---|
| `state` | Kyllä | `pending`, `success`, `failure` |
| `description` | Kyllä | Ihmisluettava kuvaus |
| `context` | Kyllä | Uniikki avain (`unit-tests`, `acc-tests`, `ci-docker-build-push`) |
| `suite` | Ei | Julkaistun raportin suite-nimi → linkki git-pagesiin |
| `custom_url` | Ei | Oma URL (ohittaa oletus-URL:n generoinnin) |

### Kutsuesimerkkejä

```bash
# Testijobi, linkki git-pages-raporttiin
report-status.sh success "Link to Bats reports" unit-tests bats

# Docker build, custom URL registryyn
report-status.sh success "Docker build & push 1.2.0 OK" ci-docker-build-push "" \
  "https://gitea.example.com/org/-/packages/container/app/1.2.0"
```

### URL-generointi

- Jos `suite` annettu → URL: `${GIT_PAGES_URL}/${repo}/reports/${sha8}/${suite}/`
- Jos `custom_url` annettu → käytetään sellaisenaan
- Muuten → URL: `${GITEA_API_URL}/${repo}/actions/runs/${run_id}` (Gitea Actions -loki)

### Gitea API -kutsu

```bash
curl -X POST "$GITEA_API_URL/api/v1/repos/$REPO/statuses/$COMMIT" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"state\":\"$STATE\",\"target_url\":\"$URL\",\"description\":\"$DESCRIPTION\",\"context\":\"$CONTEXT\"}"
```

---

## `publish-git-pages.sh`

Julkaisee raporttihakemiston git-pages-palveluun PATCH-tar:na.

### Rajapinta

```bash
publish-git-pages.sh <suite>
```

| Parametri | Pakollinen | Kuvaus |
|---|---|---|
| `suite` | Kyllä | Raporttihakemiston nimi (`bats`, `cucumber`, `junit`, ...) |

### Toiminta

1. Lukee raportit hakemistosta `reports/${SHA8}/${suite}/`
2. Pakkaa tar:ksi ja PATCHaa git-pagesiin BasicAuthilla
3. Tulostaa raportin base-URL:n stdoutiin

### Vaaditut env-muuttujat

| Muuttuja | Lähde |
|---|---|
| `GITEA_API_URL` | `env_json` → workflow `env:` |
| `GIT_PAGES_URL` | `env_json` → workflow `env:` |
| `GIT_PAGES_PUBLISH_TOKEN` | Gitea secret → `env:` |
| `GITHUB_REPOSITORY` | Automaattinen |
| `GITHUB_SHA` | Automaattinen |

---

## `ci-validate.sh`

Validoi `.conf`-tiedoston ja tarkistaa että pakolliset secretit on asetettu.
Kutsutaan `config-provider.yml`:stä osana konfiguraation latausta.

### Rajapinta

```bash
ci-validate.sh
```

Lukee tiedoston polun `CI_CONF_FILE`-env-muuttujasta (oletus: `.gitea/workflows/gitea-env.conf`).

### Validointisäännöt

- `.conf`-tiedosto on olemassa
- Jokaisella `KEY=VALUE`-rivillä on arvo (ei tyhjää)
- URL-tyyppiset avaimet alkavat `http://` tai `https://`
- `GITEA_TOKEN` on asetettu
- `GIT_PAGES_PUBLISH_TOKEN` on asetettu

---

## `dispatch-workflow.sh`

Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista synkronisesti.
Käytetään GitOps-deploymentissa ja klusteritestien ketjutuksessa (tuleva).

Generoi automaattisesti `dispatch_id`-tunnisteen, lisää sen dispatch-
inputteihin ja tunnistaa workflow-runin kohdereposta `display_title`-
kentän perusteella. Toimii luotettavasti vaikka samassa repossa olisi
useita samanaikaisia ajoja.

**Kohde-workflow'ssa on oltava `dispatch_id`-input ja `run-name`-kenttä
`display_title`-matchausta varten.** Katso `skills/gitops-update/SKILL.md`.

### Rajapinta

```bash
dispatch-workflow.sh <target_repo> <workflow_file> <ref> <inputs_json> <gitea_api_url> <gitea_token> [timeout_minutes]
```

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `target_repo` | Kyllä | `owner/repo` |
| `workflow_file` | Kyllä | Workflow-tiedosto (esim. `ci-main.yml`) |
| `ref` | Kyllä | Branch |
| `inputs_json` | Kyllä | JSON-objekti dispatch-inputteina |
| `gitea_api_url` | Kyllä | Gitean API-URL |
| `gitea_token` | Kyllä | Gitea API -token (write kohderepoon) |
| `timeout_minutes` | Ei | Aikakatkaisu (oletus 360) |

### Toiminta

1. **Generoi `dispatch_id`** — 8-hex uniikki tunniste
2. **Injektoi** `dispatch_id` inputteihin
3. **Dispatch:** `POST /api/v1/repos/{target_repo}/actions/workflows/{workflow_file}/dispatches`
4. **Etsi run:** pollaa rinnakkaisia `workflow_dispatch`-runeja, matchaa `display_title` sisältää `dispatch_id`:n
5. **Poll:** `GET /api/v1/repos/{target_repo}/actions/runs/{run_id}` — odota valmistumista
6. **Palauta:** exit 0 (success), exit 1 (failure), exit 124 (timeout)

---

## Muuttujat, joita skriptit olettavat

| Muuttuja | Lähde | Käyttäjä |
|---|---|---|
| `GITEA_API_URL` | `env_json` | `report-status.sh`, `ci-validate.sh` |
| `GIT_PAGES_URL` | `env_json` | `publish-git-pages.sh`, `report-status.sh` |
| `GITEA_TOKEN` | Gitea secret | `report-status.sh`, `check-version.yml`, `docker-build-push.yml` |
| `GIT_PAGES_PUBLISH_TOKEN` | Gitea secret | `publish-git-pages.sh` |
| `GITHUB_REPOSITORY` | Automaattinen | Kaikki skriptit |
| `GITHUB_SHA` | Automaattinen | Kaikki skriptit |
| `GITHUB_RUN_ID` | Automaattinen | `report-status.sh` |
| `GITHUB_RUN_NUMBER` | Automaattinen | `docker-build-push.yml` (tag-commit) |