| 1 |
# Using Shoutrrr as a GitHub Action |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
The Shoutrrr GitHub Action (`nicholas-fedor/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. |
| 6 |
|
| 7 |
## Usage |
| 8 |
|
| 9 |
Add the action to your `.github/workflows` YAML file. |
| 10 |
|
| 11 |
```yaml title="Workflow Syntax Example" |
| 12 |
- name: Shoutrrr |
| 13 |
uses: nicholas-fedor/shoutrrr-action@v1 |
| 14 |
with: |
| 15 |
url: <SERVICE_URL> |
| 16 |
title: <NOTIFICATION_TITLE> |
| 17 |
message: <NOTIFICATION_MESSAGE> |
| 18 |
``` |
| 19 |
|
| 20 |
| Input | Description | Required | |
| 21 |
|-----------|-----------------------------------------------------------------------------------------------|----------| |
| 22 |
| `url` | The Shoutrrr service URL (e.g., `discord://token@webhookid`). Use secrets for sensitive data. | Yes | |
| 23 |
| `title` | The notification title (optional, for services that support it). | No | |
| 24 |
| `message` | The notification message body. | Yes | |
| 25 |
|
| 26 |
!!! Note |
| 27 |
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 }}`). |
| 28 |
|
| 29 |
## Examples |
| 30 |
|
| 31 |
<!-- markdownlint-disable --> |
| 32 |
### Send Notification on Push to Main |
| 33 |
|
| 34 |
!!! Example |
| 35 |
```yaml title="Deploy Workflow with Shoutrrr" |
| 36 |
name: Deploy |
| 37 |
on: |
| 38 |
push: |
| 39 |
branches: |
| 40 |
- main |
| 41 |
|
| 42 |
jobs: |
| 43 |
build: |
| 44 |
runs-on: ubuntu-latest |
| 45 |
steps: |
| 46 |
- [Your other workflow steps] |
| 47 |
|
| 48 |
- name: Shoutrrr |
| 49 |
uses: nicholas-fedor/shoutrrr-action@v1 |
| 50 |
with: |
| 51 |
url: ${{ secrets.SHOUTRRR_URL }} |
| 52 |
title: Deployed ${{ github.sha }} |
| 53 |
message: See changes at ${{ github.event.compare }}. |
| 54 |
``` |
| 55 |
|
| 56 |
```text title="Expected Output (Success)" |
| 57 |
Notification sent |
| 58 |
``` |
| 59 |
|
| 60 |
### Send on Pull Request with Custom Message |
| 61 |
|
| 62 |
!!! Example |
| 63 |
```yaml title="PR Workflow with Shoutrrr" |
| 64 |
name: PR Notification |
| 65 |
on: |
| 66 |
pull_request: |
| 67 |
types: [opened, synchronize] |
| 68 |
|
| 69 |
jobs: |
| 70 |
notify: |
| 71 |
runs-on: ubuntu-latest |
| 72 |
steps: |
| 73 |
- name: Shoutrrr |
| 74 |
uses: nicholas-fedor/shoutrrr-action@v1 |
| 75 |
with: |
| 76 |
url: ${{ secrets.DISCORD_URL }} |
| 77 |
title: New PR #${{ github.event.number }} |
| 78 |
message: "${{ github.event.pull_request.title }} by ${{ github.actor }}: ${{ github.event.pull_request.html_url }}" |
| 79 |
``` |
| 80 |
|
| 81 |
```text title="Expected Output (Success)" |
| 82 |
Notification sent |
| 83 |
``` |
| 84 |
|
| 85 |
### Send on Failure with Verbose Logging |
| 86 |
|
| 87 |
!!! Example |
| 88 |
```yaml title="Failure Notification with Verbose" |
| 89 |
name: Build |
| 90 |
on: [push] |
| 91 |
jobs: |
| 92 |
build: |
| 93 |
runs-on: ubuntu-latest |
| 94 |
steps: |
| 95 |
- [Build steps] |
| 96 |
|
| 97 |
- name: Notify on Failure |
| 98 |
if: failure() |
| 99 |
uses: nicholas-fedor/shoutrrr-action@v1 |
| 100 |
with: |
| 101 |
url: ${{ secrets.SLACK_URL }} |
| 102 |
title: Build Failed |
| 103 |
message: "Build failed for ${{ github.ref }}. Check logs: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" |
| 104 |
``` |
| 105 |
|
| 106 |
```text title="Expected Output (Success)" |
| 107 |
Notification sent |
| 108 |
``` |
| 109 |
<!-- markdownlint-restore --> |
| 110 |
|
| 111 |
## Notes |
| 112 |
|
| 113 |
- **Error Handling**: If sending fails, the action logs errors and may fail the step. Use `continue-on-error: true` if needed. |
| 114 |
- **Parameters**: The action passes `title` and `message` to `shoutrrr send`. For service-specific params, embed them in the URL. |
| 115 |
- **Timeouts**: Inherits Shoutrrr's 10-second send timeout. |
| 116 |
- **Digest Pinning**: Pin to a specific SHA digest (e.g., `@caad2fd0be5099bbc16825bc8f71f9ff8e544ffe`) to maintain security best practices. |