aloitus dokumentaatio

2026-06-08 06:04:49 +03:00
parent 92479ebb9c
commit 66e1c98a8c
9 changed files with 1547 additions and 0 deletions
@@ -0,0 +1,190 @@
+# 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 |