notification (0.1.0)

Published 2026-10-30 18:28:11 +01:00 by stilobique in stilobique/Notification

Installation

pip install --index-url https://git.graou.studio/api/packages/stilobique/pypi/simple/ --extra-index-url https://pypi.org/simple notification

About this package

Discord build-status notifications for Gitea Actions CI

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:
      {
          "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:

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))

Requirements

Requires Python: >=3.10
Details
PyPI
2026-10-30 18:28:11 +01:00
26
14 KiB
Assets (2)
Versions (1) View all
0.1.0 2026-10-30