Let me start by reading the knowledge graph and understanding the project structure.

Now let me look at the repository-local config (.github-webhook-server.yaml) handling and more details:

Now let me check what's available in .github-webhook-server.yaml (what keys it can contain):

Let me check the verify-github-ips and verify-cloudflare-ips usage:

Now let me look at the .github-webhook-server.yaml more closely - what keys does it support:

Let me look at the welcome-message.md file pattern and remaining config usage:

Now let me look at tox config more closely and check events config:

Now let me check the OWNERS file support:

Let me also check the verify-github-ips and IP allowlist implementation:

Now let me check the disable-ssl-warnings key and look for all the config keys used at the app level:

Now let me check the .github-webhook-server.yaml in-repo config more carefully - specifically what keys it can accept. It should be basically the same as the repository-level config:

Now I have a comprehensive understanding. Let me verify the dockerfile key usage:

Now I have enough information. Let me write the comprehensive Configuration Reference page.

Configuration Reference

Complete reference for all configuration options in config.yaml (global server config) and .github-webhook-server.yaml (per-repository in-repo config).

Configuration Files Overview

Config Resolution Order

Values are resolved in this order (first match wins):

1. .github-webhook-server.yaml (in-repo file)
2. Repository-level settings in config.yaml (under repositories.<name>)
3. Global (root-level) settings in config.yaml

Note: Dot notation is supported for nested lookups (e.g., docker.username, pypi.token).

Global Server Settings

These settings are defined at the root level of config.yaml only. They cannot be set in .github-webhook-server.yaml.

log-level

Global log level. Changes take effect immediately without server restart.

log-level: INFO

log-file

File path for the main log file. Changes take effect immediately without server restart.

log-file: webhook-server.log

mcp-log-file

File path for the MCP server log file.

mcp-log-file: mcp_server.log

logs-server-log-file

File path for the Logs Server log file.

logs-server-log-file: logs_server.log

mask-sensitive-data

Mask sensitive data (tokens, passwords, secrets) in logs. Can be overridden per repository.

mask-sensitive-data: true

Warning: Setting to false in production will expose secrets in log files.

github-app-id

The GitHub App ID used by the webhook server for repository management.

github-app-id: 123456

github-tokens

Global GitHub personal access tokens. Multiple tokens enable automatic failover — the server selects the token with the highest remaining rate limit. Can be overridden per repository.

github-tokens:
  - ghp_token1abc123
  - ghp_token2def456

webhook-ip

Full webhook URL including path. This is registered on each managed repository as the webhook endpoint.

webhook-ip: https://your-domain.com/webhook_server

Tip: For local development, use a smee.io channel: https://smee.io/your-channel.

ip-bind

IP address to bind the HTTP server to.

ip-bind: 0.0.0.0

port

Port to bind the HTTP server to.

port: 5000

max-workers

Maximum number of uvicorn worker processes. Only used in production mode (not in dev mode with WEBHOOK_SERVER_DEV_MODE=true).

max-workers: 10

webhook-secret

Shared secret for validating GitHub webhook payloads via HMAC-SHA256 signature. When set, the server verifies the x-hub-signature-256 header on every incoming request.

webhook-secret: my-super-secret-value

verify-github-ips

Restrict incoming webhooks to GitHub's published IP ranges. At startup, the server fetches the GitHub meta API to build an IP allowlist.

verify-github-ips: true

verify-cloudflare-ips

Restrict incoming webhooks to Cloudflare's published IP ranges. Use when the server sits behind a Cloudflare proxy.

verify-cloudflare-ips: true

Note: verify-github-ips and verify-cloudflare-ips can be combined. If both are enabled, requests from either range are accepted. If enabled but IP lists fail to load, the server refuses to start.

disable-ssl-warnings

Disable urllib3 SSL warnings. Useful in production environments with internal CAs to reduce log noise.

disable-ssl-warnings: true

docker

Docker Hub credentials for pulling base images during container builds.

docker:
  username: my-docker-user
  password: my-docker-password

Global Defaults

These settings are defined at the root level of config.yaml and serve as defaults. They can be overridden at the repository level in config.yaml or in .github-webhook-server.yaml.

default-status-checks

Status checks included when configuring branch protection required status checks. The can-be-merged check is always appended automatically.

default-status-checks:
  - "WIP"
  - "dpulls"
  - "can-be-merged"

auto-verified-and-merged-users

Users whose PRs are automatically verified and merged. Typically used for bots like Renovate or pre-commit CI.

