v1.0.0

First stable release of doco-cd-webhook-proxy — a security-hardening proxy that validates GitHub push webhooks and forwards sanitized requests to doco-cd, so doco-cd (and its docker.sock) never has to be exposed to the internet.

Why

doco-cd needs docker.sock, which makes it effectively root on the Docker host — exposing it directly to the internet for webhooks is risky, and polling is slow. This proxy sits in between: deployments still trigger instantly via webhooks, but doco-cd stays on an internal network.

Highlights

• Full webhook validation pipeline: HTTP method, source IP, content type, event type, body size limit, HMAC-SHA256 signature, payload parsing, repository allowlist, and clone URL validation
• Fail-closed security model: the original request is never forwarded — a new minimal request is constructed from validated fields only; missing or invalid config refuses to start
• GitHub IP allowlisting: sender IPs are checked against GitHub's published meta API ranges, refreshed in the background with ETag caching
• Independent HMAC secrets: verifies inbound GitHub signatures and signs outbound requests to doco-cd with separate secrets
• Zero dependencies: Go standard library only — no third-party supply chain
• Container-friendly: single static binary, runs as an unprivileged user with a read-only filesystem; secrets support _FILE variants for Docker secrets

Getting started

Multi-arch images (amd64/arm64) are published to GHCR:

ghcr.io/strayer/doco-cd-webhook-proxy:1.0.0

See the README for a full Docker Compose example.

Configuration

Variable	Required	Default	Description
GITHUB_WEBHOOK_SECRET	yes		Secret shared with GitHub for signature validation
WEBHOOK_SECRET	yes		Secret used to sign requests to doco-cd (same variable name as doco-cd, so both can share one value)
DOCO_CD_URL	yes		Internal doco-cd URL (e.g. http://doco-cd:80)
ALLOWED_REPOS	yes		Comma-separated repository full names (e.g. org/repo1,org/repo2)
LISTEN_ADDR	no	:8080	Address to listen on
TRUSTED_PROXY_CIDRS	no		Comma-separated CIDRs of trusted reverse proxies
GITHUB_META_REFRESH_INTERVAL	no	1h	How often to refresh GitHub IP ranges

Secret variables support a _FILE suffix to read the value from a mounted file.

Changes since v1.0.0-rc.1

• DOCO_CD_WEBHOOK_SECRET was renamed to WEBHOOK_SECRET so proxy and doco-cd can share one env file (#7)
• Project licensed under Apache 2.0 (#4)
• Go 1.26.4, Renovate dependency automation, CI hardening

Full Changelog: v1.0.0-rc.1...v1.0.0

v1.0.0-rc.1

v1.0.0-rc.1

First release candidate of doco-cd-webhook-proxy, a security-hardening reverse proxy that validates GitHub push webhooks before forwarding them to doco-cd.

Highlights

• Full webhook validation pipeline: Method, source IP, content-type, event type, body size limit, HMAC-SHA256 signature verification, payload parsing, repository allowlist, and clone URL validation
• Fail-closed security model: Requests are never forwarded raw; a new request is constructed from validated fields only
• GitHub IP allowlisting: Validates sender IP against GitHub's published meta API ranges with background refresh and ETag caching
• HMAC signing: Verifies inbound GitHub signatures and signs outbound requests to doco-cd independently
• Docker secrets support: All secret config values support a _FILE suffix for mounted secrets

Configuration

Variable	Description
LISTEN_ADDR	Address to listen on (default :8080)
GITHUB_WEBHOOK_SECRET	Shared secret for inbound GitHub HMAC verification
DOCOFORWARD_URL	doco-cd endpoint URL
DOCOFORWARD_SECRET	Shared secret for outbound HMAC signing
ALLOWED_REPOS	Comma-separated owner/repo allowlist
TRUSTED_PROXY_CIDRS	Comma-separated CIDR ranges for trusted proxies
GITHUB_META_REFRESH_INTERVAL	Refresh interval for GitHub IP ranges (default 24h)
GITHUB_META_URL	Override GitHub meta API URL (for GHE or testing)

All secret variables support a _FILE suffix to read the value from a mounted file.

Full Changelog: https://github.com/strayer/doco-cd-webhook-proxy/commits/v1.0.0-rc.1