4.5 KiB
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 itssteps(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)—mappingis{step_name: (section, "builds" | "deploy", key)}. Produces:{ "android": [ {"builds": {"apk": True, "aab": False}}, {"deploy": {"itch": True, "play-store": None}}, ], }True/Falsemean the step ran and passed/failed;Nonemeans 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 ofSectionobjects, usingsections_configfor display: per status key, atitle,description,builds_labels,deploy_labels,url_suffixandauthor.
-
core.py— the Discord embed layer, with no CI-specific knowledge at all:StepResult(name, passed, log_url=None)— one build/deploy line;passedisTrue/False/None(pending), rendered as ✅/❌/⏸️.Section(title, description, builds=[], deploys=[], url=None, author=None)— one Discord embed;builds/deploysbecome📦/🚀fields, embed color is green only if nothing in either list isFalse.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
- 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 displaytitle/description/labels/url_suffix.
- Call, in order:
fetch_run_jobs→build_status→sections_from_status→build_payload→send. - 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_TOKENin this repo — Gitea reserves theGITEA_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:
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))