Let me explore the codebase to understand all environment variables used in the project.

Let me check how those Docker Compose environment variables map to config.yaml:

Now let me check how the Docker Compose environment variables map to config.yaml settings:

These Docker Compose environment variables appear in the example docker-compose.yaml but are not actually read by the Python code via os.environ. Let me check if there's any mapping logic:

These are only in the Docker Compose example and docs, not actually consumed by the Python app. Let me verify by checking config.yaml examples:

Now let me check the scripts/podman-cleanup.sh for PUID/PGID usage:

Now let me check the exposed ports and any additional env vars:

Now let me also verify the MCP server specifics:

Now I have a thorough understanding. Let me also verify the TZ usage:

Good — TZ is only in the Docker Compose example and isn't read by the application code directly (it's a standard Linux/container env var).

Let me also verify if FORCE_COLOR is just documented or actively used:

Now let me check the exclusion file again to make sure I handle it properly:

These are pages I should not reference. Let me check the pages list again:

The deny-list contains page slugs that I should NOT mention or reference. These are:

• using-the-log-viewer.html
• enabling-ai-features.html
• deploying-with-docker.html

Now I have everything I need. Let me write the documentation.

Environment Variables

All environment variables recognized by the webhook server, grouped by function.

Server Core

WEBHOOK_SERVER_DATA_DIR

Base directory containing config.yaml and the logs/ subdirectory. The server reads its configuration from $WEBHOOK_SERVER_DATA_DIR/config.yaml and writes structured logs to $WEBHOOK_SERVER_DATA_DIR/logs/.

# Local development
export WEBHOOK_SERVER_DATA_DIR=/path/to/my/data
uv run entrypoint.py

# Docker Compose
environment:
  - WEBHOOK_SERVER_DATA_DIR=/home/podman/data  # matches the container default

Note: When running outside Docker, you must set this variable to a directory that contains a valid config.yaml. See Configuration Reference for the full config schema.

WEBHOOK_SERVER_DEV_MODE

Enables Uvicorn's auto-reload mode for development. When enabled, the server watches for file changes and restarts automatically. When disabled, the server starts with the configured number of workers (max-workers in config.yaml, default 10).

WEBHOOK_SERVER_DEV_MODE=true uv run entrypoint.py

Warning: Do not enable in production. Dev mode disables multi-worker support and adds filesystem polling overhead.

ENABLE_LOG_SERVER

