Stampbot

Stampbot is a GitHub App that approves pull requests when repository policy says it may. A label or an authorized @stampbot comment can create an approval. Stampbot can withdraw its own approval too.

It never merges a pull request, changes branch protection, grants access, or reviews as a person. That boundary is the point.

Visit the Stampbot project site for the short version, or keep reading for a working setup.

Choose when Stampbot may approve

Policy lives in stampbot.toml on the repository's default branch. This small policy approves pull requests carrying the autoapprove label:

approval_labels = ["autoapprove"]
reapprove = false
chatops_required_permission = "maintain"

Label approval can also require another label, a matching title, a named author, or membership in an organization team. Every configured filter category must pass. Values inside a category are alternatives.

ChatOps follows a separate rule. A commenter with the configured repository permission can write @stampbot approve or @stampbot unapprove; label filters don't apply to that command.

Removing an approval label dismisses Stampbot's active reviews. A new commit doesn't receive another approval unless reapprove = true or an authorized maintainer asks for one.

The configuration reference lists every key, limit, default, and fallback.

Try it from source

Install Git, Make, Poetry, and Python 3.11 or newer. Then run:

git clone https://github.com/dannysauer/stampbot.git
cd stampbot
make install-dev
STAMPBOT_SETUP_ENABLED=true \
STAMPBOT_BASE_URL=http://localhost:8000 \
make dev

Check the process from another terminal:

curl -fsS http://127.0.0.1:8000/health

It should return:

{"status":"healthy"}

Open http://127.0.0.1:8000/setup to create a development GitHub App. The wizard is off by default and uses only the STAMPBOT_BASE_URL you supplied. Request headers can't change its callback or webhook destination.

GitHub can't deliver a webhook to localhost. Before testing a real pull request, put port 8000 behind a public HTTPS tunnel and restart Stampbot with that origin as STAMPBOT_BASE_URL. The installation guide walks through the App permissions, credentials, and production runtimes.

Pick a runtime

Goal	Guide
Run from source or a container	Install Stampbot
Run on Kubernetes	Install the Helm chart
Deploy through the repository's Google Cloud workflow	Deploy to Cloud Run
Promote a signed image or chart	Verify a release

The app exposes liveness and readiness, plus structured logs and optional OpenTelemetry traces. Operators can enable Prometheus metrics on a separate listener. Start with the runbook.

Understand the boundary

GitHub sends a signed webhook. Stampbot verifies the signature before parsing the body, loads policy from GitHub, and acts through the App installation that received the event. GitHub remains the source of truth for review state.

Stampbot is not a native code owner. GitHub does not treat an App's bot account as a valid CODEOWNERS owner. For path-level bot ownership, use Extra CODEOWNERS and read its safety boundary before replacing GitHub's native code-owner review rule.

The architecture traces the complete request path. The security requirements state the properties a change must preserve.

Find the rest

The documentation index routes readers by task. These files cover project work:

• contributing explains local checks and pull requests;
• security explains private vulnerability reporting;
• governance records ownership and decisions; and
• roadmap records planned work.

Stampbot is licensed under the Apache License 2.0.