diff --git a/.gitea/workflows/publish.yml b/.gitea/workflows/publish.yml new file mode 100644 index 0000000..67dc1ac --- /dev/null +++ b/.gitea/workflows/publish.yml @@ -0,0 +1,29 @@ +name: Publish package + +on: + push: + tags: + - "v*.*.*" + workflow_dispatch: + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install uv + run: curl -LsSf https://astral.sh/uv/install.sh | sh + + - name: Build package + run: ~/.local/bin/uv build + + - name: Publish to the Gitea package registry + env: + TWINE_USERNAME: ${{ secrets.PACKAGE_PUBLISH_USERNAME }} + TWINE_PASSWORD: ${{ secrets.PACKAGE_PUBLISH_TOKEN }} + run: | + ~/.local/bin/uv tool install twine + ~/.local/bin/twine upload \ + --repository-url "${{ github.server_url }}/api/packages/${{ github.repository_owner }}/pypi" \ + dist/* diff --git a/.python-version b/.python-version new file mode 100644 index 0000000..6324d40 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.14 diff --git a/README.md b/README.md index a4dd8ef..2618668 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,91 @@ -# Notification +# notifications -Module about the Discord Notif on CI \ No newline at end of file +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)) +``` diff --git a/notification/__init__.py b/notification/__init__.py new file mode 100644 index 0000000..a267e76 --- /dev/null +++ b/notification/__init__.py @@ -0,0 +1,19 @@ +"""Discord build-status notifications for Gitea Actions CI.""" + +from .core import Attachment, Section, StepResult, build_payload, send +from .gitea_api import fetch_run_jobs +from .status import StepMapping, build_status, sections_from_status + +__version__ = "0.1.0" + +__all__ = [ + "Attachment", + "Section", + "StepResult", + "build_payload", + "send", + "fetch_run_jobs", + "StepMapping", + "build_status", + "sections_from_status", +] diff --git a/notification/core.py b/notification/core.py new file mode 100644 index 0000000..83ba182 --- /dev/null +++ b/notification/core.py @@ -0,0 +1,110 @@ +"""Discord embed layer for CI build/deploy notifications. + +No CI-specific knowledge lives here: everything deals in StepResult/Section +objects and Discord's webhook payload shape. +""" + +from dataclasses import dataclass, field +from typing import Optional + +COLOR_SUCCESS = 0x2ECC71 +COLOR_FAILURE = 0xE74C3C + + +@dataclass +class StepResult: + name: str + passed: Optional[bool] + log_url: Optional[str] = None + + @property + def value(self) -> str: + if self.passed is None: + return "⏸️ pas encore exécuté" + if self.passed: + return "✅ passed" + if self.log_url: + return f"❌ failed — [voir les logs]({self.log_url})" + return "❌ failed" + + +@dataclass +class Section: + """One Discord embed: a build/deploy report for one part of a pipeline.""" + title: str + description: str + builds: list[StepResult] = field(default_factory=list) + deploys: list[StepResult] = field(default_factory=list) + url: Optional[str] = None + author: Optional[str] = "Gitea CI" + + @property + def passed(self) -> bool: + return all(result.passed is not False for result in (*self.builds, *self.deploys)) + + def to_embed(self) -> dict: + fields = [ + {"name": f"📦 {build.name}", "value": build.value} + for build in self.builds + ] + [ + {"name": f"🚀 {deploy.name}", "value": deploy.value} + for deploy in self.deploys + ] + embed = { + "title": self.title, + "description": self.description, + "color": COLOR_SUCCESS if self.passed else COLOR_FAILURE, + "fields": fields, + } + if self.url: + embed["url"] = self.url + if self.author: + embed["author"] = {"name": self.author} + return embed + + +@dataclass +class Attachment: + """A file attached to the Discord notification.""" + filename: str + content: bytes + content_type: str = "application/octet-stream" + + +def build_payload( + sections: list[Section], + username: Optional[str] = None, + avatar_url: Optional[str] = None, + content: Optional[str] = None, +) -> dict: + payload = {"embeds": [section.to_embed() for section in sections]} + if username: + payload["username"] = username + if avatar_url: + payload["avatar_url"] = avatar_url + if content: + payload["content"] = content + return payload + + +def send(webhook_url: str, payload: dict, attachments: Optional[list[Attachment]] = None) -> None: + import requests + + if not attachments: + response = requests.post(webhook_url, json=payload, timeout=10) + response.raise_for_status() + return + + import json + + files = { + f"files[{i}]": (a.filename, a.content, a.content_type) + for i, a in enumerate(attachments) + } + response = requests.post( + webhook_url, + data={"payload_json": json.dumps(payload)}, + files=files, + timeout=10, + ) + response.raise_for_status() diff --git a/notification/gitea_api.py b/notification/gitea_api.py new file mode 100644 index 0000000..4c41cbd --- /dev/null +++ b/notification/gitea_api.py @@ -0,0 +1,17 @@ +"""Thin, agnostic client for the Gitea Actions API. + +Only reads what's needed to build a build/deploy status report: the jobs +and steps of a single workflow run. +""" + +from typing import Any + + +def fetch_run_jobs(base_url: str, token: str, owner: str, repo: str, run_id) -> list[dict[str, Any]]: + """Get a Gitea Action job state""" + import requests + + url = f"{base_url}/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}/jobs" + response = requests.get(url, headers={"Authorization": f"token {token}"}, timeout=10) + response.raise_for_status() + return response.json()["jobs"] diff --git a/notification/status.py b/notification/status.py new file mode 100644 index 0000000..6095c9a --- /dev/null +++ b/notification/status.py @@ -0,0 +1,111 @@ +"""Turns raw Gitea Actions job/step results into a plain nested status dict, +and renders that dict into Discord-ready ``Section`` objects. + +Nothing here knows about any specific project's artifact names (APK, AAB, +Play Store, ...) — the step-name mapping and display labels are supplied by +the caller (see Tamagosaure's ``notify.py`` for a concrete example). + +Status dicts look like:: + + { + "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 during this workflow run (job skipped, step never reached, ...). +""" + +from typing import Any, Optional + +from .core import Section, StepResult + +# step name -> (section key, "builds" | "deploy", item key). +# Keyed by step name rather than job name: several reusable workflows can +# define jobs with the same name (e.g. both the web and android pipelines +# have a job called "deploy-itch"), but their step names are always distinct. +StepMapping = dict[str, tuple[str, str, str]] + + +def _conclusion_to_bool(conclusion: str) -> Optional[bool]: + if conclusion == "success": + return True + if conclusion == "failure": + return False + return None + + +def build_status(jobs: list[dict[str, Any]], mapping: StepMapping) -> dict[str, list[dict]]: + status: dict[str, list[dict]] = {} + + def bucket_for(section: str, bucket: str) -> dict: + entries = status.setdefault(section, []) + for entry in entries: + if bucket in entry: + return entry[bucket] + new_bucket: dict = {} + entries.append({bucket: new_bucket}) + return new_bucket + + # Seed every mapped key to "not run" first, so a step that never shows + # up in this run (skipped job, earlier failure, ...) still reports as + # pending instead of silently disappearing from the payload. + for _step_name, (section, bucket, key) in mapping.items(): + bucket_for(section, bucket)[key] = None + + steps_by_name = { + step["name"]: step.get("conclusion", "") + for job in jobs + for step in job.get("steps", []) + } + + for step_name, (section, bucket, key) in mapping.items(): + if step_name in steps_by_name: + bucket_for(section, bucket)[key] = _conclusion_to_bool(steps_by_name[step_name]) + + return status + + +def sections_from_status( + status: dict[str, list[dict]], + sections_config: dict[str, dict], + run_url: Optional[str] = None, +) -> list[Section]: + """Build Discord ``Section`` objects from a status dict. + + ``sections_config`` maps a status key (e.g. "android") to display + config: ``title``, ``description``, ``builds_labels``, ``deploy_labels``, + ``url_suffix`` and ``author``. + """ + sections = [] + for key, config in sections_config.items(): + entries = status.get(key, []) + builds_raw = next((entry["builds"] for entry in entries if "builds" in entry), {}) + deploy_raw = next((entry["deploy"] for entry in entries if "deploy" in entry), {}) + + build_labels = config.get("builds_labels", {}) + deploy_labels = config.get("deploy_labels", {}) + + url = run_url + if run_url and config.get("url_suffix"): + url = f"{run_url}{config['url_suffix']}" + + sections.append( + Section( + title=config["title"], + description=config.get("description", ""), + builds=[ + StepResult(name=build_labels.get(name, name), passed=passed, log_url=run_url) + for name, passed in builds_raw.items() + ], + deploys=[ + StepResult(name=deploy_labels.get(name, name), passed=passed, log_url=run_url) + for name, passed in deploy_raw.items() + ], + url=url, + author=config.get("author", "Gitea CI"), + ) + ) + return sections diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..0878b2f --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,16 @@ +[project] +name = "notification" +version = "0.1.0" +description = "Discord build-status notifications for Gitea Actions CI" +readme = "README.md" +requires-python = ">=3.10" +dependencies = [ + "requests>=2.31", +] + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["notification"]