Configuration Reference

Reference for config.yaml, repository entries under repositories.<repo-id>, and repository-local .github-webhook-server.yaml overrides. See Configure Repositories for rollout patterns, Set Up Checks and Release Workflows for workflow examples, Enable AI Features for AI setup, Secure Webhooks and Pull Requests for hardening, Supported GitHub Events for event coverage, and Environment Variables for non-YAML settings.

Files and Resolution

Warning: .github-webhook-server.yaml is not consulted for name, log-level, log-file, mask-sensitive-data, github-tokens, events, default-status-checks, protected-branches, allow-commands-on-draft-prs, test-oracle, or pr-size-thresholds. Put those keys in config.yaml.

Note: A repo-local branch-protection block only affects webhook-time required_conversation_resolution handling. GitHub branch protection updates at startup still come from config.yaml.

# config.yaml
github-app-id: 123456
github-tokens:
  - ghp_admin_token
webhook-ip: https://hooks.example.com/webhook_server

repositories:
  github-webhook-server:
    name: my-org/github-webhook-server
    pre-commit: true
    conventional-title: "feat,fix,docs"

# .github-webhook-server.yaml
pre-commit: false
conventional-title: "feat,fix,docs,refactor"

Global Keys

Logging

log-level: INFO
log-file: webhook-server.log
mcp-log-file: mcp_server.log
logs-server-log-file: logs_server.log
mask-sensitive-data: true

GitHub Access and Network

Warning: If verify-github-ips or verify-cloudflare-ips is enabled and no allowlist loads successfully, the server fails closed and does not start.

github-app-id: 123456
github-tokens:
  - ghp_primary_token
  - ghp_fallback_token
webhook-ip: https://hooks.example.com/webhook_server
webhook-secret: <webhook-secret>
verify-github-ips: true
verify-cloudflare-ips: true
disable-ssl-warnings: false
ip-bind: 0.0.0.0
port: 5000
max-workers: 10

Global Repository Defaults

default-status-checks:
  - ci/external
  - policy/manual-approval
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
allow-commands-on-draft-prs:
  - retest
  - build-and-push-container

docker

Where: Global

docker:
  username: dockerhub-user
  password: <dockerhub-token>

Repository Registration

repositories

Where: Global

repositories:
  github-webhook-server:
    name: my-org/github-webhook-server
  docsfy:
    name: my-org/docsfy

Repository Keys

Repo Keys Read From config.yaml Only

Where: Repo

Note: For event behavior after delivery, see Supported GitHub Events.

repositories:
  github-webhook-server:
    name: my-org/github-webhook-server
    log-level: DEBUG
    log-file: github-webhook-server.log
    mask-sensitive-data: true
    github-tokens:
      - ghp_repo_specific_token
    events:
      - pull_request
      - issue_comment
      - push
      - check_run
      - status
    default-status-checks:
      - ci/external
    allow-commands-on-draft-prs:
      - retest
      - build-and-push-container

Repo Keys Read From config.yaml or .github-webhook-server.yaml

Where: Repo/local

Warning: pre-commit is runtime-disabled until you set it to true, even though the schema advertises a true default.

# Either under repositories.<repo-id> in config.yaml
# or at the root of .github-webhook-server.yaml
slack-webhook-url: https://hooks.slack.com/services/TEAM/CHANNEL/TOKEN
verified-job: true
pre-commit: true
conventional-title: "feat,fix,docs,refactor"
minimum-lgtm: 2
set-auto-merge-prs:
  - main
can-be-merged-required-labels:
  - approved
  - security-reviewed
create-issue-for-new-pr: false
cherry-pick-assign-to-pr-author: true

Shared Blocks

branch-protection

Where: Global or Repo

Note: Repo branch-protection values overlay global values field by field.

Note: The can-be-merged check reads the strict setting from GitHub's branch protection on the PR's base branch at evaluation time, not from this config, so a change made in GitHub takes effect on the next event and the cached value never outlives a single event. When GitHub does not expose branch protection (no protection configured, or the token lacks permission), the behind-base check is skipped rather than guessed from config, because a stale value here would fail PRs GitHub would happily merge. The same unreadable protection makes the required status check read fail closed instead of reporting no required checks. The config value still applies when the server sets up branch protection itself.

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

