Discord Notification Workflow

Status: ✅ Production
Workflow File: .github/workflows/discord-notify.yml
Type: Push notification automation
Triggers: Commits to main, dev, and all branches (for testing)

---

Overview

The Discord Notification workflow automatically sends commit notifications to a Discord channel whenever code is pushed to the repository. This keeps the team informed of code changes in real-time without requiring manual updates.

Key Features:

• Multi-commit support: Shows all commits when multiple are pushed at once
• Commit count in title (e.g., "3 commits")
• Shows commit message, author, and shortened SHA for each commit
• Direct links to each commit on GitHub
• Color-coded by branch:
  • Blue (#5865F2) for main branch
  • Green (#57F287) for dev branch
• Timestamp of push
• Commits separated by horizontal rules for clarity
• Notification history tracking to avoid duplicate messages

---

Quick Setup

1. Create Discord Webhook

1. Open Discord Server Settings → Integrations → Webhooks
2. Click "New Webhook"
3. Name: GitHub Notifications
4. Select channel where notifications should appear (e.g., #dev-updates)
5. Copy the webhook URL

2. Add GitHub Secrets

1. Go to GitHub repository secrets
2. Click "New repository secret"
3. Name: DISCORD_WEBHOOK_COMMITS
4. Value: Paste the production commit-notification webhook URL (used on dev/main)
5. (Optional) Add DISCORD_WEBHOOK_TEST for feature branches if you want non-prod pushes in a separate channel
6. Click "Add secret"

3. Test

Push a commit to dev or main branch:

git commit -m "Test Discord notification"
git push origin dev

Then check:

• GitHub Actions tab for workflow status
• Your Discord channel for the notification

---

Notification Behavior

When Notifications Fire

• Any push to main branch
• Any push to dev branch
• Any push to any other branch (useful for testing or feature branch tracking)

What Gets Notified

Per Commit:

• Commit message
• Author name
• Shortened commit SHA (7 characters)
• Link to commit on GitHub

Per Push:

• Total commit count
• Branch name
• Timestamp

Avoiding Duplicates

The workflow maintains a notification history in git to prevent sending the same commit notification twice. This is stored in .github-workflow-state/notified-commits.txt and persists across workflow runs.

---

Troubleshooting

Notifications Not Appearing

Check:

1. Secret exists: Verify DISCORD_WEBHOOK_COMMITS (and DISCORD_WEBHOOK_TEST if used) are set in GitHub secrets
2. Webhook URL valid: Test by sending a test message via Discord webhook
3. Permissions: Ensure bot/webhook has permission to post in the target channel
4. Branches: Ensure you're pushing to main or dev (or another branch if configured)

Duplicate Notifications

1. The workflow includes deduplication logic—duplicates should not occur
2. If duplicates happen, check .github-workflow-state/notified-commits.txt in git history
3. May need to reset notification history by removing that file from git

Wrong Channel

1. Verify the webhook URL points to the correct Discord channel
2. Update the webhook URL in GitHub secrets if the channel changed

---

Configuration

Environment Variables (in Workflow)

No environment variables—all configuration is via:

• DISCORD_WEBHOOK_COMMITS secret (required for dev/main)
• DISCORD_WEBHOOK_TEST secret (optional for non-prod branches)
• Workflow trigger branches (currently main, dev, **)

Customization

To change notification content or formatting:

• Edit .github/workflows/discord-notify.yml
• Modify the "Prepare commit messages" step to change message format
• Modify the "Send to Discord" step to change embed styling

To add more branches:

• Edit the on.push.branches section in .github/workflows/discord-notify.yml

---

Related Documentation

• Discord Webhooks Setup Guide — Detailed setup and troubleshooting
• Discord Bot Documentation — For the full Discord bot service (separate from this workflow)

---

Testing Locally

There is no local testing needed for this workflow—it only runs on GitHub Actions when code is pushed.

To test the webhook URL:

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Test message",
    "embeds": [{
      "title": "Test Commit",
      "description": "This is a test notification"
    }]
  }'

---

Maintenance

Regular Checks

• Monthly: Verify webhook URL is still valid and bot still has permissions
• On channel changes: Update webhook URL in GitHub secrets

Updating the Workflow

If modifying the workflow, test on a non-production branch first:

git checkout -b test/discord-workflow
# Make changes to .github/workflows/discord-notify.yml
git push origin test/discord-workflow
# Verify notifications work
# Then merge to dev and main

---

Related Files

.github/workflows/
  ├── discord-notify.yml           # Workflow definition
.github/workflow-state/
  └── notified-commits.txt         # Notification history (auto-managed)
docs/engineering/github/workflows/
  ├── DISCORD_NOTIFICATION.md      # This file
  ├── discord/
  │   └── IMPLEMENTATION_SUMMARY.md # Quick reference
  └── testing/
      └── (See testing docs for workflow validation)