skill & docs

2026-06-22 06:34:37 +03:00
parent fa57a152e4
commit f58497f5e8
6 changed files with 617 additions and 31 deletions
@@ -60,9 +60,15 @@ Salaisuudet eivät ole `.conf`-tiedostossa. Ne määritellään Gitean
 organization/repository secrets -mekanismissa ja välitetään workflowlle
 `secrets: inherit` -direktiivillä.

+**`secrets.GITEA_TOKEN` on Gitean automaattisesti generoima token,
+scopeutuu siihen repoon jossa workflow ajaa.** Se ei oikeuta
+dispatchaamaan toiseen repoon eikä kirjoittamaan toisen repon
+commit-statusta. Cross-repo-operaatioihin tarvitaan manuaalinen
+org-tason token.
+
 | Secret | Pakollinen | Käyttäjä |
 |---|---|---|
-| `GITEA_TOKEN` | Kyllä | `report-status.sh`, `check-version.yml`, `docker-build-push.yml`, `gitops-update.sh` |
+| `GITEA_TOKEN` | Kyllä | `report-status.sh`, `check-version.yml`, `docker-build-push.yml`, `gitops-update.sh` (GitOps-repossa) |
 | `GIT_PAGES_PUBLISH_TOKEN` | Kyllä | `publish-git-pages.sh`, `config-provider.yml` (validointi) |
 | `DOCKER_USERNAME` | Ei | `docker-build-push.yml` (oletus: `github.actor`, ei pakollinen kaikissa registryissä) |
 | `DOCKER_PASSWORD` | Kyllä | `docker-build-push.yml` |