repositories:
  github-webhook-server:
    name: my-org/github-webhook-server
    branch-protection:
      require_code_owner_reviews: true
      required_approving_review_count: 2

labels

Where: Global or Repo/local

Note: Reviewed-by labels such as approved-*, lgtm-*, commented-*, and changes-requested-* are always enabled.

Tip: Use pr-size-thresholds to control size/* label names and colors.

labels:
  enabled-labels:
    - verified
    - hold
    - size
    - branch
  colors:
    hold: red
    verified: green
    approved-: blue
    branch-: darkorange

welcome-extra-info

Where: Global or Repo/local

Note: If .github-webhook-server-welcome-message.md exists in the repository, its contents replace welcome-extra-info. An empty file suppresses configured welcome text.

welcome-extra-info: |
  Please link the tracking issue.
  Review the release checklist before merging.

security-checks

Where: Global or Repo/local

Note: Built-in suspicious-paths defaults are .claude/, .vscode/, .cursor/, .devcontainer/, .pi/, .github/workflows/, and .github/actions/.

Note: The server automatically trusts the GitHub App bot login, web-flow, and the API users behind github-tokens.

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

ai-features

Where: Global or Repo/local

Warning: Repo/local ai-features replaces the global block. Repeat ai-provider and ai-model in every override.

Note: Cherry-picks resolved with AI are never auto-verified.

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

Where: Global or Repo

Note: approved refers to the /approve command path used by this server. The /test-oracle command works whenever the block is configured.

Warning: Repo test-oracle replaces the global block. .github-webhook-server.yaml does not override this block.

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

pr-size-thresholds

Where: Global or Repo

Note: Built-in thresholds are size/XS for <20, size/S for <50, size/M for <100, size/L for <300, size/XL for <500, and size/XXL otherwise.

Warning: Repo pr-size-thresholds replaces the global block. .github-webhook-server.yaml does not override this block.

pr-size-thresholds:
  XS:
    threshold: 20
    color: lightgray
  M:
    threshold: 100
    color: orange
  XXL:
    threshold: inf
    color: darkred

Repository-Only Blocks

tox

Where: Repo/local

Warning: Use exact branch names and string env lists. The runtime does not expand branch globs, and array branch values are not normalized before execution.

Note: If a tox block exists but no branch key matches the PR base branch, tox still runs with the repository’s default tox configuration.

tox:
  main: all
  develop: unit,lint
  args: "-p -v"
  python-version: "3.11"

protected-branches

Where: Repo

Warning: Use exact branch names and the object form shown below. The schema accepts array shorthand, but the startup branch-settings path reads the object form.

repositories:
  github-webhook-server:
    name: my-org/github-webhook-server
    protected-branches:
      main: {}
      develop:
        include-runs:
          - can-be-merged
          - verified
          - tox
        exclude-runs:
          - pre-commit.ci - pr

pypi

Where: Repo/local

pypi:
  token: <pypi-token>

container

Where: Repo/local

container:
  username: quay-user
  password: <quay-token>
  repository: quay.io/example/my-image
  tag: latest
  release: true
  build-args:
    - VERSION=1.2.3
  args:
    - --platform=linux/amd64
  context: src/app
  dockerfile: Dockerfile

container.oci-annotations

Where: Repo/local

Warning: container.context must stay under the repository root. Path traversal is rejected at runtime.

container:
  username: quay-user
  password: <quay-token>
  repository: quay.io/example/my-image
  oci-annotations:
    enabled: true
    static:
      org.opencontainers.image.vendor: Example Corp
    auto:
      created: true
      source: true
      revision: true
      version: true
      title: true

custom-check-runs

Where: Repo/local

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

Note: The server validates that the command has an executable after any leading environment assignments, and that the executable exists on the server.

custom-check-runs:
  - name: lint
    command: uv tool run --from ruff ruff check
    mandatory: true
  - name: security-scan
    command: TOKEN=value uv tool run --from bandit bandit -r .
    mandatory: false

Related Pages

• Configure Repositories
• Set Up Checks and Release Workflows
• Enable AI Features
• Secure Webhooks and Pull Requests
• Environment Variables