github-workflows

Shared GitHub Actions workflows for release-failure notifications.

What this repository provides

• A reusable workflow that sends release-failure alerts with Shoutrrr.
• A Telegram Bot delivery path using a single SHOUTRRR_URL secret per caller repository.
• A thin caller-workflow template for repositories that need failure notifications.
• A helper script to batch-sync the same SHOUTRRR_URL secret across multiple repositories.

Repository layout

• .github/workflows/release-failure-telegram.yml — reusable workflow and manual smoke-test entrypoint.
• templates/workflows/notify-release-failure.yml — thin caller workflow template for other repositories.
• scripts/sync-shoutrrr-secret.sh — batch sync helper for the SHOUTRRR_URL secret.
• docs/specs/ — implementation spec and acceptance criteria for this repository.

Setup

1. Create a Telegram bot

1. Talk to @BotFather and create a dedicated bot.
2. Save the bot token.
3. Decide whether alerts should go to a private chat or a private group.

2. Resolve the target chat ID

Preferred: use Shoutrrr's interactive generator.

docker run --rm -it containrrr/shoutrrr generate telegram

Alternative: forward a message to @shoutrrrbot, or add @shoutrrrbot to the target group and mention it once so it can return the chat ID.

3. Build the secret value

Format the service URL like this:

telegram://<BOT_TOKEN>@telegram?chats=<CHAT_ID>

Optional Telegram parameters can be appended to the URL, for example:

telegram://<BOT_TOKEN>@telegram?chats=<CHAT_ID>&preview=false

4. Make this repository callable from your other private repositories

In this repository's GitHub settings:

1. Open Settings -> Actions -> General.
2. Find the Access section.
3. Choose Accessible from repositories owned by '<YOUR_USERNAME>' user.

5. Distribute the same secret to caller repositories

You can sync the same secret into multiple repositories with the helper script:

export SHOUTRRR_URL='telegram://<BOT_TOKEN>@telegram?chats=<CHAT_ID>'
./scripts/sync-shoutrrr-secret.sh --repo repo-a --repo repo-b

To target every non-archived repository for the authenticated user:

export SHOUTRRR_URL='telegram://<BOT_TOKEN>@telegram?chats=<CHAT_ID>'
./scripts/sync-shoutrrr-secret.sh --all

6. Add the thin caller workflow to each repository

Copy templates/workflows/notify-release-failure.yml into the caller repository at:

.github/workflows/notify-release-failure.yml

Then customize:

• YOUR_USERNAME to your GitHub username.
• the watched workflow names under on.workflow_run.workflows.
• the ref_label expression if your release workflow is tag-driven and you want a custom label.
• keep the built-in workflow_dispatch entrypoint so each caller repository can run a safe notifier smoke test after setup or secret rotation.

How the reusable workflow works

• It is triggered through workflow_call from a caller repository.
• It also supports workflow_dispatch for a manual smoke test in this repository.
• The caller passes workflow metadata and the SHOUTRRR_URL secret.
• The reusable workflow formats a Telegram-friendly message whose first line is an emoji-prefixed status plus repository name, then sends it with containrrr/shoutrrr-action@v1.
• The thin caller template also supports workflow_dispatch, which sends a smoke-test message without waiting for a real release failure.

Security notes

• Use a dedicated Telegram bot for CI alerts.
• Keep the full Shoutrrr URL only in SHOUTRRR_URL secrets.
• The notifier workflow should never check out or execute untrusted code, because workflow_run triggered workflows can access secrets and write-capable tokens.
• For private-chat delivery, the destination user must start the bot first. For group delivery, add the bot to the group before testing.

Manual smoke test

After pushing this repository to GitHub and setting the SHOUTRRR_URL secret here, open the Release failure Telegram notifier workflow and use Run workflow.

Suggested test inputs:

• repository: your-user/example-repo
• workflow_name: Release
• conclusion: failure
• run_url: a real or placeholder GitHub Actions URL
• ref_label: tag: v0.1.0

Limitations

• Each caller repository still needs one local workflow_run notifier file. GitHub does not support subscribing to other repositories' workflow events globally.
• The workflow_run notifier file must exist on the caller repository's default branch.
• This repository can be shared directly with your own private repositories. Public repositories may need a different sharing strategy if you want to keep this repository private.