Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 19 additions & 9 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ jobs:

publish:
name: Build container image (amd64)
runs-on: blacksmith-2vcpu-ubuntu-2404
runs-on: ubuntu-24.04
timeout-minutes: 60

permissions:
Expand All @@ -33,15 +33,22 @@ jobs:

outputs:
digest: ${{ steps.build.outputs.digest }}
image: ${{ steps.image.outputs.name }}

steps:
- name: Check out source
uses: useblacksmith/checkout@v1 # v7.0.1
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false

- name: Setup Blacksmith Builder
uses: useblacksmith/setup-docker-builder@v1
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4

- name: Set image name
id: image
env:
REPOSITORY: ${{ github.repository }}
run: echo "name=ghcr.io/${REPOSITORY,,}" >> "$GITHUB_OUTPUT"

- name: Log in to GitHub Container Registry
if: env.PUBLISH_IMAGE == 'true'
Expand All @@ -55,14 +62,14 @@ jobs:
id: meta
uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
with:
images: ghcr.io/${{ github.repository }}
images: ${{ steps.image.outputs.name }}
flavor: latest=false
tags: |
type=sha,format=long

- name: Build candidate image
id: build
uses: useblacksmith/build-push-action@v2 # v7.3.0
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
with:
context: .
platforms: linux/amd64
Expand All @@ -85,7 +92,7 @@ jobs:

promote:
name: Promote the tested image
runs-on: blacksmith-2vcpu-ubuntu-2404
runs-on: ubuntu-24.04
timeout-minutes: 10
needs: [checks, publish]
if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
Expand All @@ -95,12 +102,12 @@ jobs:
packages: write

env:
IMAGE: ghcr.io/${{ github.repository }}
IMAGE: ${{ needs.publish.outputs.image }}
DIGEST: ${{ needs.publish.outputs.digest }}

steps:
- name: Check out source
uses: useblacksmith/checkout@25227e61ff9dafe400e22fa487b673eac4e4409a # v1
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false

Expand All @@ -109,6 +116,9 @@ jobs:
with:
tool: just,ripgrep

- name: Set up Docker Buildx
uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4

- name: Log in to GitHub Container Registry
uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
with:
Expand Down
12 changes: 6 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ concurrency:

jobs:
fmt:
runs-on: blacksmith-2vcpu-ubuntu-2404
runs-on: ubuntu-24.04
steps:
- name: Check out source
uses: useblacksmith/checkout@v1 # v7.0.1
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false

Expand All @@ -35,10 +35,10 @@ jobs:
run: just fmt-check

clippy:
runs-on: blacksmith-2vcpu-ubuntu-2404
runs-on: ubuntu-24.04
steps:
- name: Check out source
uses: useblacksmith/checkout@v1 # v7.0.1
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false

Expand All @@ -57,10 +57,10 @@ jobs:
run: just lint

test:
runs-on: blacksmith-2vcpu-ubuntu-2404
runs-on: ubuntu-24.04
steps:
- name: Check out source
uses: useblacksmith/checkout@v1 # v7.0.1
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false

Expand Down
125 changes: 43 additions & 82 deletions README.md

Large diffs are not rendered by default.

10 changes: 4 additions & 6 deletions compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ services:
restart: unless-stopped
init: true
environment:
RUST_LOG: ${RUST_LOG:-github_release_router=info}
SENTRY_DSN: ${SENTRY_DSN:-}
SENTRY_ENVIRONMENT: ${SENTRY_ENVIRONMENT:-production}
read_only: true
Expand All @@ -15,15 +16,12 @@ services:
volumes:
- ./config.toml:/etc/router/config.toml:ro
secrets:
- actix_github_secret
- personal_github_secret
- github_webhook_secret
- discord_webhook_url
stop_grace_period: 75s

secrets:
actix_github_secret:
file: ./secrets/actix_github_secret
personal_github_secret:
file: ./secrets/personal_github_secret
github_webhook_secret:
file: ./secrets/github_webhook_secret
discord_webhook_url:
file: ./secrets/discord_webhook_url
44 changes: 15 additions & 29 deletions config.example.toml
Original file line number Diff line number Diff line change
@@ -1,38 +1,24 @@
bind = "0.0.0.0:8080"