auto-verified-and-merged-users:
  - "renovate[bot]"
  - "pre-commit-ci[bot]"

auto-verify-cherry-picked-prs

Automatically add the verified label to cherry-picked PRs.

auto-verify-cherry-picked-prs: true

create-issue-for-new-pr

Create a tracking issue for each new pull request.

create-issue-for-new-pr: true

cherry-pick-assign-to-pr-author

Assign cherry-pick PRs to the original PR author.

cherry-pick-assign-to-pr-author: true

allow-commands-on-draft-prs

Controls which PR comment commands are allowed on draft PRs.

# Allow all commands on draft PRs
allow-commands-on-draft-prs: []

# Allow only specific commands
allow-commands-on-draft-prs:
  - build-and-push-container
  - retest

welcome-extra-info

Additional markdown content appended to the PR welcome message. An empty string explicitly clears any inherited value.

welcome-extra-info: |
  **Note:** Please review the contribution guide before merging.
  - Ensure tests pass
  - Update documentation if needed

Tip: For larger welcome message content, commit a .github-webhook-server-welcome-message.md file to the repository root. It takes priority over all config-based welcome-extra-info settings.

Labels Configuration

Controls which labels the server manages and their colors. Can be set globally or per repository. See Configuring Labels and PR Size Thresholds for usage details.

labels

labels.enabled-labels

List of label categories to enable. If not set, all categories are active.

Note: Reviewed-by labels (approved-<user>, lgtm-<user>, changes-requested-<user>, commented-<user>) are always enabled and cannot be disabled.

labels:
  enabled-labels:
    - verified
    - hold
    - size
    - can-be-merged

labels.colors

Custom colors for labels. Use the exact label name for static labels, or the prefix for dynamic labels.

labels:
  colors:
    hold: red
    verified: green
    approved-: green
    lgtm-: yellowgreen
    cherry-pick-: coral
    branch-: royalblue

pr-size-thresholds

Custom PR size categories based on total lines changed (additions + deletions).

Categories are sorted by threshold. Each PR gets the label whose threshold it meets but whose next-higher threshold it does not. Use "inf" for the unbounded largest category.

pr-size-thresholds:
  Tiny:
    threshold: 10    # 0–9 lines changed
    color: lightgray
  Small:
    threshold: 50    # 10–49 lines changed
    color: green
  Medium:
    threshold: 150   # 50–149 lines changed
    color: orange
  Large:
    threshold: 300   # 150–299 lines changed
    color: red
  Massive:
    threshold: inf   # 300+ lines changed
    color: darkred

Branch Protection

Configures GitHub branch protection rules applied at server startup. Can be set globally or per repository. Repository-level settings override global.

branch-protection

branch-protection:
  strict: true
  require_code_owner_reviews: true
  dismiss_stale_reviews: false
  required_approving_review_count: 1
  required_linear_history: true
  required_conversation_resolution: true

Security Checks

Detects potentially malicious PR patterns. Can be set globally or per repository. See Enabling Security Checks for usage details.

security-checks

Default suspicious paths:

• .claude/
• .vscode/
• .cursor/
• .devcontainer/
• .pi/
• .github/workflows/
• .github/actions/

Note: The GitHub App bot, web-flow, and API users from github-tokens are automatically added to the trusted committers list. Only list additional external committers.

security-checks:
  mandatory: true
  suspicious-paths:
    - ".github/workflows/"
    - ".github/actions/"
  committer-identity-check: true
  trusted-committers:
    - "pre-commit-ci[bot]"

AI Features

AI-powered enhancements using external AI CLI providers. Can be set globally or per repository. See Enabling AI Features for usage details.

ai-features

ai-features.conventional-title

ai-features.resolve-cherry-pick-conflicts-with-ai

Note: AI-resolved cherry-picks are never auto-verified — manual review is always required.

ai-features:
  ai-provider: "claude"
  ai-model: "sonnet"
  conventional-title:
    enabled: true
    mode: suggest
    timeout-minutes: 10
  resolve-cherry-pick-conflicts-with-ai:
    enabled: true
    timeout-minutes: 10

Test Oracle

PR Test Oracle integration that analyzes diffs with AI and recommends which tests to run. Can be set globally or per repository.

test-oracle

Trigger values:

Tip: The /test-oracle comment command always works when configured, regardless of triggers.

test-oracle:
  server-url: "http://localhost:8000"
  ai-provider: "claude"
  ai-model: "sonnet"
  test-patterns:
    - "tests/**/*.py"
  triggers:
    - approved
    - pr-opened

