GitCord — GitHub to Discord Notification Gateway & Dashboard

GitCord is a high-performance, serverless integration built with Next.js (App Router, TypeScript, and Vanilla CSS) that forwards GitHub events (stars, forks, issues, pull requests, push commits, repository creation/deletion, and GitHub Actions) directly to dedicated Discord channels.

It features a sleek developer dashboard to monitor system configurations, test routes using an interactive simulator, review real-time activity logs, and configure multilingual notifications.

---

Features

• 🚀 Serverless First: Built for Vercel. Webhook dispatch is fast, lightweight, and uses Discord's REST API, preventing cold starts and persistent socket overhead.
• 🟢 Active presence (Optional): Includes a standalone Discord Gateway script to connect your bot, set its status to Online (green dot), and report status notifications.
• 🔌 Automatic Console Mirroring: Redirects all server console warnings, errors, and info logs to a dedicated Discord channel for real-time diagnostics.
• 🌐 Multilingual Support (i18n): Supports notifications in English and Spanish. Use the /language command in Discord to toggle notifications for each server dynamically! Also features a /ping command responding with 🏓 **Pong!**.
• 🧪 Testing Simulator: Select any event type (Star, Fork, Issue, PR, Action, Push) and send a mock payload with one click to test channel deliveries.
• 🔄 Automatic Activity Polling: Periodically syncs your GitHub activity (including private repos) and detects repository deletions via smart repo list comparison.
• 📌 Persistent State: Poller state is persisted via Discord pinned messages, surviving Vercel cold starts without external databases.

---

Configuration

Duplicate .env.template to create a .env file in the root directory:

# Discord Configuration
DISCORD_TOKEN=
DISCORD_PUBLIC_KEY=

# Discord Channel Mappings (Replace with your actual Channel IDs)
DISCORD_CHANNEL_DEFAULT=
DISCORD_CHANNEL_STARS=
DISCORD_CHANNEL_FORKS=
DISCORD_CHANNEL_ISSUES=
DISCORD_CHANNEL_PRS=
DISCORD_CHANNEL_ACTIONS=
DISCORD_CHANNEL_PUSH=
DISCORD_CHANNEL_LOGS=
DISCORD_CHANNEL_REPO_CREATE=
DISCORD_CHANNEL_REPO_DELETE=
DISCORD_CHANNEL_ACTIVE=

# GitHub Configuration
# Your GitHub username to poll activity from
GITHUB_USERNAME=
# A GitHub Personal Access Token (required for private repo visibility and to avoid rate limits)
GITHUB_PAT=

# Cron Security (Optional but recommended)
# A secret token to protect the sync-user endpoint from unauthorized calls
CRON_SECRET=

Generating a CRON_SECRET

Run the following command to generate a secure random token:

openssl rand -hex 16

Add this value as CRON_SECRET in both your .env file and your Vercel environment variables.

---

Running Locally

1. Start the Dashboard (Web UI & Webhook Server)

npm install
npm run dev

Open http://localhost:3000 to access the GitCord Dashboard.

2. Start the Discord Gateway Bot (For Online Status & /language command)

npm run bot

This connects the bot to the Discord Gateway, marks it as Online, registers the /language slash command, and sends a greeting message to DISCORD_CHANNEL_DEFAULT.

3. Testing Webhooks Locally

Since GitHub cannot communicate directly with localhost, you must set up a public tunnel:

1. Start a tunnel using ngrok:

   ngrok http 3000

