actions/github-releases-to-discord
1
0
Fork 0
mirror of https://github.com/SethCohen/github-releases-to-discord synced 2026-09-07 20:03:23 +00:00
Code Packages Releases Activity
Files
master
github-releases-to-discord/README.md
T

232 lines
8.2 KiB
Markdown
Raw Permalink Blame History

# GitHub Releases to Discord Action
Easily notify your Discord community about new GitHub releases! This GitHub Action automatically sends a beautifully formatted Discord embed message with your release notes whenever you publish a release on GitHub.
**Main Benefits:**
- Instantly share release changelogs with your Discord server.
- Highly customizable message appearance and content.
- Simple setup—no coding required.
- Supports advanced formatting and filtering for professional notifications.
---
## Features
- **Automatic Release Notifications:** Sends a Discord embed when a GitHub release is published.
- **Clean Formatting:**
- Removes carriage returns and HTML comments.
- Optimizes whitespace and paragraph spacing.
- **Mention & Link Handling:**
- Converts `@mentions` to clickable GitHub profile links.
- Converts PR, issue, and changelog URLs to Markdown links.
- Optionally removes PR, commit, and issue links for cleaner messages.
- **Heading Reduction:**
- Optionally reduces heading sizes for compact display.
- **Custom Embed Appearance:**
- Set color, username, avatar, footer, and more.
- **Length Management:**
- Ensures messages fit Discord's embed limits, trimming and linking as needed.
- **Error Handling:**
- Clear errors for missing or invalid inputs.
- **Easy Integration:**
- Works with any public or private repository.
---
## Quick Start
### 1. Create a Discord Webhook
- Go to your Discord server settings → **Integrations** → **Webhooks**.
- Click **Create Webhook** and copy the webhook URL.
### 2. Add the Action to Your Workflow
Create (or update) `.github/workflows/github-releases-to-discord.yml`:
```yaml
on:
release:
types: [published]
jobs:
github-releases-to-discord:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: GitHub Releases to Discord
uses: SethCohen/github-releases-to-discord@v1
with:
webhook_url: ${{ secrets.WEBHOOK_URL }}
color: "2105893"
username: "Release Changelog"
avatar_url: "https://cdn.discordapp.com/avatars/487431320314576937/bd64361e4ba6313d561d54e78c9e7171.png"
content: "||@everyone||"
footer_title: "Changelog"
reduce_headings: true
```
### 3. Optional: Test with `workflow_dispatch`
If you want to test the action manually without relying on cloning and using `act`, you can add `workflow_dispatch` and pass release fields into the action:
Example inputs:
```yaml
release_name: v1.2.3
release_body: |
## Changes
- Added manual testing support
- Verified Discord webhook output
release_html_url: https://github.com/owner/repo/releases/tag/v1.2.3
```
```yaml
on:
release:
types: [published]
workflow_dispatch:
inputs:
release_name:
description: Release title to post
required: true
release_body:
description: Release notes body to post
required: true
release_html_url:
description: Release URL to link in Discord
required: false
jobs:
github-releases-to-discord:
runs-on: ubuntu-latest
steps:
- name: GitHub Releases to Discord
uses: SethCohen/github-releases-to-discord@v1
with:
webhook_url: ${{ secrets.WEBHOOK_URL }}
release_name: ${{ inputs.release_name }}
release_body: ${{ inputs.release_body }}
release_html_url: ${{ inputs.release_html_url }}
```
### 4. Add Your Webhook URL as a Secret
- In your GitHub repo, go to **Settings → Secrets and variables → Actions**.
- Add a new secret named `WEBHOOK_URL` and paste your Discord webhook URL.
---
## Configuration Options
| Input Name | Required | Default | Description |
|--------------------------------|----------|-------------|--------------------------------------------------------------------|
| `webhook_url` | ✔ | | Discord webhook URL (use a GitHub secret). |
| `color` | ❌ | 2105893 | Embed color (decimal). |
| `username` | ❌ | | Webhook username. |
| `avatar_url` | ❌ | | Webhook avatar image URL. |
| `custom_html_url` | ❌ | | Custom URL for the embed title (overrides GitHub release URL). |
| `content` | ❌ | | Additional message content (e.g., `@everyone`). |
| `release_name` | ❌ | | Manual release title for `workflow_dispatch` testing. |
| `release_body` | ❌ | | Manual release body for `workflow_dispatch` testing. |
| `release_html_url` | ❌ | | Manual release URL for `workflow_dispatch` testing. |
| `footer_title` | ❌ | | Footer title. |
| `footer_icon_url` | ❌ | | Footer icon image URL. |
| `footer_timestamp` | ❌ | false | Show timestamp in footer (`true`/`false`). |
| `max_description` | ❌ | 4096 | Max description length (Discord limit: 4096). |
| `remove_github_reference_links`| ❌ | false | Remove PR, commit, and issue links from the description. |
| `reduce_headings` | ❌ | false | Reduce heading sizes for compact display. |
---
## Example Output
![Discord Embed Example](https://i.imgur.com/ovr0gTL.png)
---
## Best Practices & Notes
- **Use Secrets for Webhook URLs:** Never commit your Discord webhook URL directly to your repository.
- **Discord Embed Limits:**
- Title: 256 characters max
- Description: 4096 characters max
- The action will trim and link if limits are exceeded.
- **Release Body Formatting:**
- Use Markdown in your release notes for best results.
- **Private Repos:**
- The action works for both public and private repositories.
- **Manual Testing:**
- Use `release_name`, `release_body`, and optionally `release_html_url` when triggering the workflow with `workflow_dispatch`.
---
## Troubleshooting & FAQ
**Q: The action didn't post to Discord!**
- Check that your webhook URL is correct and not expired.
- Ensure the `webhook_url` secret is set in your repository.
- Review the Actions log for error messages.
**Q: My message is cut off.**
- Discord has strict embed limits. The action trims long messages and adds a link if needed.
**Q: How do I customize the embed?**
- Use the configuration options above to set color, username, avatar, footer, and more.
**Q: Can I mention everyone or specific roles?**
- Use the `content` input (e.g., `content: "@everyone"`).
---
## Contributing
We welcome contributions! To get started:
1. **Fork** this repository.
2. **Clone** your fork and run `npm install`.
3. **Create a test release payload:**
- Copy `tests/sample-test-release.json` and edit as needed.
4. **Create a `.env` file** in the root with your webhook and config (see below):
```env
INPUT_WEBHOOK_URL=your_webhook_url
INPUT_COLOR=2105893
...
```
5. **Test locally** with [`act`](https://github.com/nektos/act):
```bash
act release -e tests/sample-test-release.json
```
6. **Make your changes** and commit using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
7. **Open a pull request** with a clear description of your changes.
---
## License
[MIT License](LICENSE)
---
## Support & Feedback
- **Issues:** [Open an issue](https://github.com/SethCohen/github-releases-to-discord/issues) for bugs, questions, or feature requests.
- **Pull Requests:** Contributions are welcome—see above!
---
## Acknowledgements
- Inspired by the needs of open source maintainers and Discord communities.
- Built and maintained by [SethCohen](https://github.com/SethCohen).
View Git Blame Copy Permalink