# notifications Discord build-status notifications for Gitea Actions CI. Renders a dynamic embed (color, per-job pass/fail fields, link to the failing job's logs) instead of a static message — and knows nothing about any specific project's jobs, artifacts, or deploy targets. The mapping from "this repo's steps" to "this dict shape" lives in the calling script (`notify.py` in this repo), not in this package. Currently lives under `.gitea/` in the Tamagosaure repo. The goal is to extract it as a standalone package (published to Gitea's package registry) once Froggies and the Blender Pipeline need the same notification format — see the project memory for that initiative. Until then, treat this directory as if it already were that package: don't add Tamagosaure-specific knowledge to it. ## Pieces - **`gitea_api.py`** — `fetch_run_jobs(base_url, token, owner, repo, run_id)` calls the Gitea Actions API (`/actions/runs/{run_id}/jobs`) and returns the raw list of jobs, each with its `steps` (name + `conclusion`). - **`status.py`** — turns that raw job/step list into a plain nested dict, and that dict into Discord-ready objects: - `build_status(jobs, mapping)` — `mapping` is `{step_name: (section, "builds" | "deploy", key)}`. Produces: ```python { "android": [ {"builds": {"apk": True, "aab": False}}, {"deploy": {"itch": True, "play-store": None}}, ], } ``` `True`/`False` mean the step ran and passed/failed; `None` means it never ran this workflow run (job skipped, step never reached, ...). - `sections_from_status(status, sections_config, run_url=None)` — turns that dict into a list of `Section` objects, using `sections_config` for display: per status key, a `title`, `description`, `builds_labels`, `deploy_labels`, `url_suffix` and `author`. - **`core.py`** — the Discord embed layer, with no CI-specific knowledge at all: - `StepResult(name, passed, log_url=None)` — one build/deploy line; `passed` is `True`/`False`/`None` (pending), rendered as ✅/❌/⏸️. - `Section(title, description, builds=[], deploys=[], url=None, author=None)` — one Discord embed; `builds`/`deploys` become `📦`/`🚀` fields, embed color is green only if nothing in either list is `False`. - `build_payload(sections, username=None, avatar_url=None, content=None)` — wraps sections into a Discord webhook payload. - `send(webhook_url, payload, attachments=None)` — POSTs it. **Why key by step name, not job name**: a run can contain several jobs with the *same* name (e.g. both the web and android pipelines define a job called `deploy-itch`, called from two different reusable workflows), but step names are unique within a run. `build_status` matches on step name for exactly this reason — no need to know which job a step belongs to. ## Wiring it up in a new project 1. Write a `notify.py` (or similar) that defines, for your project: - `STEP_MAPPING`: every Gitea step name you care about → `(section, bucket, key)`. - `SECTIONS_CONFIG`: per section, the display `title`/`description`/labels/`url_suffix`. 2. Call, in order: `fetch_run_jobs` → `build_status` → `sections_from_status` → `build_payload` → `send`. 3. In the workflow step that runs it, set these env vars (all come from the `github.*` context Gitea Actions exposes, except the token): - `DISCORD_WEBHOOK_URL` — Discord webhook secret. - A token with read access to this repo's Actions API (named `FORGE_API_TOKEN` in this repo — Gitea reserves the `GITEA_` secret name prefix, so pick a non-reserved name). - `GITEA_SERVER_URL` — `${{ github.server_url }}`. - `REPOSITORY` — `${{ github.repository }}` (`owner/repo`). - `RUN_ID` — `${{ github.run_id }}`. - `RUN_URL` — for linking back to the run from Discord. See `.gitea/notify.py` in this repo for the complete, working example. ## Debugging Everything up to the Discord POST is plain Python, no network calls beyond the two documented above. To check what a run would report without sending anything, fetch its jobs once and feed them straight to `build_status`: ```python import json from notification.gitea_api import fetch_run_jobs from notification.status import build_status from notify import STEP_MAPPING # your project's mapping jobs = fetch_run_jobs("https://git.graou.studio", TOKEN, "owner", "repo", RUN_ID) print(json.dumps(build_status(jobs, STEP_MAPPING), indent=2)) ```