Using Shoutrrr as a GitHub Action

Overview

The Shoutrrr GitHub Action (circa10a/shoutrrr-action) integrates Shoutrrr into your workflows to send notifications using service URLs. It supports all Shoutrrr services and allows dynamic messaging with GitHub context variables.

Usage

Add the action to your .github/workflows YAML file.

Workflow Syntax Example

- name: Shoutrrr
  uses: circa10a/shoutrrr-action@v1
  with:
    url: <SERVICE_URL>
    title: <NOTIFICATION_TITLE>
    message: <NOTIFICATION_MESSAGE>

Input	Description	Required
url	The Shoutrrr service URL (e.g., discord://token@webhookid). Use secrets for sensitive data.	Yes
title	The notification title (optional, for services that support it).	No
message	The notification message body.	Yes

Note

Use GitHub secrets for URLs containing tokens. The action uses shoutrrr send internally, supporting all services like discord, slack, telegram, etc. Messages can include GitHub variables (e.g., ${{ github.sha }}).

Examples

Send Notification on Push to Main

Example

Deploy Workflow with Shoutrrr

name: Deploy
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - [Your other workflow steps]

      - name: Shoutrrr
        uses: circa10a/shoutrrr-action@v1
        with:
          url: ${{ secrets.SHOUTRRR_URL }}
          title: Deployed ${{ github.sha }}
          message: See changes at ${{ github.event.compare }}.

Expected Output (Success)

Notification sent

Send on Pull Request with Custom Message

Example

PR Workflow with Shoutrrr

name: PR Notification
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Shoutrrr
        uses: circa10a/shoutrrr-action@v1
        with:
          url: ${{ secrets.DISCORD_URL }}
          title: New PR #${{ github.event.number }}
          message: "${{ github.event.pull_request.title }} by ${{ github.actor }}: ${{ github.event.pull_request.html_url }}"

Expected Output (Success)

Notification sent

Send on Failure with Verbose Logging

Example

Failure Notification with Verbose

name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - [Build steps]

      - name: Notify on Failure
        if: failure()
        uses: circa10a/shoutrrr-action@v1
        with:
          url: ${{ secrets.SLACK_URL }}
          title: Build Failed
          message: "Build failed for ${{ github.ref }}. Check logs: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

Expected Output (Success)

Notification sent

Notes

• Error Handling: If sending fails, the action logs errors and may fail the step. Use continue-on-error: true if needed.
• Parameters: The action passes title and message to shoutrrr send. For service-specific params, embed them in the URL.
• Timeouts: Inherits Shoutrrr's 10-second send timeout.
• Digest Pinning: Pin to a specific SHA digest (e.g., @caad2fd0be5099bbc16825bc8f71f9ff8e544ffe) to maintain security best practices.