SakuraCord Discord Bot

The independently deployable GitHub-to-Discord automation service for SakuraCord Roadmap.

The Worker accepts signed GitHub webhooks and posts compact update cards to Discord through a durable Cloudflare Queue. The webhook returns after signature verification and enqueueing; Discord rate limits and transient failures are retried by the queue without holding GitHub's request open. Pushes get a short summary followed by one intentionally small card per commit, each with a direct Open commit button.

Runtime boundary

flowchart LR
  G["GitHub webhooks"] --> B["DiscordBot Worker"]
  B --> Q[("Cloudflare Queue")]
  Q --> B
  B -->|"compact updates + role ping"| REST["Discord REST API"]

Loading

Neither repository imports the other from the local filesystem. A clone needs only its own dependencies and Discord/GitHub configuration.

Cloudflare setup

Requirements: Node.js 20.19 or later, npm, and a Cloudflare account.

git clone https://github.com/SakuraCordApp/DiscordBot.git
cd DiscordBot
npm install
npm run check
npx wrangler whoami
npx wrangler queues create sakuracord-github-updates
npx wrangler queues create sakuracord-github-updates-dlq
npx wrangler secret put DISCORD_BOT_TOKEN
npx wrangler secret put GITHUB_WEBHOOK_SECRET
npx wrangler deploy

The Discord GitHub-updates channel and role IDs are public configuration in wrangler.jsonc. GITHUB_WEBHOOK_SECRET is a random shared secret used only to authenticate GitHub deliveries.

For each repository, create a repository webhook targeting:

https://discord-bot.sakuracord.app/webhooks/github

Use JSON content, the same GITHUB_WEBHOOK_SECRET, SSL verification, and these events: pushes, branch or tag creation/deletion, workflow runs, releases, pull requests, pull-request reviews, issues, issue comments, discussions, discussion comments, and deployment statuses. Setup pings are signature-checked but do not create a Discord message. Release events are also acknowledged without being queued because each application repository's release workflow owns its prepared release announcement. GitHub delivery IDs become deterministic Discord nonces so ordinary webhook retries do not duplicate recent messages.

Discord report discovery and analysis are owned by the Roadmap Worker so this service cannot start a duplicate reconciliation crawl.

Local development

Copy .env.example to .dev.vars, fill the Discord and GitHub credentials, and run:

npm install
npm run dev

The complete local gate is:

npm run check

Continuous deployment

The production Worker is connected to this repository through Cloudflare Workers Builds. Pushes to main run npm run check and then npx wrangler deploy. Runtime secrets stay in Cloudflare and are not stored in GitHub. Non-production branches are not deployed.

License

MIT. SakuraCord is unofficial and is not affiliated with Discord.