Quick Start (GitHub)

Use this guide to run the server locally with GitHub Apps. It mirrors docs/getting-started-github.md.

Prerequisites

• Go 1.24+
• Docker + Docker Compose
• ngrok (for local development)
• A GitHub account

Step 1: Start dependencies

docker compose up -d

Step 2: Expose with ngrok

ngrok http 8080

Copy the HTTPS forwarding URL (for example, https://abc123.ngrok-free.app).

Step 3: Create a GitHub App

1. Go to: Settings -> Developer settings -> GitHub Apps -> New GitHub App
2. App name: githook-local
3. Homepage URL: https://<your-ngrok-url>
4. Webhook URL: https://<your-ngrok-url>/webhooks/github
5. Webhook secret: devsecret
6. Callback URL: https://<your-ngrok-url>/auth/github/callback
   • Required if enabling "Request user authorization (OAuth)"
7. Permissions: Repository metadata (read), Pull requests (read & write)
8. Subscribe to events: Pull request, Push, Check suite
9. Create the app and download the private key

Step 4: Configure githook

Edit config.yaml:

server:
  port: 8080
endpoint: https://<your-ngrok-url>

providers:
  github:
    webhook:
      secret: devsecret
    app:
      app_id: YOUR_APP_ID
      private_key_path: /path/to/github.pem
      app_slug: your-app-slug
    api:
      base_url: https://api.github.com
    oauth:
      client_id: your-oauth-client-id
      client_secret: your-oauth-client-secret

watermill:
  driver: amqp
  amqp:
    url: amqp://guest:guest@localhost:5672/
    mode: durable_queue

storage:
  driver: postgres
  dsn: postgres://githook:githook@localhost:5432/githook?sslmode=disable
  dialect: postgres
  auto_migrate: true

redirect_base_url: https://app.example.com/success

rules:
  - when: action == "opened" && pull_request.draft == false
    emit: pr.opened.ready
  - when: action == "closed" && pull_request.merged == true
    emit: pr.merged
  - when: head_commit.id != "" && commits[0].id != "" && commits[1] == null
    emit: github.commit.created
  - when: action == "requested" && check_suite.head_commit.id != ""
    emit: github.commit.created

Step 5: Start the server

go run ./main.go serve --config config.yaml

Step 6: Start a worker

go run ./example/github/worker/main.go --config config.yaml --driver amqp

Step 7: Install the GitHub App

Get the provider instance hash:

githook --endpoint http://localhost:8080 providers list --provider github

Visit the OAuth installation URL:

http://localhost:8080/?provider=github&instance=<instance-hash>

Follow the GitHub authorization flow to complete installation.

Step 8: Trigger events

Create a pull request or push a commit to an installed repository. The worker will receive and process the events.

Troubleshooting

• Webhooks not received: check ngrok is running, verify endpoint matches
• 404 on callback: callback URL must be /auth/github/callback
• Missing signature: webhook secret mismatch
• No matching rules: rules in config do not match payload
• Connection refused: ensure Docker Compose is running
• Database errors: check PostgreSQL is running and the connection string is correct

Multiple provider instances

For GitHub.com + GitHub Enterprise setups, configure multiple instances:

providers:
  github:
    api:
      base_url: https://api.github.com
    # ... other config

  github_enterprise:
    api:
      base_url: https://ghe.company.com/api/v3
    # ... other config

Get instance hash:

githook --endpoint http://localhost:8080 providers list --provider github

Use with OAuth:

http://localhost:8080/?provider=github&instance=<instance-hash>