irc-gitbot

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.

---

Features

Repository Activity

• ✅ 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

Issues

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

Issue Comments

• ✅ New issue comments

Pull Requests

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

Releases

• ✅ Release published

IRC

• 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

Security

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

Miscellaneous

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

---

Requirements

• Python 3.11 or newer
• FastAPI
• Uvicorn

---

Installation

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

---

Configuration

Copy the example configuration:

cp config.example.py config.py

Edit config.py to match your environment.

Configuration Options

Option	Description
WEBHOOK_SECRET	GitHub webhook secret used for signature verification.
NETWORKS	One or more IRC networks to send notifications to.
DISPLAY_NAMES	Maps GitHub usernames to preferred display names.

---

Running

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.

---

GitHub Webhook Setup

On your GitHub repository:

Settings → Webhooks → Add webhook

Configure the webhook:

Setting	Value
Payload URL	https://your-domain.example/hub
Content type	application/json
Secret	Same value as WEBHOOK_SECRET
SSL verification	Enabled (recommended)
Events	Send me everything

The bot automatically filters unsupported events.

---

Supported GitHub Events

Event	Supported
Push	✅
Branch create	✅
Branch delete	✅
Issues	✅
Issue comments	✅
Pull requests	✅
Releases	✅

Unsupported events are safely ignored.

---

Example IRC Output

Push

*** 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)

Issue

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

Issue Comment

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

Pull Request

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

Release

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

---

Project Structure

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

Files

File	Description
webhook.py	FastAPI webhook endpoint and GitHub event handling.
gitbot.py	IRC client implementation and message formatting.
config.example.py	Example configuration.
config.py	Local configuration (not tracked by Git).

---

Security

• 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.

---

Future Ideas

• 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

---

License

This project is released under the MIT License.