Skip to content

Installation

Prerequisites

  • A GitHub organization (the app is installed at the org level)
  • A Cloudflare account with Workers and Pages enabled
  • Node.js 18+ and wrangler CLI installed locally

1. Register the GitHub App

  1. Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
  2. Fill in:
  3. App name: your-org-checklist (or any name)
  4. Homepage URL: your Cloudflare Pages URL (e.g. https://checklist.yourorg.pages.dev)
  5. Webhook URL: https://your-worker.workers.dev/api/webhook
  6. Webhook secret: generate a strong random string and save it

  7. Set Repository permissions:

    Permission Access
    Issues Read & write
    Contents Read-only
    Members Read-only
    Metadata Read-only

  8. Set Organization permissions:

    Permission Access
    Members Read-only

  9. Subscribe to Webhook events:

  10. Issues

  11. Issue comment

  12. Set Where can this GitHub App be installed? to Only on this account

  13. Click Create GitHub App
  14. On the next page, click Generate a private key and download the .pem file

2. Install the App on your org

  1. In your GitHub App settings, click Install App
  2. Select your organization and choose All repositories (required to read .github and .github-private)

3. Deploy the Cloudflare Worker

Clone the repo and install dependencies:

git clone https://github.com/your-org/github-checklist
cd github-checklist
npm install

Store secrets with wrangler:

wrangler secret put APP_ID           # your GitHub App's numeric ID
wrangler secret put PRIVATE_KEY      # contents of the .pem file
wrangler secret put WEBHOOK_SECRET   # the secret you chose in step 1
wrangler secret put CLIENT_ID        # OAuth client ID (for the UI)
wrangler secret put CLIENT_SECRET    # OAuth client secret (for the UI)

Deploy:

wrangler deploy

Copy the worker URL (e.g. https://github-checklist.yourname.workers.dev) and paste it as the webhook URL in your GitHub App settings.

4. Set up checklist templates

Create your first template. In any repo where issues will be opened (or in your org's .github repo for a shared default), create:

.github/CHECKLIST/<issue-type>.md

For example, for a Feature issue type:

.github/CHECKLIST/feature.md

See the Templates guide for the full template format.

5. Verify

Open a new issue in a repo where the app is installed and assign an issue type. Within seconds, the bot should post a managed comment with the checklist rendered and ready to use.