Angelia

Every release, on the wire, the moment it lands.

Wire Sample bulletins

Priority comes from the bump: major is FLASH, minor BULLETIN, patch ROUTINE.

Angelia is the self-hosted release event bus. It watches PyPI, npm, crates.io and GitHub or GitLab releases, turns every new version into one signed CloudEvent, and delivers it to your CI, your chat or your AI agents.

v0.2.01 binary6 sources3 sinks + pull, SSE, MCPSQLite or PostgresApache-2.0

Detect. Normalize. Deliver. Nothing else.

What to do about a release stays with you. Angelia's job is to make sure you hear about every one, once, in a shape every consumer understands.

  1. Detect. It watches, politely.

    A scheduler checks each target on its own interval with per-host rate limits and conditional requests. Fifty watches on pypi:requests cost one fetch.

  2. Normalize. It understands versions.

    SemVer, PEP 440, calver: every new version is diffed against the known set, so a backport like 1.9.4 after 2.0.0 is caught. Policies filter and cool down.

  3. Deliver. It never drops one.

    One immutable event, one delivery per subscriber, written in the same transaction. Retries with backoff, dead letters, replay.

The bulletin is the product.

Whatever the source, whatever the sink, consumers read the same CloudEvent, specified by a JSON Schema.

{
  "type": "dev.angelia.release.published.v1",
  "id": "01JBX2A7C8D9E0F1G2H3J4K5M6",
  "subject": "pypi:requests@2.33.0",
  "data": {
    "package": "requests",
    "version": "2.33.0",
    "previous_version": "2.32.5",
    "bump": "minor",
    "backport": false,
    "scheme": "pep440",
    "urls": { "release": "https://pypi.org/project/requests/2.33.0/" },
    "watch": { "name": "requests", "labels": { "team": "platform" } },
    "purl": "pkg:pypi/requests@2.33.0"
  }
}
id
Generated once. Every retry and replay carries it, so consumers deduplicate on it.
bump
Measured against the greatest earlier version, in the package's own scheme. Filter on it, route on it.
purl
A package URL, so you can join releases with your SBOMs, OSV advisories and Renovate.
null, never missing
Every documented field is always present. Read the contract.

Route it to every desk that cares.

Push to the systems that can be called. Let the others pull, from a cursor that never skips.

DeskForSink
WebhookYour CI server, n8n, a Lambda, your own bot. Signed with Standard Webhooks. Webhookskind: webhook
GitHub ActionsRun tests against the new version, open an update PR, start an agent. Dispatchkind: github-dispatch
Chat and pushSlack, Discord, Telegram, ntfy, Gotify, Matrix, with your own message template. Chatkind: shoutrrr
Pull and streamConsumers with no public URL: named cursors, acknowledgements, server-sent events. Pull APIGET /v1/events
AI agentsAsk what changed, read events, add a watch, through MCP with scoped tokens. MCPangelia mcp

From a Home Assistant release to a pull request.

A real setup, end to end, for a custom integration that must keep up with Home Assistant every month.

  1. Angelia sees home-assistant/core publish a release, betas included.
  2. It dispatches ha-release to the integration's repository, after a one-hour cooldown.
  3. Tests run against that exact version, before anyone reads the changelog.
  4. Claude reviews the release notes and the HA API diff, with no tools, and opens an issue.
  5. A maintainer approves with a label, and an agent prepares the fix as a PR.
Read the recipe
NARRATED ยท EN Watch the walkthrough

Three commands to a running wire.

One container with SQLite on a volume. The binary is static, signed and attested when you outgrow it.

# one container, SQLite, loopback only
$ git clone --depth 1 https://github.com/angelia-dev/angelia && cd angelia/deploy/compose/sqlite
$ docker run --rm ghcr.io/angelia-dev/angelia:0.2.0 token generate > bootstrap-token && chmod 0644 bootstrap-token
$ docker compose up -d
# then say what to watch, in watches.yaml
version: 1
watches:
  - name: home-assistant
    source: github-release
    coordinates: { repo: home-assistant/core }
    scheme: calver

What is on the wire today.

Angelia is pre-1.0. This is the honest ledger of v0.2.0.

Shipped

  • Sources: PyPI, npm, crates.io, GitHub releases and tags, GitLab releases
  • Private registries and mirrors, stored secrets bound to hosts
  • Sinks: signed webhooks, GitHub dispatch, Slack, Discord, Telegram, ntfy, Gotify, Matrix
  • Policies: pre-releases, ranges, bumps, include and exclude, cooldown
  • REST API with scoped tokens, pull API, SSE, MCP
  • SQLite and Postgres, several replicas without a queue

Planned

  • OCI images, Maven, Go module proxy, generic HTTP sources
  • NATS and MQTT sinks, GitLab pipeline triggers
  • Release notes in events, OSV advisories
  • Third-party plugins (WASM)
  • Web UI and published Helm charts

Hear about the next release before your users do.

Angelia, from the ancient Greek for "message, news": the herald's daughter, now running your release wire.