lint-pr-title

A GitHub App built with Probot that enforces Conventional Commits on pull request titles. When a PR is opened, updated, or its title is edited, the bot checks the PR title and posts a detailed comment with any violations. Designed for a squash-merge workflow where the PR title becomes the final commit message.

What it does

1. Listens for pull_request.opened, pull_request.synchronize, and pull_request.edited events
2. Lints the PR title against the Conventional Commits spec
3. Creates a Check Run (pass/fail badge) on the PR
4. Posts (or updates) a comment — guides developers to fix the title and use Squash and merge

Example output

All good:

✅ PR title follows conventional commit format

💡 Remember: Use Squash and merge when merging this PR so the PR title becomes the commit message.

Violations found:

❌ PR Title Does Not Follow Conventional Commits

Current title: added some stuff

• type-enum: type must be one of [feat, fix, chore, ...]

💡 Tip: Update the PR title above, and this check will re-run automatically. Use Squash and merge to keep a clean commit history.

Setup

Prerequisites

• Node.js >= 20
• A registered GitHub App

Install dependencies

npm install

Configure environment

Copy the example and fill in your GitHub App credentials:

cp .env.example .env

Variable	Description
APP_ID	Your GitHub App's ID
PRIVATE_KEY	Full contents of the .pem private key (or use PRIVATE_KEY_PATH for local dev)
WEBHOOK_SECRET	The webhook secret you set when creating the app
HOST	Set to 0.0.0.0 on Railway/cloud platforms
LOG_LEVEL	Logging verbosity (debug, info, warn, error)
PORT	Server port (default: 3000)

Required GitHub App permissions

Permission	Access	Why
Checks	Read & Write	Create pass/fail check runs on PRs
Pull Requests	Read & Write	Post and update comments
Contents	Read	Read commit messages
Metadata	Read	Required for all GitHub Apps

Subscribe to the Pull Request event (including opened, synchronize, and edited actions).

Recommended repo settings

For the best workflow, enforce squash merging on repos where the bot is installed:

Settings → General → Pull Requests — keep only "Allow squash merging" checked. This ensures the PR title always becomes the final commit message.

Development

# Build TypeScript
npm run build

# Run in development
npm run dev

# Run tests
npm test

# Type-check without emitting
npm run lint

Deployment

Quick: Platform-as-a-Service (Railway, Render, Fly.io)

1. Push this repo to GitHub
2. Connect your repo on Railway, Render, or Fly.io
3. Set the environment variables (APP_ID, PRIVATE_KEY, WEBHOOK_SECRET, HOST=0.0.0.0)
4. Update your GitHub App's webhook URL to https://your-app-url/api/github/webhooks
5. Install the app on your repos
6. In each repo, enable only squash merging (Settings → Pull Requests)

Docker

docker build -t lint-pr-title .
docker run -p 3000:3000 \
  -e APP_ID=your-app-id \
  -e PRIVATE_KEY="$(cat your-key.pem)" \
  -e WEBHOOK_SECRET=your-secret \
  lint-pr-title

Kubernetes (Helm)

For organizations with existing K8s infrastructure:

helm install lint-pr-title ./helm/commitlint-bot \
  --set github.appId=your-app-id \
  --set github.privateKey="$(cat your-key.pem)" \
  --set github.webhookSecret=your-secret

The Helm chart includes auto-scaling (2–10 replicas), health probes, TLS ingress, and resource limits.

Project structure

src/
  index.ts                  # Entry point — registers event listeners
  handlers/
    pull-request.ts         # Orchestrates: lint PR title → report
  services/
    commit-linter.ts        # Loads rules and lints the PR title
  utils/
    format.ts               # Formats the GitHub comment and check output (includes squash merge guidance)
tests/                      # Vitest test suite
helm/                       # Kubernetes Helm chart
commitlint.config.js        # Conventional commit rules configuration
Dockerfile                  # Multi-stage production build
app.yml                     # GitHub App manifest

Interactive course

An interactive HTML course is included that explains how the entire codebase works — from webhooks to deployment. It's designed for people who want to understand the code without a traditional CS background.

Run the course

cd commitlint-bot-course
open index.html        # macOS
xdg-open index.html    # Linux
start index.html       # Windows

Or simply open commitlint-bot-course/index.html in any browser. No server or build step required — it's a self-contained HTML file with all CSS and JS included.

What's in the course

Module	Topic
1	What This Bot Does — trace a PR event end-to-end
2	Meet the Cast — the 4 source files and their roles
3	The Webhook Pipeline — animated data flow and component chat
4	The Rulebook — how the linting engine and config work
5	Ship It — Docker, Helm, and production security
6	How to Deploy — step-by-step from zero to running on GitHub

Features: scroll animations, glossary tooltips on every technical term, code ↔ plain English translations, group chat animations between components, data flow visualizations, and 18 interactive quiz questions.

License

ISC