2. Copy the forwarding HTTPS URL generated by ngrok (e.g., https://xxxx.ngrok-free.app).
3. Add /api/webhook/github to the end of the URL (e.g., https://xxxx.ngrok-free.app/api/webhook/github).
4. Go to your GitHub repository Settings ➔ Webhooks ➔ Add Webhook, paste this URL, set Content Type to application/json, select "Send me everything" (or select individual events), and click Add Webhook.
5. You will instantly see a 🏓 Pong! message in Discord and a new entry in your logs channel.

---

Deploying to Vercel

1. Deploy the Web App

1. Import your repository into the Vercel Dashboard.
2. Add all environment variables from your .env file to your Vercel Project Settings ➔ Environment Variables.
3. Deploy the application.
4. Set the Vercel deployment URL + /api/webhook/github (e.g., https://my-gitcord.vercel.app/api/webhook/github) as your webhook URL in your GitHub settings.

2. Setting Up Automatic Polling

The poller (/api/sync-user) periodically checks your GitHub activity for events that webhooks might miss (e.g., activity on repos without webhooks, repository deletions). It supports both GET and POST requests.

Vercel Cron (Daily — Hobby Plan)

The Vercel Hobby plan only allows cron jobs to run once per day. A daily cron is preconfigured in vercel.json:

{
  "crons": [
    {
      "path": "/api/sync-user",
      "schedule": "0 0 * * *"
    }
  ]
}

External Cron Service (Recommended for real-time sync)

For more frequent polling (e.g., every 5 minutes), use a free external cron service to call the sync endpoint:

1. Generate a CRON_SECRET (see Configuration) and add it to your Vercel environment variables.

2. Sign up for one of these free services:

   • cron-job.org — Free, every 1 minute
   • UptimeRobot — Free, every 5 minutes
   • Easycron — Free tier available

3. Create a new job with:

   • URL: https://your-app.vercel.app/api/sync-user?token=YOUR_CRON_SECRET
   • Method: GET
   • Interval: Every 5 minutes (or your preferred frequency)

4. Activate the job. The poller will now run automatically.

Note: If CRON_SECRET is not set, the endpoint is open (no authentication required). It is strongly recommended to set a secret in production.

How the Poller Works

• Events: Polls GET /users/{username}/events from the GitHub API to detect stars, forks, pushes, PRs, issues, and repository creation.
• Repo Deletions: Since GitHub's Events API does not emit events when a repository is deleted, GitCord compares the current repo list against a cached snapshot on each sync. Any repos that disappear trigger a deletion notification.
• Private Repos: Uses the authenticated GET /user/repos endpoint with your GITHUB_PAT to track private repositories.
• State Persistence: The last processed event ID and repo list are stored as a pinned message in your DISCORD_CHANNEL_LOGS channel. This survives Vercel serverless cold starts without needing a database.
• Deduplication: Events are tracked by ID. Re-running the sync will never send duplicate notifications.
• First Run: On the very first execution, only events from the last 10 minutes are processed to avoid flooding Discord with historical activity.

You can also manually synchronize at any time by clicking 🔄 Sync User Activity on the web dashboard.

---

Multilingual Support

GitCord supports English (en) and Spanish (es) template overrides.

There are two ways to configure the /language command inside Discord:

Method A: Serverless via Discord Interactions (Recommended for Vercel)

You do not need to run a persistent bot. Discord will call your Vercel deployment directly via HTTPS when a user types the slash command.

1. Go to the Discord Developer Portal and open your application.
2. Under General Information, copy your Public Key.
3. Add it as DISCORD_PUBLIC_KEY to your Vercel Project Environment Variables (and your local .env).
4. Set the Interactions Endpoint URL to your deployment URL ending in /api/interactions (e.g. https://my-gitcord.vercel.app/api/interactions).
5. Save changes. Discord will verify the endpoint, and you can now use /language and /ping on your server!
6. Optional: If the slash commands are not recognized by Discord right away, open your GitCord Dashboard in the browser and click the ⚡ Sync Discord Commands button to manually register/force-update them globally. (They also register automatically on the very first API request after a Vercel deployment).

Method B: Gateway Bot (For Local Testing & Development)

If you are running the bot locally:

1. Start the gateway bot client with npm run bot.
2. In your Discord server, run the command /language lang: Español or /language lang: English.

The bot will save your language selection, automatically check which guild a webhook's destination channel belongs to, and dynamically format the Discord notifications in the language chosen by that guild.