Providers

Providers are configured in config.yaml and require OAuth or App credentials. If you omit providers.*.webhook.path, defaults are /webhooks/github, /webhooks/gitlab, and /webhooks/bitbucket.

GitHub (App + OAuth)

This is the same flow as docs/getting-started-github.md.

App setup

1. Create a GitHub App: Settings -> Developer settings -> GitHub Apps -> New GitHub App
2. Homepage URL: https://<your-public-url>
3. Webhook URL: https://<your-public-url>/webhooks/github
4. Webhook secret: set a value (for example, devsecret)
5. Callback URL: https://<your-public-url>/auth/github/callback
6. Permissions: Repository metadata (read), Pull requests (read & write)
7. Subscribe to events: Pull request, Push, Check suite
8. Download the private key

Config

providers:
  github:
    webhook:
      secret: devsecret
    app:
      app_id: 123456
      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

Onboarding URL

https://your-domain.com/?provider=github&instance=<instance-hash>

GitLab (OAuth)

This mirrors docs/getting-started-gitlab.md.

OAuth app setup

1. Create a GitLab OAuth app: https://gitlab.com/-/user_settings/applications
2. Redirect URI: https://<your-public-url>/auth/gitlab/callback
3. Scopes: read_api, read_repository
4. Save and copy Application ID + Secret

Config

providers:
  gitlab:
    webhook:
      secret: devsecret
    api:
      base_url: https://gitlab.com/api/v4
      web_base_url: https://gitlab.com
    oauth:
      client_id: your-oauth-client-id
      client_secret: your-oauth-client-secret

Webhook setup

Configure project or group webhooks in GitLab:

• URL: https://<your-public-url>/webhooks/gitlab
• Secret token: devsecret
• Enable merge request, push, and tag push events

Onboarding URL

https://your-domain.com/?provider=gitlab&instance=<instance-hash>

Bitbucket (OAuth)

This mirrors docs/getting-started-bitbucket.md.

OAuth app setup

1. Create an OAuth consumer in Bitbucket: Settings -> OAuth consumers
2. Callback URL: https://<your-public-url>/auth/bitbucket/callback
3. Permissions: repository, pullrequest, webhook (as needed)
4. Save and copy the Key + Secret

Config

providers:
  bitbucket:
    webhook:
      secret: devsecret
    api:
      base_url: https://api.bitbucket.org/2.0
      web_base_url: https://bitbucket.org
    oauth:
      client_id: your-oauth-client-id
      client_secret: your-oauth-client-secret

Webhook setup

Configure repository or workspace webhooks in Bitbucket:

• URL: https://<your-public-url>/webhooks/bitbucket
• Secret token: devsecret (optional)
• Enable pull request, push, and tag push events

Onboarding URL

https://your-domain.com/?provider=bitbucket&instance=<instance-hash>

OAuth callbacks

Callback URLs must be configured in the provider OAuth settings:

• GitHub: https://your-domain.com/auth/github/callback
• GitLab: https://your-domain.com/auth/gitlab/callback
• Bitbucket: https://your-domain.com/auth/bitbucket/callback

Your public base URL should be set in config:

endpoint: https://your-domain.com
redirect_base_url: https://app.example.com/oauth/complete

Onboarding URL

Get the provider instance hash and redirect users to:

githook --endpoint https://your-domain.com providers list --provider github

https://your-domain.com/?provider=github&instance=<instance-hash>

See docs/webhooks.md and docs/oauth-callbacks.md for step-by-step setup.