Debian Codegraph @

docs/usage/github-action/index.md

raw
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.