Notifycat

Notifycat listens for GitHub pull request webhooks and keeps Slack up to date.

One pull request gets one Slack message. As the PR opens, moves to draft, gets reviewed, merges, or closes, Notifycat updates that message and adds the configured reactions. The result is a quieter channel: reviewers can follow the state of a PR without digging through repeated notifications.

It is intentionally small: one HTTP endpoint, a SQLite database (for Slack message timestamps), and a declarative mappings.yaml that decides which PRs route to which Slack channels.

Quick start

You'll need a host with Docker + Compose V2, a domain name pointing at it, and inbound ports 80/443 open. In about 10 minutes you'll have Notifycat running behind automatic HTTPS and posting PR updates to Slack — no Go toolchain, no SQLite client, no manual file editing.

curl -fsSL https://github.com/mptooling/notifycat/releases/latest/download/install.sh | sh
cd notifycat
./notifycat setup          # interactive wizard — writes .env and mappings.yaml
docker compose up -d       # start Notifycat + Caddy (HTTPS via Let's Encrypt)
./notifycat doctor         # verify setup

The installer downloads a pinned, checksum-verified bundle into ./notifycat. The setup wizard prompts for your domain, Slack token, webhook secret, and first mapping. For the full walkthrough — webhook registration, a delivery smoke test, and troubleshooting — see Install with Docker Compose, then run through the Security & permissions checklist before go-live.

Alternative: run from source (contributors)

Most users want the one-command path above. Build from source if you're contributing or want to run without Docker.

Requires:

• Go 1.25.10 or newer (go version to check).
• git to clone the repository.
• sh and curl for the helper scripts under scripts/.
• A public URL (ngrok or Cloudflare Tunnel) only if you want GitHub to deliver real webhooks to your laptop. Local CLI commands (validate / doctor) don't need one.

Six commands from "nothing" to "running":

git clone https://github.com/mptooling/notifycat.git && cd notifycat
cp .env.example .env                       # then edit: set GITHUB_WEBHOOK_SECRET, SLACK_BOT_TOKEN
cp mappings.example.yaml mappings.yaml     # then edit: real Slack channel IDs

go run ./cmd/notifycat-mapping validate
go run ./cmd/notifycat-doctor
go run ./cmd/notifycat-server

The binaries pick up .env from the current working directory and default to ./mappings.yaml and ./data/notifycat.db. See Getting started for the end-to-end walkthrough including the tunnel + webhook setup.

What It Handles

• pull_request webhooks for opened, closed, and converted-to-draft PRs.
• pull_request_review webhooks for approved, commented, and changes-requested reviews.
• pull_request_review_comment webhooks for line-specific PR comments.
• GitHub HMAC-SHA256 verification through X-Hub-Signature-256.
• Repository routing from a declarative mappings.yaml — explicit lists or repositories: "*" for a whole org. See mappings.example.yaml.
• Slack message updates instead of repeated new messages for the same PR.

Binaries

Binary	Purpose
notifycat-server	HTTP server for GitHub webhooks
notifycat-mapping	CLI for listing and validating the mappings file
notifycat-migrate	Applies embedded SQLite migrations
notifycat-doctor	Preflight diagnostics (config, database, mappings, optional per-repo Slack/GitHub)
notifycat-smoke	Forges a signed PR event end-to-end to confirm Slack delivery

Documentation

Full documentation is published at https://mptooling.github.io/notifycat/.

• Install with Docker Compose — the recommended one-command path
• Security & permissions — least-privilege model and pre-go-live checklist
• Getting started
• Mappings file
• Configuration
• Slack app setup
• GitHub webhook setup
• Docker (manual)
• Operations
• Doctor

Development

The project includes a justfile for common development commands. Install just (brew install just on macOS), then run:

just
just check
just serve

just is a developer tool only. It is not part of the Go module, the Docker runtime image, or production dependencies.

The underlying checks are:

go vet ./...
golangci-lint run ./...
govulncheck ./...
go test -race ./...
go build ./...

See CONTRIBUTING.md for contributor setup, pull request expectations, and issue reporting guidance.

Community

• Code of conduct
• Support
• Security policy

License

MIT. See LICENSE.