Repository Settings

Each repository is defined under the repositories key in config.yaml. The repository key is an alias; the actual GitHub repository is identified by the name field.

repositories:
  my-repo-alias:
    name: my-org/my-repository
    # ... repository-specific settings

name

Full repository name in org/repo format.

name: my-org/my-repository

log-level

Override the global log level for this repository.

log-level: DEBUG

log-file

Override the global log file for this repository.

log-file: my-repository.log

mask-sensitive-data

Override the global sensitive data masking for this repository.

mask-sensitive-data: false

slack-webhook-url

Slack webhook URL for notifications on PR merges, container builds, PyPI uploads, and other events. See Setting Up Slack Notifications for details.

slack-webhook-url: https://slack-webhook-url/replace-with-your-webhook-url

verified-job

Enable the verified job check run functionality.

verified-job: true

events

GitHub webhook events to listen to. If omitted, all events are subscribed. See Webhook Events and Handlers for supported events.

events:
  - push
  - pull_request
  - pull_request_review
  - pull_request_review_thread
  - issue_comment
  - check_run
  - status

github-tokens

Override global GitHub tokens for this repository. Supports multi-token failover.

github-tokens:
  - ghp_repo_specific_token1
  - ghp_repo_specific_token2

default-status-checks

Override global default status checks for this repository.

default-status-checks:
  - "WIP"
  - "can-be-merged"
  - "ci/my-external-check"

minimum-lgtm

Minimum number of LGTM approvals required before a PR can be approved.

minimum-lgtm: 2

can-be-merged-required-labels

Additional labels required for a PR to receive the can-be-merged label.

can-be-merged-required-labels:
  - qa-approved
  - docs-reviewed

set-auto-merge-prs

Branches for which auto-merge is automatically enabled on new PRs.

set-auto-merge-prs:
  - main
  - release

conventional-title

Comma-separated list of allowed Conventional Commits types for PR title validation. Use "*" to accept any type while still enforcing the format <type>[optional scope]: <description>.

Standard types: feat, fix, build, chore, ci, docs, style, refactor, perf, test, revert

# Specific types
conventional-title: "feat,fix,build,chore,ci,docs,style,refactor,perf,test,revert"

# Any type (wildcard) — enforces format only
conventional-title: "*"

See Setting Up CI Checks for details on how validation integrates with check runs.

pypi

PyPI publishing configuration. When set, the server runs a Python module install check on PRs.

pypi:
  token: pypi-AgEIcHlwaS5vcmc...

Tox Configuration

Configures tox test execution per branch. Defined under the repository in config.yaml. See Setting Up CI Checks for details.

tox

The tox key maps branch names to tox environments, with optional sub-keys for extra configuration.

tox:
  args: "-p -v"
  python-version: "3.12"
  main: all
  dev: testenv1,testenv2
  feature: lint,test

tox-python-version (deprecated)

Warning: Deprecated. Use tox.python-version instead. This key still works but logs a warning.

# Deprecated
tox-python-version: "3.11"

# Use instead
tox:
  python-version: "3.11"

Pre-commit

pre-commit

Enable pre-commit checks on pull requests. When enabled, the server runs pre-commit run --all-files in the PR worktree.

pre-commit: true

Container Build Configuration

Configures container image builds using Podman. See Setting Up CI Checks for details.

container

container:
  username: my-user
  password: my-password
  repository: quay.io/myorg/myimage
  tag: latest
  release: true
  context: src
  build-args:
    - BUILD_VERSION=1.0
  args:
    - --format docker

container.oci-annotations

Auto annotations (all default to true when enabled is true):

container:
  # ...
  oci-annotations:
    enabled: true
    static:
      org.opencontainers.image.vendor: "My Organization"
      org.opencontainers.image.licenses: "Apache-2.0"
    auto:
      created: true
      source: true
      revision: true
      version: true
      title: true

Protected Branches

Configures required status checks for branch protection per branch.

protected-branches

Each key is a branch name. The value is either:

• An empty array [] — uses all default status checks
• An array of strings — uses those exact status checks
• An object with include-runs and/or exclude-runs

protected-branches:
  dev: []  # All default checks
  main:
    include-runs:
      - "pre-commit.ci - pr"
      - "WIP"
    exclude-runs:
      - "SonarCloud Code Analysis"
  feature:
    - "lint"
    - "test"

Custom Check Runs

