A lightweight GitHub webhook bot that delivers GitHub repository activity directly to IRC channels.

irc-gitbot receives GitHub webhook events through a FastAPI endpoint, verifies the webhook signature, formats human-friendly messages, and posts them to one or more IRC networks over secure TLS connections.

Designed to be simple, fast, and dependency-light, it is ideal for IRC communities that want real-time GitHub notifications without relying on third-party bridges.

• ✅ Push notifications

  • Multiline commit summaries
  • Branch name
  • Number of commits
  • Short commit SHA
  • Commit titles
  • Compare/commit URL
  • GitHub display name mapping

• ✅ Branch created

• ✅ Branch deleted

• ✅ Issue opened
• ✅ Issue closed
• ✅ Issue reopened

• ✅ New issue comments

• ✅ Pull request opened
• ✅ Pull request closed
• ✅ Pull request reopened
• ✅ Pull request merged

• ✅ Release published

• Connects using TLS
• Supports multiple IRC networks
• Supports multiple channels per network
• IPv4 and IPv6 outbound connections
• Custom nickname and ident per network
• Custom quit message per network
• Automatic disconnect after sending notifications

• GitHub webhook signature verification (HMAC SHA-256)
• Invalid or unsigned requests are rejected

• Optional GitHub username → display name mapping
• Simple configuration file
• Designed to run as a systemd service
• Lightweight with minimal dependencies

• Python 3.11 or newer
• FastAPI
• Uvicorn

Clone the repository:

git clone git@github.com:pinkabels/irc-gitbot.git
cd irc-gitbot

Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install the required packages:

pip install fastapi uvicorn

Or install from a requirements file (recommended):

pip install -r req.txt

Copy the example configuration:

cp config.example.py config.py

Edit config.py to match your environment.

Start the webhook server:

uvicorn webhook:app --host 127.0.0.1 --port 8000

For production deployments, it is recommended to run the application behind a reverse proxy (such as Nginx) and manage it with systemd.

On your GitHub repository:

Settings → Webhooks → Add webhook

Configure the webhook:

The bot automatically filters unsupported events.

Unsupported events are safely ignored.

*** GitHub (git@example.org) has joined the channel
<GitHub> [irc-gitbot] Belle pushed 3 commits to main https://github.com/example/repo/compare/...
<GitHub> [irc-gitbot] da23634 - Fourth test commit
<GitHub> [irc-gitbot] 870acfb - Fifth test commit
<GitHub> [irc-gitbot] 01b369a - Sixth test commit
*** GitHub (git@example.org) has left the channel (GitHub update posted)

<GitHub> [irc-gitbot] Belle opened issue #5: Webhook does not reconnect

<GitHub> [irc-gitbot] Belle commented on issue #5: Webhook does not reconnect

<GitHub> [irc-gitbot] Belle merged PR #8: Improve IPv4 fallback

<GitHub> [irc-gitbot] Belle published release v1.0.0: Initial stable release

irc-gitbot/
├── config.example.py
├── gitbot.py
├── req.txt
├── webhook.py
├── README.md
├── LICENSE
└── .gitignore

• Verifies every webhook using GitHub's HMAC SHA-256 signature.
• Rejects requests without a valid signature.
• Supports HTTPS deployments behind reverse proxies.
• Sensitive configuration is kept outside version control.

• Commit comment notifications
• GitHub Discussions
• GitHub Discussions comments
• Wiki edit notifications
• Deployment notifications
• GitHub Actions workflow notifications
• Star notifications
• Fork notifications
• Configurable event filtering
• IRC color themes
• Persistent IRC connections
• Configurable message templates

This project is released under the MIT License.