Webhook Automator for GitHub Orgs

This interactive CLI configures webhooks across repositories in a GitHub organization.

Features

• Asks for a fingerprint file that must exist in the repository (choose common options or enter custom). Repos without it are skipped.
• Skips empty repositories.
• Lets you choose notification presets:
  • A) stars and watches only
  • B) checks/comments/discussions/forks/issues/PRs/releases/visibility changes
  • C) custom multi-select from common events (plus custom entries)
  • D) GitHub default (push only)
• Reads a CSV (webhooks.csv) of options: first column org name, second column webhook URL. Always allows manual entry.
  • If manual entry is chosen, you’ll select the organization from those you belong to.
• For each repository:
  • Skip if empty or missing fingerprint file.
  • If the same webhook URL with identical events exists, skip.
  • If the same URL exists but events differ, remove and recreate with new events.
• Per-organization webhook CSVs in csv/ directory: for each organization, a file named .csv contains all webhook URLs and their permissions (events). The first column is the webhook URL, the second column is the comma-separated permissions. Values are quoted to preserve commas.
• When adding new webhooks, the tool checks the organization's CSV. If a matching URL exists, you are informed of differences (if any) and prompted to:
  • A) Proceed to update the webhooks in the organization
  • B) Cancel and go back to the insert URL screen
  • C) Cancel and exit
• Session awareness: if you try to add the same webhook to an organization you've already added it to in this session, you’ll be asked if you want to try again (default is No).
• Manage existing webhooks: you can list existing webhooks in all repositories in an organization and select which ones to delete using selections like 1a, 1b, etc. Multiple selections can be provided separated by commas.

Requirements

• Python 3.8+
• requests library

Install

• pip install -r requirements.txt

Usage

1. Set an access token (recommended):
   • export GITHUB_TOKEN=your_pat
   • Optionally export GITHUB_API for GHES: export GITHUB_API=https://ghe.example.com/api/v3
2. Optional: create a CSV named webhooks.csv with two columns: org, webhook_url
3. Run the tool:
   • python webhook_automator.py

Global interaction guidelines

• Always allow typing 'exit' at any prompt to exit the prompt screens.
• Typing 'help' at any prompt shows a more detailed guide to the steps. When exiting help, you will be notified that you're back in the selection screen.
• If an option list is enumerated with letters (e.g., A, B, C...), select using those letters (A, B, C), not numbers.
• Organization selection is listed with composite labels in the style of 1a, 1b, 1c, ...; enter 1a, 1b, etc. (the letter alone, e.g., 'a', is also accepted).
• Before adding webhooks, you will be prompted to choose how to handle the webhook URL:
  • A) Automatically append '/github' to the end of the webhook URL
  • B) Leave the URL unchanged The tool will notify you how the URL was handled.

Notes

• Token must permit managing repository webhooks for the target repositories (admin permission).
• Fingerprint supports a basic root-level glob pattern like *.gemspec.
• When selecting events (option C), you can add events not in the pre-defined list.