User-defined check runs that execute commands on PR events. See Setting Up CI Checks for details.

custom-check-runs

Each custom check run object:

Warning: Custom check names cannot conflict with built-in check names: tox, pre-commit, build-container, python-module-install, conventional-title, can-be-merged, security-suspicious-paths, security-committer-identity.

custom-check-runs:
  - name: lint
    command: uv tool run --from ruff ruff check
    mandatory: true
  - name: security-scan
    command: TOKEN=xyz uv tool run --from bandit bandit -r .
    mandatory: false
  - name: complex-check
    command: |
      uv run python -c "
      import sys
      print('Running complex check')
      sys.exit(0)
      "

Per-Repository In-Repo Config

The .github-webhook-server.yaml file is committed to a repository's root and provides repository-specific overrides at the highest priority.

Supported Keys

This file accepts any key that is valid under repositories.<name> in config.yaml. The value resolution order is: .github-webhook-server.yaml → repository config in config.yaml → global config in config.yaml.

Common keys used in .github-webhook-server.yaml:

• tox
• pre-commit
• conventional-title
• container
• auto-verified-and-merged-users
• auto-verify-cherry-picked-prs
• can-be-merged-required-labels
• labels
• pr-size-thresholds
• ai-features
• security-checks
• custom-check-runs
• welcome-extra-info
• test-oracle
• set-auto-merge-prs
• minimum-lgtm
• create-issue-for-new-pr
• cherry-pick-assign-to-pr-author
• allow-commands-on-draft-prs
• branch-protection

# .github-webhook-server.yaml (in repository root)
conventional-title: "feat,fix,docs,chore"
pre-commit: true
tox:
  main: all
labels:
  enabled-labels:
    - verified
    - size

Welcome Message File

.github-webhook-server-welcome-message.md

A markdown file committed to the repository root. Its content replaces the welcome-extra-info config value for the Additional Information section of the PR welcome comment.

<!-- .github-webhook-server-welcome-message.md -->
**Contribution Guidelines:**
- All PRs must include tests
- Update CHANGELOG.md for user-facing changes
- Squash commits before merging

Full Example

# config.yaml
log-level: INFO
log-file: webhook-server.log
mask-sensitive-data: true

github-app-id: 123456
github-tokens:
  - ghp_globaltoken1
  - ghp_globaltoken2

webhook-ip: https://webhooks.example.com/webhook_server
webhook-secret: my-secret
ip-bind: 0.0.0.0
port: 5000
max-workers: 10

verify-github-ips: true
disable-ssl-warnings: false

docker:
  username: dockeruser
  password: dockerpass

default-status-checks:
  - "WIP"
  - "can-be-merged"

auto-verified-and-merged-users:
  - "renovate[bot]"

auto-verify-cherry-picked-prs: true
create-issue-for-new-pr: true
cherry-pick-assign-to-pr-author: true

labels:
  enabled-labels:
    - verified
    - hold
    - size
    - can-be-merged
  colors:
    hold: red
    verified: green

pr-size-thresholds:
  Small:
    threshold: 50
    color: green
  Medium:
    threshold: 200
    color: orange
  Large:
    threshold: inf
    color: red

branch-protection:
  strict: true
  required_approving_review_count: 1
  required_conversation_resolution: true

security-checks:
  mandatory: true
  committer-identity-check: true
  trusted-committers:
    - "pre-commit-ci[bot]"

ai-features:
  ai-provider: claude
  ai-model: sonnet
  conventional-title:
    enabled: true
    mode: suggest

test-oracle:
  server-url: "http://localhost:8000"
  ai-provider: claude
  ai-model: sonnet
  triggers:
    - approved

repositories:
  my-service:
    name: my-org/my-service
    log-level: DEBUG
    slack-webhook-url: https://slack-webhook-url/replace-with-your-webhook-url
    events:
      - push
      - pull_request
      - issue_comment
      - check_run
    conventional-title: "feat,fix,chore,docs,ci"
    pre-commit: true
    tox:
      python-version: "3.12"
      main: all
      dev: lint,test
    container:
      username: quayuser
      password: quaypass
      repository: quay.io/myorg/my-service
      tag: latest
      release: true
    protected-branches:
      main:
        include-runs:
          - "tox"
          - "pre-commit"
    custom-check-runs:
      - name: lint
        command: uv tool run --from ruff ruff check
        mandatory: true

Related Pages

• Configuring Repositories
• Configuration Recipes
• Environment Variables
• Setting Up CI Checks
• Enabling Security Checks