1 parent
b81e86b640
commit
b86ae38b03
8 files changed
+393
-2
No files matched your search
@@ -1,3 +1,91 @@
|
||||
# Notification
|
||||
# notifications
|
||||
|
||||
Module about the Discord Notif on CI
|
||||
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))
|
||||
```
|
||||
Reference in new issue
Block a user