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

# Jaetut skriptit

> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Tämä dokumentti määrittelee reusable workflow'sta kutsuttavien bash-skriptien rajapinnat, parametrit ja vastuut.

Skriptit asuvat `gitea-ci-library/scripts/`-hakemistossa. Workflowt lataavat ne checkout-stepin jälkeen.

---

## `report-status.sh`

POSTaa build-statuksen Gitea-commitin REST APIin.

### Rajapinta

```bash
report-status.sh <state> <description> <url> [key] [root_commit] [root_repo]
```

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `state` | Kyllä | `pending`, `success`, `failure`, `error` |
| `description` | Kyllä | Ihmisluettava kuvaus (esim. "Unit tests passed") |
| `url` | Kyllä | Linkki buildiin tai raporttiin |
| `key` | Ei | Uniikki avain. Oletus: `commit-{sha_short}` |
| `root_commit` | Ei | Root-buildin commit-hash (cross-repo-raportointia varten) |
| `root_repo` | Ei | Root-buildin repo (cross-repo-raportointia varten) |

### Kutsuesimerkkejä

```bash
# Buildin aloitus
report-status.sh pending "Building..." "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"

# Testivaihe valmis, linkki raporttiin
report-status.sh success "Unit tests OK" "$MINIO_BASE_URL/$GITHUB_REPOSITORY/${GITHUB_SHA::8}/cucumber/overview-features.html" "unit-test"

# Deployment valmis, cross-repo: raportoi takaisin mikropalvelun committiin
report-status.sh success "Deployed to staging" "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/commit/$GITHUB_SHA" "deploy-staging" "$ROOT_COMMIT" "$ROOT_REPO"
```

### 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\": \"$KEY\"
  }"
```

Status-arvot mapataan Gitean skeemaan: `pending` (INPROGRESS), `success` (SUCCESS), `failure` (FAILURE), `error` (STOPPED).

---

## `dispatch-workflow.sh`

Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista synkronisesti.

### Rajapinta

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

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `target_repo` | Kyllä | `owner/repo` |
| `workflow_file` | Kyllä | Workflow-tiedoston nimi (esim. `test.yml`) |
| `ref` | Kyllä | Branch |
| `inputs_json` | Kyllä | JSON-objekti input-parametreina |
| `timeout_minutes` | Ei | Oletus: 360 (6 tuntia) |

### Toiminta

1. **Dispatch:** `POST /api/v1/repos/{target_repo}/actions/workflows/{workflow_file}/dispatches`
2. **Etsi run:** `GET /api/v1/repos/{target_repo}/actions/runs?status=running` → etsi uusin (aikaleimasta)
3. **Poll:** `GET /api/v1/repos/{target_repo}/actions/runs/{run_id}` 10s välein
4. **Lopeta:** Kun `status == "completed"` → palauta `conclusion` (`success`/`failure`/`cancelled`)
5. **Timeout:** Jos kestää yli `timeout_minutes` → palauta `timeout`

### Kutsuesimerkki

```bash
dispatch-workflow.sh "tests/integration" "test.yml" "main" \
  '{"version":"1.2.3","tags":"@smoke","root_commit":"abc123","root_repo":"services/temperature-store"}'
```

---

## `push-reports.sh`

Puskaa raporttihakemiston MinIO:hon ja päivittää indeksisivut.

### Rajapinta

```bash
push-reports.sh <report_type> <source_dir> [index_title]
```

| Parametri | Pakollinen | Kuvaus |
|-----------|------------|--------|
| `report_type` | Kyllä | Raportin tyyppi (`cucumber`, `jacoco`, `junit`, `site`) |
| `source_dir` | Kyllä | Paikallinen hakemisto, jossa raporttitiedostot |
| `index_title` | Ei | Näkyvä nimi indeksisivulla (esim. "Cucumber Reports") |

### Toiminta

1. Kopioi raportit: `mc cp --recursive {source_dir} minio/reports/{repo}/{commit_short}/{report_type}/`
2. Päivitä `/reports/{repo}/{commit_short}/index.html` — lisää linkki tähän raporttiin
3. Päivitä `/reports/{repo}/index.html` — varmista että tämä build on listalla
4. Palauta URL: `{MINIO_BASE_URL}/{repo}/{commit_short}/{report_type}/index.html`

### Indeksisivut

**Projektin build-indeksi** (`/reports/{repo}/index.html`):
- Lista buildeista aikajärjestyksessä (uusin ensin)
- Jokainen rivi: commit hash (linkki), päivämäärä, status (✅/❌), branch

**Buildin raportti-indeksi** (`/reports/{repo}/{commit_short}/index.html`):
- Lista raporteista linkkeinä
- Linkki "← Back to builds" → projektin build-indeksiin

Molemmat generoidaan uudestaan jokaisen pushauksen yhteydessä. Staattinen HTML, ei vaadi palvelinpuolen logiikkaa.

### Kutsuesimerkki

```bash
push-reports.sh cucumber target/cucumber-report "Cucumber Reports"
# → https://reports.example.com/temperature-store/abc12345/cucumber/overview-features.html

push-reports.sh jacoco target/jacoco-report "JaCoCo Coverage"
# → https://reports.example.com/temperature-store/abc12345/jacoco/index.html
```

---

## `tag-commit.sh`

Tagittaa commitin versiolla Gitea REST API:n kautta.

### Rajapinta

```bash
tag-commit.sh <version>
```

### Toiminta

```bash
curl -X POST "$GITEA_API_URL/api/v1/repos/$GITHUB_REPOSITORY/tags" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"tag_name\": \"$VERSION\",
    \"message\": \"Build #$GITHUB_RUN_NUMBER\",
    \"target\": \"$GITHUB_SHA\"
  }"
```

### Kutsu

```bash
tag-commit.sh "1.2.3.$GITHUB_RUN_NUMBER"
```

Tagataan vain onnistuneen buildin ja pushin jälkeen. Tämän jälkeen `isContainerBuilt()` palauttaa `true` samalle commitille.

---

## Muuttujat, joita skriptit olettavat

Skriptit lukevat nämä Gitea Actionsin ympäristömuuttujat:

| Muuttuja | Lähde | Käyttäjä |
|----------|-------|----------|
| `GITEA_API_URL` | Org variable | Kaikki skriptit |
| `GITEA_TOKEN` | Org secret | `report-status.sh`, `dispatch-workflow.sh`, `tag-commit.sh` |
| `MINIO_BASE_URL` | Org variable | `push-reports.sh` |
| `MINIO_ACCESS_KEY` | Org secret | `push-reports.sh` |
| `MINIO_SECRET_KEY` | Org secret | `push-reports.sh` |
| `GITHUB_REPOSITORY` | Automaattinen | Kaikki skriptit |
| `GITHUB_SHA` | Automaattinen | Kaikki skriptit |
| `GITHUB_SERVER_URL` | Automaattinen | `report-status.sh` |
| `GITHUB_RUN_ID` | Automaattinen | `report-status.sh`, `tag-commit.sh` |
| `GITHUB_RUN_NUMBER` | Automaattinen | `tag-commit.sh` |
| `GITHUB_ACTOR` | Automaattinen | Docker-labelit |