# A repository hook and an organization hook use the same endpoint format.
# Configure each hook with the secret for its named source.
[sources.actix]
repositories = ["actix/actix-web"]
secret = { file = "/run/secrets/actix_github_secret" }
# Replace example/app in both the allowlist and the route below.
# Configure GitHub to send releases to /webhooks/github/releases.
[sources.releases]
repositories = ["example/app"]
secret = { file = "/run/secrets/github_webhook_secret" }
# Alternative: secret = { env = "GITHUB_WEBHOOK_SECRET" }

[sources.personal]
repositories = ["robjtede/actix-web-lab"]
secret = { file = "/run/secrets/personal_github_secret" }

# This URL must belong to #web in server 771444961383153695.
# The server/channel IDs are not API parameters for incoming webhook delivery.
[destinations.web]
[destinations.releases]
webhook = { file = "/run/secrets/discord_webhook_url" }
# Alternative: webhook = { env = "DISCORD_WEBHOOK_URL" }

[[routes]]
name = "actix-web"
repository = "actix/actix-web"
# Optional. Match any of these case-insensitive regexes.
include_tags = ["^web-"] # Omit or use [] to match all tags before exclusions.
include_prereleases = false
destinations = ["web"]
name = "app-releases"
repository = "example/app"
destinations = ["releases"]

[[routes]]
name = "actix-web-lab"
repository = "robjtede/actix-web-lab"
# Optional. Match any of these case-insensitive regexes.
include_tags = ["^lab-"] # Omit or use [] to match all tags before exclusions.
# Optional. Exclude tags that match any of these case-insensitive regexes.
# exclude_tags = ["^actix-web-lab-derive-.*$"]
include_prereleases = false
destinations = ["web"]
# Optional. Prereleases are excluded by default.
# include_prereleases = true

# Add the other repository names to a source allowlist and add a route for each.
# There is no two-repository limit; four or more use the same configuration.
# Optional. All tags are allowed by default. Patterns are case-insensitive regexes.
# include_tags = ["^v[0-9]+[.][0-9]+[.][0-9]+$"]
# exclude_tags = ["-(internal|test)$"]
66 changes: 66 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Configuration

Start with [`config.example.toml`](../config.example.toml). Configuration is loaded once at startup. Restart the service after a change. Unknown fields, invalid regular expressions, and invalid references stop startup.

## Sources and destinations

A **source** defines a GitHub webhook secret and an explicit repository allowlist. Its name selects the endpoint: `[sources.releases]` accepts requests at `/webhooks/github/releases`. Source names can contain ASCII letters, digits, hyphens, and underscores.

Repository names use the `owner/name` format and match exactly, including letter case. Signed events for repositories outside the source allowlist return `403`. An authenticated GitHub ping does not need a repository, which permits organization webhook setup.

A **destination** defines a Discord webhook URL. Create a named destination for each webhook you want to use. URLs copied from Discord and URLs with `/api/v10/webhooks/` are accepted. The URL must use `https://discord.com`; suffixes such as `/github` and query strings are rejected.

## Secrets

Each secret must use exactly one reference:

```toml
secret = { file = "/run/secrets/github_webhook_secret" }
# Or: secret = { env = "GITHUB_WEBHOOK_SECRET" }

# Under a destination:
webhook = { file = "/run/secrets/discord_webhook_url" }
# Or: webhook = { env = "DISCORD_WEBHOOK_URL" }
```

Keep credential values out of TOML and source control. The service removes trailing CR/LF from secret values and preserves other bytes. Secret values and webhook URLs are excluded from application logs and queue records.

Compose mounts the two files in `secrets/` at `/run/secrets/`. For local execution, change the file references to local paths or use environment references. Add any extra secret files to the Compose service's `secrets` list and top-level `secrets` definitions, or to the Kubernetes Secret.

