Discord Webhook Setup Guide

This guide explains how to set up Discord notifications for git pushes to the Lantern repository.

Overview

The Lantern repository uses GitHub Actions to automatically send Discord notifications whenever code is pushed to the main or dev branches. These notifications include:

• Branch name
• Commit message
• Author information
• Direct link to the commit
• Timestamp

Step 1: Create a Discord Webhook

1. Open your Discord server where you want to receive notifications
2. Navigate to Server Settings
   • Click on the server name dropdown
   • Select "Server Settings"
3. Go to Integrations
   • In the left sidebar, click "Integrations"
4. Create a Webhook
   • Click "Webhooks" (or "View Webhooks" if you already have some)
   • Click "New Webhook" or "Create Webhook"
5. Configure the Webhook
   • Name: GitHub Notifications (or any name you prefer)
   • Channel: Select the channel where you want notifications to appear (e.g., #dev-updates, #commits)
   • Optionally, you can customize the webhook's avatar
6. Copy the Webhook URL
   • Click "Copy Webhook URL"
   • Important: Keep this URL secret! Anyone with this URL can send messages to your Discord channel

Step 2: Add the Webhook to GitHub Secrets

1. Go to your GitHub repository
   • Navigate to https://github.com/cattreedev/lantern_app
2. Open Settings
   • Click the "Settings" tab (you need admin/write access)
3. Navigate to Secrets
   • In the left sidebar, expand "Secrets and variables"
   • Click "Actions"
4. Create a New Secret
   • Click "New repository secret"
   • Name: DISCORD_WEBHOOK_URL (must be exactly this)
   • Value: Paste the Discord webhook URL you copied in Step 1
   • Click "Add secret"

Step 3: Verify the Setup

The workflow is already configured in .github/workflows/discord-notify.yml. To test it:

1. Make a test commit to the dev or main branch
2. Check the Actions tab on GitHub
   • Go to https://github.com/cattreedev/lantern_app/actions
   • You should see a "Discord Notification" workflow run
3. Check your Discord channel
   • A notification should appear with the commit details

Notification Format

Main Branch (Blue)

When a commit is pushed to main, the notification will have a blue embed color (#5865F2).

Dev Branch (Green)

When a commit is pushed to dev, the notification will have a green embed color (#57F287).

Notification Content

Each notification includes:

• Repository name
• Branch name
• Commit count (e.g., "1 commit" or "3 commits")
• For each commit:
  • Commit author
  • Commit SHA (shortened to 7 characters, clickable link)
  • Full commit message
• Clickable title that links to the compare view showing all changes
• Timestamp
• Pusher name in the footer

Multiple Commits: When multiple commits are pushed at once, all commits are displayed in a single notification, separated by horizontal rules (---). Each commit shows its own author, SHA, and message.

Troubleshooting

Notifications not appearing

1. Check the Actions tab on GitHub to see if the workflow ran

   • If it didn't run: Verify the workflow file is in .github/workflows/ and named discord-notify.yml
   • If it failed: Click on the failed run to see error details

2. Verify the secret is set correctly

   • The secret name must be exactly DISCORD_WEBHOOK_URL
   • The webhook URL should start with https://discord.com/api/webhooks/

3. Check Discord webhook settings

   • Ensure the webhook hasn't been deleted in Discord
   • Verify the channel still exists

Workflow not triggering

• The workflow only triggers on pushes to main or dev branches
• Pushes to other branches (e.g., feature branches) won't trigger notifications
• Pull requests don't trigger this workflow

Notification appears but content is wrong

• Check the workflow file .github/workflows/discord-notify.yml
• Verify the GitHub Actions context variables are being used correctly

Customization

To customize the notifications, edit .github/workflows/discord-notify.yml:

• Change trigger branches: Modify the branches: list under on: push:
• Change colors: Modify the embed-color value (hex color codes)
• Change message format: Modify the embed-description section
• Add more information: Use GitHub Actions context variables (see GitHub Actions Contexts)

Security Notes

• Never commit the webhook URL to the repository
• The webhook URL is stored as a GitHub secret and is not visible in logs
• Only repository administrators can view or modify secrets
• If the webhook URL is compromised, delete it in Discord and create a new one

References

• Discord Webhook Documentation
• GitHub Actions Secrets
• tsickert/discord-webhook Action