managarten/docs/DISCORD_NOTIFICATIONS_SETUP.md

Discord Notifications Setup

This guide shows you how to set up Discord notifications for daily test results.

Quick Setup (5 minutes)

1. Create Discord Webhook

1. Open your Discord server
2. Go to Server Settings → Integrations → Webhooks
3. Click New Webhook
4. Configure:
   • Name: Mana CI/CD (or whatever you prefer)
   • Channel: Select the channel for test notifications (e.g., #dev-alerts)
   • Avatar: Optional - upload a custom icon
5. Click Copy Webhook URL

2. Add Webhook to GitHub Secrets

1. Go to your GitHub repository
2. Navigate to Settings → Secrets and variables → Actions
3. Click New repository secret
4. Add:
   • Name: DISCORD_WEBHOOK_URL
   • Value: Paste the webhook URL from Discord
5. Click Add secret

3. That's It!

The workflow will now send Discord notifications automatically:

• Failure notifications: Always sent when tests fail
• Success notifications: Optional (enable via manual workflow trigger)

---

What You'll Receive

Failure Notification

When tests fail, you'll get a red embed:

❌ Daily Tests Failed
The daily test suite encountered failures and needs attention.

📅 Date: 2025-12-26
📊 Coverage: 87.5%
🔗 Workflow Run: [View Details](link)

Color: Red (#E74C3C)

Success Notification (Optional)

When tests pass and you enable success notifications:

✅ Daily Tests Passed
All tests completed successfully!

📅 Date: 2025-12-26
📊 Coverage: 95.3%
✅ Tests: 180 passed
🔗 Workflow Run: [View Details](link)

Color: Green (#2ECC71)

---

Advanced Configuration

Enable Success Notifications

By default, only failures send Discord notifications. To get success notifications:

1. Go to Actions → Daily Tests workflow
2. Click Run workflow
3. Check the box: Send Discord notification on success
4. Run workflow

Customize Notification Content

Edit .github/workflows/daily-tests.yml and modify the Discord webhook payload:

- name: Send Discord notification
  run: |
    curl -X POST "$DISCORD_WEBHOOK_URL" \
      -H 'Content-Type: application/json' \
      -d '{
        "username": "Your Custom Name",
        "avatar_url": "https://your-custom-avatar.png",
        "embeds": [{
          "title": "Custom Title",
          "description": "Custom description",
          "color": 15158332,
          ...
        }]
      }'

Change Notification Channel

In Discord:

1. Server Settings → Integrations → Webhooks
2. Find Mana CI/CD webhook
3. Change Channel dropdown
4. Save

The GitHub secret stays the same - no need to update!

Add Multiple Channels

To send to multiple Discord channels:

1. Create multiple webhooks in Discord (one per channel)
2. Add multiple secrets to GitHub:
   • DISCORD_WEBHOOK_URL_ALERTS
   • DISCORD_WEBHOOK_URL_TEAM
   • DISCORD_WEBHOOK_URL_DEVOPS
3. Duplicate the Discord notification step in the workflow for each webhook

---

Discord Webhook URL Format

The webhook URL should look like:

https://discord.com/api/webhooks/[WEBHOOK_ID]/[WEBHOOK_TOKEN]

Security: Never commit this URL to git! Always use GitHub Secrets.

---

Troubleshooting

Notifications Not Appearing

1. Check webhook is active:

   • Discord → Server Settings → Integrations → Webhooks
   • Verify webhook exists and is enabled

2. Check GitHub secret:

   • GitHub → Settings → Secrets → DISCORD_WEBHOOK_URL
   • Verify secret exists and is spelled correctly

3. Check workflow logs:

   • GitHub Actions → Daily Tests → Latest run
   • Look for "Send Discord notification" step
   • Check for curl errors

Rate Limiting

Discord webhooks are rate-limited to:

• 30 requests per minute per webhook
• 5 requests per 2 seconds burst

Our daily workflow sends 1-2 notifications per day, well within limits.

Testing Your Webhook

Test the webhook without running the full workflow:

# Replace with your actual webhook URL
WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE"

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "Test Bot",
    "content": "This is a test message from curl!"
  }'

If you see the message in Discord, your webhook works!

---

Slack + Discord Together

You can use both Slack and Discord notifications simultaneously:

1. Add both secrets:

   • DISCORD_WEBHOOK_URL
   • SLACK_WEBHOOK_URL

2. The workflow checks for both and sends to whichever exists

---

Discord Embed Colors

The workflow uses these colors:

Status	Color	Hex
❌ Failure	Red	#E74C3C (15158332)
✅ Success	Green	#2ECC71 (3066993)

To customize, change the "color" field in the workflow.

---

Security Best Practices

1. ✅ Do: Store webhook URL in GitHub Secrets
2. ✅ Do: Use a dedicated Discord channel for CI/CD
3. ✅ Do: Restrict webhook permissions if possible
4. ❌ Don't: Commit webhook URLs to git
5. ❌ Don't: Share webhook URLs publicly
6. ❌ Don't: Use webhooks with admin permissions

---

Example: Full Setup

# 1. Create Discord webhook
Discord → Server Settings → Integrations → Create Webhook
Channel: #dev-alerts
Copy URL: https://discord.com/api/webhooks/123456789/abcdefg

# 2. Add to GitHub
GitHub → Settings → Secrets → New secret
Name: DISCORD_WEBHOOK_URL
Value: https://discord.com/api/webhooks/123456789/abcdefg

# 3. Test (optional)
GitHub Actions → Daily Tests → Run workflow

# 4. Done!
Wait for next daily run (2 AM UTC) or trigger manually

---

Support

For issues with:

• Discord webhooks: Discord API Docs
• GitHub Actions: GitHub Actions Docs
• This workflow: See docs/TESTING_GUIDE.md

---

🏗️ Mana Monorepo