## Routes

Each `[[routes]]` entry needs a unique `name`, one `repository`, and one or more named `destinations`. The repository must appear in a source allowlist. All matching routes contribute destinations; overlapping routes send only one message to each destination.

To add a repository, add its `owner/name` to a source's `repositories` list and add a route:

```toml
# First add example/cli to the existing source allowlist:
# repositories = ["example/app", "example/cli"]

[[routes]]
name = "cli-releases"
repository = "example/cli"
destinations = ["releases"]
include_prereleases = true
```

Configure a repository webhook for each repository, or use an organization webhook. Reuse a source when hooks share a secret. Create a new source with an independent secret when hooks need separate credentials. Destination names can refer to webhooks in different Discord channels or servers.

## Tag filters

By default, a route allows all tags and excludes prereleases. Set `include_prereleases = true` to announce prereleases too. Only the `published` release action creates announcements.

Use optional regular expressions to select tags within a route:

```toml
include_tags = ["^app-v", "^v[0-9]+[.][0-9]+[.][0-9]+$"]
exclude_tags = ["-(internal|test)$"]
```

Patterns are case-insensitive and can match anywhere in the tag. Use `^` and `$` to match the complete tag. A tag must match at least one inclusion pattern, unless `include_tags` is omitted or empty. Any matching exclusion rejects the tag for that route. Other routes can still match.

For example, these filters include `app-v1.0.0` and `V1.0.0`, but exclude `app-v1.0.0-internal` and `APP-v1.0.0-TEST`. Omit `exclude_tags` or use `[]` to exclude no tags.

## HTTP listener

`bind` defaults to `0.0.0.0:8080`. Use an IP address and port. TLS ends at your reverse proxy. The service accepts JSON bodies up to 2 MiB and rejects content encodings so it can verify the original signed bytes.
37 changes: 37 additions & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Development and container publishing

## Local commands

Install stable Rust and `just`. The toolchain file selects stable Rust with rustfmt and Clippy. Builds use the committed `Cargo.lock`.

```sh
just fmt
just fmt-check
just lint
just test
just preview
just preview path/to/webhook.json
just run config.toml
```

Preview renders a webhook payload without configuration, credentials, or network calls. Its JSON output contains `payload` (the Discord message) and `notes` (the full attachment, when needed). Tests use in-memory queues and local fake Discord servers.

## Containers

```sh
just container-build
just container-smoke
just container-run
```

The smoke test needs Docker, OpenSSL, and ripgrep. It checks startup as a non-root user with a read-only filesystem, health, readiness, duplicate detection, state reset after restart, and SIGTERM shutdown. It uses an isolated container with no external network and removes it when done.

## GitHub Actions

The [CI workflow](../.github/workflows/ci.yml) checks formatting, Clippy, and tests. The [container workflow](../.github/workflows/build.yml) builds for `linux/amd64`. Both use standard GitHub-hosted Ubuntu runners. Pull requests build and smoke-test the image without publishing it.

A push to `main` publishes a candidate to `ghcr.io/<owner>/<repository>:sha-<full-commit>`, using the current GitHub repository name. After CI and the build pass, the promotion job smoke-tests that exact image digest and updates `:stable` and `:latest` without rebuilding. Failed checks leave those tags unchanged. Manual runs publish and promote only on `main`.