@@ -113,17 +113,38 @@ Lukee tiedoston polun `CI_CONF_FILE`-env-muuttujasta (oletus: `.gitea/workflows/
 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> [timeout_minutes]
+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. **Dispatch:** `POST /api/v1/repos/{target_repo}/actions/workflows/{workflow_file}/dispatches`
-2. **Poll:** `GET /api/v1/repos/{target_repo}/actions/runs` → odota valmistumista
-3. **Palauta:** `conclusion` (`success`/`failure`/`timeout`)
+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)

 ---

@@ -153,9 +153,17 @@ load-config → bats + cucumber → report-summary (always)
 ```
 load-config → check-version →
  [artifact exists] → done
-  [no artifact]    → bats + cucumber → report-summary (always) → docker-build-push
+  [no artifact]    → bats + cucumber
+                     ├─ docker-build-push → gitops-values ─┐
+                     └─ helm-build-push  → gitops-chart   ─┤
+                                                           ├─ gitops-summary
+                     tag-maintenance ←─────────────────────┘
 ```

+GitOps-jobit (`gitops-chart`, `gitops-values`) dispatchaavat GitOps-repon
+workflown ja asettavat commit-statusin code-repoon + GitOps-repoon
+(kaksisuuntainen track). Katso [skills/gitops-update/SKILL.md](../skills/gitops-update/SKILL.md).
+
 ### `example-bats-tests.yml` — Bats unit-testit

 **Trigger:** `workflow_call`
@@ -189,9 +197,15 @@ Forward-compatibeli — ei haittaa vanhemmilla Gitea-versioilla.
 **Riippuvuudet:** `yq`, `scripts/report-status.sh`, `git`

 Päivittää GitOps-repon konfiguraatiotiedoston versionumeron `yq`:lla,
-committaa muutoksen ja asettaa commit-statuksen molempiin repoihin.
+committaa muutoksen ja asettaa commit-statuksen molempiin repoihin
+(kaksisuuntainen track):

-**Input-ympäristömuuttujat:**
+| Status | Mihin repo | Context | Linkki |
+|---|---|---|---|
+| ✅ | **GitOps-repo** | `source/{repo}` | Code-repon committiin |
+| ✅ | **Code-repo** (dispatchin jälkeen) | `gitops/{repo} {RUN_ID}` | GitOps-repon committiin |
+
+**Input-ympäristömuuttujat (ajetaan GitOps-repon workflow'ssa):**

 | Muuttuja | Pakollinen | Kuvaus |
 |---|---|---|
@@ -200,33 +214,53 @@ committaa muutoksen ja asettaa commit-statuksen molempiin repoihin.
 | `VERSION` | Kyllä | Uusi versio (esim. `0.2.3`) |
 | `SOURCE_REPO` | Kyllä | Lähdekoodirepo (esim. `org/app`) |
 | `SOURCE_COMMIT` | Kyllä | Lähdekoodin commit-SHA |
-| `GITOPS_REPO` | Kyllä | GitOps-konfiguraatiorepo (esim. `org/app-gitops`) |
+| `GITOPS_REPO` | Kyllä | GitOps-repo slug |
 | `GITEA_API_URL` | Kyllä | Gitean API-URL |
-| `GITEA_TOKEN` | Kyllä | Gitea API-token |
+| `GITEA_TOKEN` | Kyllä | Gitea API-token (write GitOps-repoon) |
 | `GITOPS_BRANCH` | Ei | GitOps-repon branch (oletus `main`) |
+| `GIT_TAG_PREFIX` | Ei | Komponentin tag-prefix status-nimeämiseen |
+
+**Commit-status (GitOps-repoon):**
+| Kenttä | Formaatti | Esimerkki |
+|--------|-----------|-----------|
+| Context | `source/{repo}` | `source/gitea-ci-library` |
+| Description | `Install to {env} {version}` | `Install to dev 0.2.0` |
+| Target URL | Linkki code-repon committiin | `/org/repo/commit/sha` |
+
+`{env}` parsitaan `INPUT_FILE`:stä (`dev/Chart.yaml` → `dev`).

 **Steppikuvaus:**
 1. Korvaa `YQ_TPL`:n `{{VERSION}}` versiolla
 2. Muodostaa `CLONE_URL` tokenilla ja hostilla
 3. Kloonaa GitOps-repon
 4. Ajaa `yq eval -i` päivittääkseen tiedoston
-5. Commit + push `[skip ci]`
-6. Asettaa commit-statuksen: code-repoon (gitops-konteksti) ja GitOps-repoon (source-konteksti)
+5. Jos muutoksia: commit + push `[skip ci]`, muuten status `— no change`
+6. Asettaa commit-statuksen GitOps-repoon (source-konteksti, linkki code-repoon)

-**Esimerkki dispatchistä:**
-```yaml
- name: Update GitOps
-  run: |
-    export INPUT_FILE=dev/Chart.yaml
-    export YQ_TPL='(.version) = "{{VERSION}}"'
-    export VERSION=0.2.3
-    export SOURCE_REPO=org/app
-    export SOURCE_COMMIT=${{ github.sha }}
-    export GITOPS_REPO=org/app-gitops
-    bash scripts/gitops-update.sh
-  env:
-    GITEA_API_URL: ${{ vars.GITEA_API_URL }}
-    GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-```
+**Scriptiä ei ajeta code reposta.** Se ajaa GitOps-repon workflow'ssa.
+
+### Code-repon commit-status (dispatchin jälkeen)
+
+GitOps-päivityksen valmistuttua `dispatch-workflow.sh` tulostaa
+`GITOPS_COMMIT=<sha>` (GitOps-repon commitin SHA). Code repo asettaa
+oman commit-statusinsa linkillä GitOps-committiin:
+
+| Kenttä | Formaatti | Esimerkki |
+|--------|-----------|-----------|
+| Context | `gitops/{repo} {RUN_ID}` | `gitops/gitea-ci-library 473` |
+| Description | `Install to {env} {version}` | `Install to dev 0.2.0` |
+| Target URL | Linkki GitOps-repon committiin | `/niko/gitea-ci-gitops-tests/commit/def456` |
+
+### Loppuraportti (GITHUB_STEP_SUMMARY)
+
+`gitops-summary`-job (tai `report-summary`-job) lisää rivin GitOps-päivityksestä
+GITHUB_STEP_SUMMARYyn:
+
+| Component | Version | Status | GitOps commit |
+|---|---|---|---|
+| helm | 0.2.0 | success | [link](...) |
+
+Kokonainen esimerkki molemmista puolista: [skills/gitops-update/SKILL.md](../skills/gitops-update/SKILL.md)
+ja [.gitea/workflows/example-main.yml](../.gitea/workflows/example-main.yml).

 ---