Registers the log viewer HTTP and WebSocket endpoints under /logs. When not set to exactly true, all /logs/* endpoints return HTTP 404.

# Enable
ENABLE_LOG_SERVER=true uv run entrypoint.py

# Docker Compose
environment:
  - ENABLE_LOG_SERVER=true

Warning: Log viewer endpoints are unauthenticated. Only enable on trusted networks (VPN, internal). Access is restricted to private/loopback IP ranges, but this can be bypassed behind a misconfigured reverse proxy.

Affected endpoints when enabled:

See Log Viewer API Reference for endpoint details.

ENABLE_MCP_SERVER

Registers the Model Context Protocol (MCP) endpoint at /mcp for AI agent integration. When enabled, the server exposes its API operations as MCP tools that AI agents can discover and invoke.

# Enable
ENABLE_MCP_SERVER=true uv run entrypoint.py

# Docker Compose
environment:
  - ENABLE_MCP_SERVER=true

MCP logging is separated from the main application log. The log file is configured via the mcp-log-file key in config.yaml (default: mcp_server.log).

Warning: The MCP endpoint has no authentication. Deploy only on trusted networks. Use a reverse proxy with authentication for any external access.

Tip: You must restart the server after changing ENABLE_MCP_SERVER. The endpoint registration happens at import time, not at runtime.

AI Sidecar

SIDECAR_PORT

Port on which the Pi SDK sidecar Node.js process listens. The sidecar bridges AI CLI tools (Claude, Gemini, Cursor) for features such as conventional title suggestions and cherry-pick conflict resolution. The sidecar is started automatically by entrypoint.sh if sidecar-helper/dist/server.js exists.

# Override default port
SIDECAR_PORT=9200 uv run entrypoint.sh

# Docker Compose
environment:
  - SIDECAR_PORT=9100

The container health check probes both the main server and the sidecar:

healthcheck:
  test: ["CMD-SHELL", "curl -f http://localhost:5000/webhook_server/healthcheck && curl -f http://localhost:${SIDECAR_PORT:-9100}/health"]

Note: If the sidecar binary is not present or fails to start within 15 seconds, the main server still starts, but AI features will not be available.

ACPX_AGENTS

Enables model discovery for the specified AI agent. Set to cursor to enable Cursor model discovery for AI features.

# Docker Compose
environment:
  - ACPX_AGENTS=cursor

VERTEX_CLAUDE_1M

Enables Claude 1M context window models via Google Vertex AI. Requires Google Cloud credentials to be mounted into the container.

# Docker Compose
environment:
  - VERTEX_CLAUDE_1M=true
volumes:
  - $HOME/.config/gcloud:/home/podman/.config/gcloud:ro

AI CLI API Keys

These environment variables provide authentication credentials for the AI CLI tools used by the sidecar. They are required only when the corresponding AI provider is configured in the ai-features section of config.yaml. See Configuration Reference for ai-features settings.

# Docker Compose — set only the key for your chosen provider
environment:
  - ANTHROPIC_API_KEY=sk-ant-xxx
  # OR
  - GEMINI_API_KEY=xxx
  # OR
  - CURSOR_API_KEY=xxx

Tip: For Cursor interactive login (instead of API key), use: docker exec -it github-webhook-server agent

Container Runtime

PUID

User ID used by the Podman runtime cleanup script to locate stale runtime directories at /tmp/storage-run-{PUID}/.

environment:
  - PUID=1000

PGID

Group ID for container process ownership. Standard Docker/Podman convention for controlling file permissions on mounted volumes.

environment:
  - PGID=1000

TZ

Sets the container timezone. Affects log timestamps and any time-dependent operations.

environment:
  - TZ=Asia/Jerusalem

FORCE_COLOR

Enables colored terminal output in Uvicorn HTTP request logs. Useful when viewing Docker container logs in a terminal that supports ANSI colors. Application-level logs use simple-logger with console=True, which provides colored output independently.

environment:
  - FORCE_COLOR=1

Docker Compose Configuration

The example docker-compose.yaml at examples/docker-compose.yaml includes several environment variables that map directly to keys in config.yaml. These are not read via os.environ by the Python application — they are passed as container environment variables and are available for shell-level substitution or container configuration.

Note: Server settings such as bind address, port, webhook secret, and IP verification are configured in config.yaml, not via environment variables. See Configuration Reference for all config.yaml options.

Docker Compose Example

services:
  github-webhook-server:
    container_name: github-webhook-server
    build: ghcr.io/myk-org/github-webhook-server:latest
    volumes:
      - "./webhook_server_data_dir:/home/podman/data:Z"
      - "/tmp/podman-storage-${USER:-1000}:/tmp/storage-run-1000"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Jerusalem
      - ENABLE_LOG_SERVER=true
      - ENABLE_MCP_SERVER=false
      # - SIDECAR_PORT=9100
      # - ACPX_AGENTS=cursor
      # - VERTEX_CLAUDE_1M=true
      # - ANTHROPIC_API_KEY=sk-ant-xxx
    ports:
      - "5000:5000"
    privileged: true
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:5000/webhook_server/healthcheck && curl -f http://localhost:${SIDECAR_PORT:-9100}/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    restart: unless-stopped

Exposed Container Ports

E2E Test Variables

These variables are used exclusively by the end-to-end test infrastructure. They are loaded from a .dev/.env file and are not relevant to production deployments.

# .dev/.env
SERVER_PORT=5000
SMEE_URL=https://smee.io/YOUR_UNIQUE_CHANNEL
TEST_REPO=owner/repo-name
DOCKER_COMPOSE_FILE=.dev/docker-compose.yaml

Quick Reference

All environment variables in one table:

Related Pages

• Deploying with Docker
• Configuration Reference
• Enabling AI Features
• Using the Log Viewer
• Getting Started