gitea-ci-library/docs/tickets/0002-dispatch-workflow-sh.md

Ticket 0002: dispatch-workflow.sh

Vaihe: 2/12 Status: done Feature branch: feature/0002-dispatch-workflow-sh TDD required: Yes Feature file required: Yes

Required context:

• docs/test-plan/tdd-guide.md
• tests/features/0002-dispatch-workflow.feature
• Skills: tdd, implementation, clean-code, bash-script

---

TDD — Red-Green-Refactor

Red

Kirjoita tests/dispatch-workflow.bats mock-Gitea API:a vasten:

• Dispatch → API palauttaa 201
• Poll: API palauttaa running 3 kertaa, sitten completed + success → exit 0
• Poll: API palauttaa completed + failure → exit 1
• Timeout: ylittää timeout_minutes → exit 124
• Virheellinen target_repo → exit 1

bats tests/dispatch-workflow.bats
# FAIL

Green

scripts/dispatch-workflow.sh — dispatch + poll-silmukka 10s välein.

bats tests/dispatch-workflow.bats
# PASS

Refactor

Poista duplikaatio, tarkista edge caset. Testit vihreänä.

DoD

• Cucumber: @ticket-0002 and @mock → kaikki skenaariot GREEN
• tests/dispatch-workflow.bats — kaikki testit läpi
• Dispatch, poll, ja timeout toimivat mock-API:a vasten
• Exit-koodit: 0 (success), 1 (failure), 124 (timeout)

---

Toiminto

Dispatchaa workflow toisessa repossa ja pollaa sen valmistumista synkronisesti. Vastaa Jenkinsin buildJob()-semantiikkaa — kutsuja jää odottamaan kunnes dispatchattu workflow on valmis.

Rajapinta

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. test.yml)
ref	Kyllä	Branch
inputs_json	Kyllä	JSON-objekti input-parametreina
gitea_api_url	Kyllä	Gitean API-URL
gitea_token	Kyllä	Gitea API -token
timeout_minutes	Ei	Oletus: 360

API-kutsut

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
3. Poll: GET /api/v1/repos/{target_repo}/actions/runs/{run_id} (10s välein)
4. Lopetus: conclusion == "success" → exit 0, muuten exit 1
5. Timeout: > timeout_minutes → exit 124

Esimerkkikutsu

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

Verifiointi

Mock-Gitea API, jossa:

• POST dispatches → palauttaa 201
• GET runs → palauttaa status: running 3 kertaa, sitten status: completed, conclusion: success

Skripti pollaa ja palauttaa exit 0.

Viitteet

• docs/shared-scripts.md — Rajapinnan määrittely
• docs/design-rationale.md — Periaate 4: Deterministinen testigraafi
• docs/architecture.md — Tietovuo 4: Test flow -ketjutus