GitHub to Discord Webhook Gateway

A production-ready, modular, and high-performance integration server that captures GitHub repository events and routes them as rich, color-coded embeds to designated Discord channels.

Designed for reliability, maintainability, and ease of deployment, this gateway features timing-safe signature verification, automatic Discord rate-limit throttling with queues, and repository-to-channel routing through simple YAML configuration.

---

Key Features

• Complete Event Coverage: Out-of-the-box support for 17 standard GitHub webhook events including commits, pull requests, releases, workflow outcomes, and deployment updates.
• Granular Routing: Route different repositories to separate Discord webhooks and channels using a single configuration file.
• Rate-Limit Resilient: Embedded in-memory queue manager that sequences posts and handles Discord's 429 Too Many Requests API limits automatically by respecting retry_after values.
• Security Hardened: Enforces raw body HMAC SHA-256 signature verification to prevent payload spoofing, sets security headers via Helmet, and limits JSON payload sizes to protect memory.
• Production Observability: Built-in micro-latency logging, server metric health checking endpoint (GET /), and graceful process termination handling.
• Cloud-First Design: Compatible with Docker, Docker Compose, PM2, and serverless host providers (Railway, Render, Coolify) via config-string injections.

---

Visual Design (Discord Embeds)

Notifications sent by this server are visually optimized using Discord's embed cards, which feature:

• Event Color Coding: Instant visual scanning (e.g., Green for pushes, Red for failures, Blue for pull requests, Gold for releases).
• Rich Metadata: Repository name, URL links, author avatar profiles, event footers, and timestamp.
• Details Lists: Push cards display the branch name, pusher, and up to the latest 10 commits with short SHAs. PR cards display draft status, state, author, and merge status.

---

Prerequisites

• Node.js: >= 22.0.0
• NPM: >= 10.0.0
• Operating System: Linux (Ubuntu/Debian recommended), macOS, or Windows.

---

Installation

# Clone the repository
git clone https://github.com/fczavian/git-notifier.git
cd git-notifier

# Install dependencies
npm install

---

Configuration

Configure the application by creating a config.yml file in the root directory:

cp config.yml.example config.yml

Example config.yml

server:
  port: 3000

github:
  secret: "your_hmac_secret_here"

repositories:
  "octocat/hello-world": "https://discord.com/api/webhooks/123456/abcdef"

Environment Variables

Variable	Description
CONFIG_PATH	Overrides the default path to search for the config.yml configuration file.
CONFIG_YML_CONTENT	Paste the entire content of your config.yml as a string (useful for cloud hosts where committing configs is not allowed).
NODE_ENV	Setting to production disables debug logging.

---

Running Locally

Development (Auto-Reloading)

npm run dev

Exposing Local Server for Testing

To receive GitHub hooks on localhost, run a Cloudflare Tunnel or Ngrok:

# Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3000

Then register https://<your-generated-subdomain>.trycloudflare.com/github in GitHub's settings.

---

Production Deployment

1. Docker Compose (Recommended)

Configure your config.yml and boot the stack:

docker compose up -d

2. PM2 (Process Manager)

npm install -g pm2
pm2 start index.js --name "github-webhook"
pm2 save
pm2 startup

---

Supported GitHub Events

This gateway supports these events out of the box:

• ping (configuration test)
• push (branches, commits lists)
• pull_request (open, close, merge details)
• issues (opened, closed, labels)
• issue_comment (comments on issues/PRs)
• commit_comment (comments on commits)
• release (major/pre-releases, tags)
• create / delete (branch/tag create and destroy logs)
• fork / watch (star updates and clones)
• discussion / discussion_comment (forum topics)
• workflow_run / workflow_job (Actions workflow status)
• deployment / deployment_status (deploy steps)

---

Project Structure

├── index.js                  # Main entrypoint
├── package.json              # Build scripts and dependency versions
├── Dockerfile                # Production container blueprint
├── docker-compose.yml        # Docker compose coordinator
├── config.yml.example        # Configuration blueprint
├── docs/                     # Comprehensive setup guides
│   ├── getting_started.md    # End-to-end setup walk-through
│   ├── github_setup.md       # Registering webhooks on GitHub
│   ├── discord_setup.md      # Discord webhook setup
│   ├── architecture.md       # System design and request lifecycles
│   ├── api.md                # Endpoint specs (Headers, JSON examples)
│   └── ...                   # Cloud deployment guides (VPS, Docker, Railway, Render, Coolify)
└── src/
    ├── app.js                # Express app framework initialization
    ├── config/               # Config parser
    ├── middleware/           # Logging, verification, and limits middlewares
    ├── routes/               # API endpoints
    ├── handlers/             # Modular, event-specific message formatting
    ├── services/             # Rate-limited native fetch dispatchers
    └── utilities/            # Loggers and embed templates

---

Troubleshooting

For in-depth explanations of issues, consult docs/troubleshooting.md. Here is a quick reference:

• Webhook returns 401 Unauthorized: Verify that the payload type on GitHub is set to application/json (NOT application/x-www-form-urlencoded) and that your shared secret matches github.secret in config.yml.
• Webhook returns 404 Not Found: Ensure the URL path ends with /github (e.g. https://domain.com/github).
• Discord rate limits hit: No action needed. The server's in-memory queue throttles requests and schedules retries automatically.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgements

• Thanks to the community for testing and contributing event schemas.
• Built using Express and native Node.js APIs.