The workflow uses `GITHUB_TOKEN` with package write permission. Enable GitHub Actions and permit package publishing in the repository or organization settings. New container packages are private by default; make the package public or configure registry credentials for your deployment. See [GitHub's container registry guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).

For a registry deployment, use the digest recorded in the promotion job summary or the promoted `:stable` tag. Compose builds a local image by default; it does not pull the published image. The published image targets amd64. Build locally on another architecture.
54 changes: 54 additions & 0 deletions docs/operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Operations

## Health and logs

- `GET /healthz` returns `200` when the HTTP server is running.
- `GET /readyz` returns `200` when the delivery worker is active, or `503` otherwise. It does not check Discord connectivity.

Logs go to stderr. They include webhook decisions, delivery results, and retry attempts. They exclude credentials, webhook URLs, and request bodies. With Compose:

```sh
docker compose logs -f router
```

The default log level is `INFO`. Set `RUST_LOG=github_release_router=debug` for more delivery details. Compose passes this variable to the container. Avoid HTTP wire logging because it can expose credentials.

Sentry reporting is optional. Set `SENTRY_DSN` to enable it and `SENTRY_ENVIRONMENT` to label the deployment. Compose passes both variables through. Without a DSN, reporting is disabled. Preview does not initialize Sentry.

## Delivery and recovery

The service accepts signed GitHub release events and queues matching announcements before returning `202`. Other event types and release actions return `204`. An unmatched published release returns `202` without a job.

The queue holds up to 64 jobs, including the active request and delayed retries. If all new destinations cannot fit, the service returns `503` without adding jobs or recording the delivery ID. Redeliver the event after capacity becomes available.

One worker sends one request at a time. It waits for Discord to confirm message creation. Rate limits pause all destinations for the required delay. Network errors, HTTP `408`/`5xx`, and missing confirmation retry with exponential delay and jitter. Each job gets up to 12 attempts. Other HTTP errors fail immediately. Permanent and exhausted failures appear in the logs and in Sentry when enabled.

Keep one service instance. Queue state, cooldowns, and duplicate detection are held in memory. **Stopping the process discards pending jobs and recent delivery history.** HTTP `202` does not guarantee delivery. A lost response or a redelivery after restart can create a duplicate announcement.

Delivery IDs and successful `(repository, release ID, destination)` keys are each retained for up to 30 days, with a limit of 4,096 entries per cache. Active jobs stay deduplicated until completion. Edits are not reposted while a release key is retained.

To recover a failed delivery or one lost during a restart:

1. Fix the cause shown in the service logs.
2. Open the repository or organization webhook's **Recent deliveries** in GitHub.
3. Select the event and choose **Redeliver**.
4. Check the logs for a successful Discord delivery.

Failed destinations can be retried by redelivery. Successful destinations remain deduplicated while their keys are cached.

## Updates and shutdown

After changing configuration, recreate the service:

```sh
docker compose up --build -d --force-recreate --wait
curl --fail http://127.0.0.1:8080/readyz
```

Use `docker compose stop` to stop it. On SIGINT or SIGTERM, the service stops intake and waits for the active send to finish. An outgoing request has a 5-second connect timeout and a 30-second total timeout. Pending jobs and retries do not drain during shutdown. Before a planned restart, check delivery logs and allow accepted work to finish. Redeliver lost events afterward.

## Message format

Each announcement includes a linked release title, repository name, and notes. The tag is the fallback title when the release has no name. Supported Markdown is retained, and all mention parsing is disabled.

Notes that exceed the embed description limit use an excerpt and a complete `release-notes.md` attachment. Unicode truncation preserves character boundaries. The input body limit also bounds the attachment size.
8 changes: 4 additions & 4 deletions examples/release.json
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
{
"action": "published",
"repository": { "full_name": "actix/actix-web" },
"repository": { "full_name": "example/app" },
"release": {
"id": 123456,
"tag_name": "web-v4.0.0",
"name": "Actix Web 4.0.0",
"html_url": "https://github.com/actix/actix-web/releases/tag/web-v4.0.0",
"tag_name": "v1.0.0",
"name": "App 1.0.0",
"html_url": "https://github.com/example/app/releases/tag/v1.0.0",
"published_at": "2026-09-24T10:00:00Z",
"prerelease": false,
"body": "## Changes\n\n- Improve request handling.\n- Fix an edge case.\n\nThank you to all contributors!"
Expand Down
2 changes: 1 addition & 1 deletion justfile
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ container-build:
docker build -t github-release-router:local .

container-run:
docker compose up --build -d
docker compose up --build -d --wait

# Requires Docker, OpenSSL, and ripgrep. Uses no external network.
container-smoke image="github-release-router:local":
Expand Down
Loading