Diagnosing Missing GitHub Notifications in a Gitter Room

Problem Statement

GitHub pushes events (push, pull‑request, issue, etc.) to a Gitter room via a webhook. When those messages no longer appear in the room, the problem is often not in GitHub but in the Gitter integration or the network path that carries the payload. This guide helps you pinpoint the root cause and apply the correct fix.

Diagnostic Flow

Use the table below to match the symptoms you observe with the most likely cause. Then follow the ordered checks to confirm or rule out each possibility.

Symptom	Probable Cause	Primary Check
No events at all	Missing or expired GitHub token	Verify token in Gitter integration settings
Only some events (e.g., pushes) appear	Webhook payload filter blocking certain event types	Inspect webhook filter rules
Messages appear but are blank or contain errors	Room permissions disallow bot messages	Check room member roles
Room shows "…waiting for events…" or no activity log	Outbound network blocked (firewall, proxy)	Test connectivity to github.com

Step 1 – Verify the GitHub Integration Token

1. Log into Gitter as an administrator of the target room.
2. Navigate to Room Settings → Integrations → GitHub.
3. Check the Token field. It should contain a non‑empty string and be marked as active. If the token appears blank or expired, generate a new one in GitHub:
   • Go to Settings → Developer settings → Personal access tokens.
   • Create a token with the repo and notifications scopes.
   • Copy the token exactly as displayed.
   • Paste it into the Gitter integration field and save.
4. After saving, Gitter will attempt to validate the token. A successful validation shows a green checkmark.
5. Risk: If you revoke the token after changing your GitHub password, Gitter will silently fail until you update it.
6. Check: Send a test event from GitHub (e.g., push a commit) and confirm the message appears.

Step 2 – Inspect Webhook Payload Filters

1. In the same GitHub integration page, locate the Payload Filters section.
2. By default, Gitter may filter out events that are not explicitly allowed. Verify that the event types you expect (e.g., push, pull_request) are listed or that the filter is set to All.
3. Example filter rule to allow only pushes and PRs:

   event_types: push,pull_request

4. After adjusting, click Save and trigger a test event.
5. Check the Webhook Logs under Room Settings → Integrations → GitHub → Logs for the payload. A 200 OK response indicates the filter passed.
6. Risk: Over‑restrictive filters can silently drop legitimate events.

Step 3 – Confirm Room Permissions for Bots

1. Navigate to Room Settings → Members.
2. Find the Gitter Bot (often listed as gitter-bot@).
3. Ensure the role is at least Member or Moderator. Bots with Guest status cannot post messages.
4. Adjust the role if necessary and save.
5. Test by sending a message from the bot manually: curl -X POST https://api.gitter.im/v1/rooms//chatMessages -H "Authorization: Bearer " -d "{\"text\":\"Test message\"}".
   • Run this from a machine that has network access to api.gitter.im.
   • Expected response: HTTP 201 Created.
6. Risk: If the bot token is revoked or expired, messages will fail silently.

Step 4 – Test Outbound Connectivity

1. From a server or workstation that hosts the Gitter integration (often the same as your GitHub webhook endpoint), run:

   curl -I https://api.github.com

2. Expected output contains HTTP/2 200 OK. If you receive a timeout or DNS error, a firewall or proxy is blocking outbound HTTPS to GitHub.
3. Check corporate firewall rules for outbound ports 443 and host github.com. If blocked, add an allow rule or use a proxy.
4. Risk: Network restrictions may also block webhook callbacks if the Gitter service cannot reach GitHub’s callback URL.

Escalation Criteria

• If all four checks pass but events still do not appear, verify that the GitHub repository is correctly configured to send events to the webhook URL. In the repository settings, under Webhooks, confirm the payload URL matches https://api.gitter.im/v1/integrations/github (or the specific room webhook endpoint).
• Check the Webhook Delivery page in GitHub for any delivery failures. A 4xx or 5xx status indicates an issue on the receiver side; 2xx indicates GitHub delivered successfully but the receiver may have rejected the payload.
• If the webhook shows 2xx responses yet no messages appear, contact Gitter support with the webhook logs and a sample payload. Provide the room-id and the timestamp of the test event.
• When network issues are suspected, involve the network operations team to confirm that the Gitter service can reach api.github.com and api.gitter.im over HTTPS.
• Document all steps taken and the outcomes; this aids support in diagnosing the problem faster.

Practical Verification Checklist

• Token is active and has required scopes.
• Webhook filter includes desired event types.
• Bot role is at least Member.
• Outbound HTTPS to GitHub and Gitter APIs succeeds.
• GitHub webhook delivery status is 2xx.
• Gitter logs show a 200 OK response for the payload.

Conclusion

Missing GitHub notifications in a Gitter room usually boil down to one of four concrete problems: an expired token, a restrictive payload filter, insufficient bot permissions, or blocked outbound traffic. By following the diagnostic flow above, you can quickly identify and resolve the issue, or provide the right information to support teams if the problem persists.