CLI: Checks & gate ​

Check what changed, gate the release and manage the policy behind it.

Check a connected GitHub pull request ​

bumpkit github check 7 --repository acme/shop
bumpkit github check 7 --repository acme/shop --json

Runs the same live pull request check as the dashboard using the workspace's GitHub App installation. Sign in with bumpkit login; machine keys cannot request this action. Your account needs a workspace role that can run checks, and the GitHub App must have access to the repository. If --repository is omitted, the command uses the checkout's origin remote.

Bumpkit fetches the current open PR and its exact commit, applies the base branch policy, verifies required CI and reviews, saves the decision and publishes a GitHub check. A manual check does not post a PR comment or trigger follow-up automation. The output links to the saved decision and GitHub check.

Exit codes: 0 passed, 1 blocked or needs approval, 2 could not complete, 3 waiting for required CI. After CI finishes, run the command again; a waiting result is not a passing decision.

Read a saved release decision ​

bumpkit decisions view CHECK_OR_DECISION_ID
bumpkit decisions view CHECK_OR_DECISION_ID --json

Use the saved release check ID or gate decision ID from Bumpkit. This reads recorded evidence only: repository and exact commit, outcome, policy reasons including CI, approvals and their source, retained policy text, and findings. It does not run a check, generate new evidence, query GitHub, or change a decision. A release check with no saved gate decision is reported as such.

Workspace-scoped read access is sufficient. A foreign workspace's ID returns not found. --json preserves the complete recorded response for scripts. Reading a saved failing decision exits successfully; the saved outcome remains fail.

bumpkit approvals lists the releases waiting for a person's approval, and bumpkit approvals show ID shows what one waits on and the votes so far. To vote, run bumpkit approvals approve ID, bumpkit approvals deny ID, bumpkit decisions approve CHECK_ID or bumpkit decisions deny CHECK_ID. Each prints a link and a one-time code, opens your browser, and waits while you confirm the vote signed in to Bumpkit; the CLI's API key never votes on its own. The vote needs an active workspace role with write permission, a linked GitHub identity, and eligibility under the saved release's approval policy. The check must refer to the current PR commit; a new push makes an old check ineligible.

When you confirm, the vote is recorded against that exact commit and the shared gate runs again, as for any dashboard vote. Recording a vote does not promise a pass, merge, or deployment. Repeating a vote updates that reviewer's vote rather than creating duplicates. These votes differ from inbox approval actions, and there is no --note option.

bumpkit check ​

Check a release and list what it proves. The output gives the verdict, the decided version, a summary, each finding above info with its location, and the affected areas. See Release Checks & Blast Radius.

bumpkit check [--base REF] [--head REF|working-tree] [--json]

bumpkit check --base v1.4.2 --head working-tree

Beta: --comment ​

bumpkit checks ​

List and view release checks.

checks list flags:

With --recorded, Bumpkit groups check runs into releases the way the Releases page does and shows each release's latest decision. Use --limit 50 to match the page. The default list includes working-tree previews.

checks queue lists the GitHub pull request checks that haven't finished yet, plus any whose Bumpkit release gate check failed after retries, with the same wording as the Queued, running, retrying and failed pull request checks panel on the Checks page:

The checks_queue MCP tool returns the same list.

bumpkit gate ​

Decide whether a release ships under your policy. In GitHub Actions, gate finds the pull request, its base commit and its approving reviews by itself. A branch named hotfix/, hotfixes/, release/ or releases/ (or with - instead of /) is gated as a hotfix. See Release Gate.

bumpkit gate [--base REF] [--policy FILE] [--comment] [--json]

With the GitHub App installed, --base only sets what the diff is compared against. Bumpkit reads the policy from the default branch, or from the base commit of a pull request into the default branch.

With Close the loop on (flag close_the_loop), gate also reports the fix tasks it found in the local checkout, such as callers still on a changed function's old signature, and its output gains a Close the loop section. See bumpkit loop.

bumpkit gate --comment

--comment only comments from a CI job running for a pull request: GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure Pipelines, Buildkite, CircleCI or Jenkins. Run from a laptop, gate can't tell which pull request the checkout belongs to, so it prints the decision and posts nothing. With the Bumpkit GitHub App installed, you don't need --comment at all: the App's automatic run on every push posts the single bumpkit[bot] comment on the pull request and edits it in place as the decision changes.

Beta: --spec, --bench-base and --bench-head ​

Beta, early access. Flags: intent_check, performance_diff.

Other CI systems ​

Inside GitLab CI, Bitbucket Pipelines, Azure Pipelines, Buildkite, CircleCI or Jenkins, gate reads the merge or pull request, its base and its repository from that CI's variables. It uses the tokens listed under CI variables to read approvals and post --comment. See Run it in CI for the setup for each.

bumpkit gate connections connects GitLab, Bitbucket, Azure DevOps or GitHub Enterprise Server to the release gate (owners and admins). A connection lets Bumpkit run the gate on merge and pull requests there and verify approvals. The access token is stored encrypted. The webhook secret is shown only once, when you add the connection.

gate connections add flags:

gate connections remove takes -y, --yes to skip the confirmation.

bumpkit gate connections add --provider gitlab --path acme/api

bumpkit approvals ​

List the releases in this workspace that wait for a person's approval: repository, pull request, exact commit, how many votes are in and when it was requested. bumpkit approvals with no subcommand is the same as bumpkit approvals list.

bumpkit approvals
bumpkit approvals show APPROVAL_OR_CHECK_ID
bumpkit approvals approve APPROVAL_OR_CHECK_ID
bumpkit approvals deny APPROVAL_OR_CHECK_ID --no-browser

show prints the rules still asking for approval, from whom, and the votes so far. approve and deny start a browser confirmation with a one-time code and wait for it; nothing is recorded from the API key alone. --no-browser prints the link without opening a browser, and --timeout limits the wait. Add --json to any of them for the stored fields.

bumpkit approvals commands list ​

Read stored agent command decisions for the current workspace without running or re-evaluating commands. Requires a person-bound API key and access to agent_pause; workspace viewers can read the list.

bumpkit approvals commands list --status recent --limit 20
bumpkit approvals commands list --status pending --limit 50

recent is the default and includes decided commands and expired requests, newest first. pending includes only unexpired requests awaiting a decision. Limits range from 1 to 500; omitting --limit uses 20 for recent or 50 for pending, matching the dashboard. Add --json for stored decision fields and the response time used to label expired requests.

bumpkit override ​

A break-glass override needs a person signed in to the dashboard: an owner, admin or policy admin, on the commit's check page. This command sends the request, and the server refuses an API key with 403 HUMAN_APPROVAL_REQUIRED and the link to the page. An override applies to that exact commit only, so a new push needs a fresh decision. It is kept in the gate decision, the audit log and the compliance evidence. A repository can forbid overrides with break_glass: false in bumpkit.yml. See Hotfixes & Break Glass.

bumpkit override --reason TEXT [flags]

With neither --pr nor --sha, the command looks up the open pull request for your current branch; if there isn't one, it lists the pull requests waiting on the gate. With both flags, --sha must be the pull request's head.

override list flags: --limit (default 100, max 500) and --overdue (only overrides whose review is past due). override review takes --note, what the review found (kept in the audit record).

bumpkit rules ​

Write a release rule in plain English. Bumpkit turns it into bumpkit.yml gate policy, shows the change as a diff and dry-runs it on recent gate decisions. Nothing takes effect until an owner, admin or policy admin approves it and the pull request that adds it to bumpkit.yml is merged, because the gate reads the policy from the base branch.

rules compile flags:

rules approve takes --open-pr (open a pull request through the Bumpkit GitHub App) and -y, --yes. rules list takes --limit (default 50, max 200).

bumpkit rules compile "Changes to the payments folder need approval from @acme/payments" --dry-run

bumpkit criteria ​

Beta, early access. Flag: intent_check.

Map a ticket's acceptance criteria to the evidence in a change. Criteria come from the pull request description, the GitHub, Jira or Linear issues it links, and any --spec files: Markdown checklists, Acceptance criteria sections and Given/When/Then lines. With --llm, Bumpkit's AI extracts them from free-form text instead. Each criterion is mapped to the changed files, the tests touching them and the behavioral verification results for the head, and reported as covered or not evidenced.

This is never a pass or fail on its own. gate.require_approval: [intent] asks for an approval when a criterion lacks evidence. Jira needs JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN; Linear needs LINEAR_API_KEY.

bumpkit criteria [--base REF] [--spec FILE]... [--llm] [flags]

bumpkit criteria --spec docs/specs/export.md

bumpkit policy ​

Beta, early access. Flag: org_policies.

Show and change the org-wide gate policy. An org policy is a bumpkit.yml with an optional top-level locked: list of gate keys that repositories may only tighten. See Org Policies & Freezes.

policy show --effective merges the org policy with this repository's bumpkit.yml (as it is at --base, as the gate reads it). It shows each key's value and where it came from: default, org, repo or org+repo. A loosened value of a locked key is ignored and explained.

policy set saves a new version from FILE or exact YAML passed with --content, points the org policy at a config repository with --repository (its bumpkit.yml on the default branch is read at gate time), or removes it with --clear. Every version is kept and audited. --content is mutually exclusive with FILE, --repository and --clear; parsing and confirmation still apply.

policy history takes --limit (default 20).

bumpkit policy set org-policy.yml --message "Require CI everywhere"

bumpkit freeze ​

Beta, early access. Flag: change_freezes.

Declare, list and end change freezes. While a freeze is on, the gate fails every pull request (with --mode approve, it asks for an approval instead). Hotfixes need an approval by default. A break-glass override still lets a specific commit through when the repository allows overrides. Freezes are audited. Owners, admins and policy admins can declare one or end it early. See Org Policies & Freezes.

freeze start flags:

bumpkit freeze start --reason "Incident 42: payments degraded" --for 4h

bumpkit blast-radius ​

Beta, early access. Flag: blast_radius.

Show which areas of the product a change reaches, call by call, in any of the supported languages. Each area comes with its call path and the file and line of every call.

Areas come from gate.blast_radius.approve_areas, the areas in require_approval, CODEOWNERS, and otherwise the top-level directory. gate.blast_radius.max_depth limits how far callers are followed. See Release Checks & Blast Radius.

Under the summary line, the report lists any files it didn't analyze, like 4 files over 1 MB not analyzed. With --json, the same lines are in notes, the counts are in skipped, and cache says how many files were reused from earlier runs and how many were read again. See Files Bumpkit doesn't analyze.

bumpkit blast-radius [--base REF] [--head REF] [--json] [flags]

bumpkit blast-radius --base v1.4.0 --head HEAD --json

bumpkit contains ​

Find a commit by ref or by text in its message, then list every release tag and remote branch that contains it, directly or as a cherry-pick. See Hotfixes & Break Glass.

bumpkit contains REF_OR_TEXT

bumpkit contains "null pointer in checkout"

bumpkit predict ​

Beta, early access. Flag: regression_predictor.

Rank the existing functionality a change can break, with a likelihood. Each area the change reaches is ranked against the repository's history: production incidents in that code, releases that changed the same files before an incident, and proven findings. A percentage shows only where Bumpkit has measured one from your releases; otherwise you get the evidence and no percentage.

bumpkit predict [--base REF] [--head REF] [flags]

bumpkit when ​

Beta, early access. Flag: release_time_machine.

Find the first release where a symbol, file, finding or dependency appeared, the commit that introduced it, and what changed it after. --symbol, --file and --edge read this checkout at every release tag. --kind and --text search the findings of every release Bumpkit checked. See Rollback & Time Machine.

bumpkit when (--symbol NAME | --file PATH | --edge FROM->TO | --kind KIND | --text TEXT) [flags]

bumpkit when --edge 'services/api->services/db'

bumpkit quality ​

Beta, early access. Flags: architecture_drift, slop_tracker, performance_diff.

Show architecture drift, code quality and performance changes between two versions of a codebase in any of the supported languages. Each analysis runs when its feature is on for your workspace. bumpkit gate sends the same findings with the release, and gate.quality decides whether they hold it. See Code Quality & Architecture.

bumpkit quality [--base REF] [--head REF] [--bench-base FILE --bench-head FILE] [--json] [flags]

bumpkit quality --base v1.4.0

bumpkit tests ​

Beta, early access. Flag: test_evolution.

List new behavior no test reaches, suggest tests, and find obsolete ones. It lists each new function or method, and each changed one that gained branches, that no test reaches, with its file and lines. With --coverage, a function counts as tested only when the profile shows its lines run; otherwise a test must refer to it by name.

Obsolete tests are tests that refer to symbols this release removes and, with --results, tests that never failed and never touched changed code in the last --releases releases.

bumpkit tests [--base REF] [--head REF] [--coverage FILE] [--results FILE] [--patch FILE] [flags]

go test -coverprofile=cover.out -json ./... > results.json
bumpkit tests --coverage cover.out --results results.json --patch tests.patch

bumpkit verify ​

Beta, early access. Flag: behavioral_verification.

Run the base and head side by side in your CI, never on Bumpkit's servers, and compare how they behave. verify checks out both versions into separate worktrees and runs:

• the project's test command at both versions (verify.test, or detected from go.mod, package.json or pyproject.toml)
• for Go, each changed exported function called with the same generated inputs at both versions
• for HTTP services (verify.http.start), recorded requests (verify.http.requests) and requests derived from the OpenAPI spec, replayed against both versions on separate localhost ports
• with Playwright, verify.browser.pages compared by text, DOM structure and screenshot

Commands run with a time limit (verify.timeout), CPU and memory limits where the operating system supports them, and a safe set of environment variables. Unless verify.network is allow, they get no network beyond localhost: in a network namespace on Linux when unshare is available, and otherwise through proxy settings that point nowhere and offline package managers. The report records which isolation ran. The report is uploaded signed with the API key. In GitHub Actions with id-token: write, it is also attested by the job's OIDC token. gate.require_checks: [behavior] requires the report and, by default, accepts only an attested one: the gate uses the latest attested report for the commit, so a later report signed only with a key neither replaces nor blocks it. With the GitHub App installed, a report doesn't count if the pull request changes what that CI run executes (anything under .github/, or a local action or script the default branch's workflow names), or if it comes from a merge commit that isn't that pull request's current one. The workflow still runs the pull request's own code and tests. verify.require_ci_attestation: false in your repository's policy opts out and trusts anyone with a key. A regression or a failing test fails; a changed response or return value needs a person's approval.

bumpkit verify [--base REF] [--head REF] [--no-upload] [flags]

bumpkit history ​

List releases that changed the repository or a path. With --tree, print the version tree instead.

bumpkit history [PATH] [--tree] [flags]

--tree shows every release Bumpkit checked, newest first: its commit range, verdict and gate outcome, the environments it's live in (●) or was live in, the incidents traced to it, and the rollback pull requests that undo it.

acme/shop
Live now: production v1.0.0 since 2026-10-23, staging v1.2.0 since 2026-10-23
● v1.2.0  live in staging  was live in production
│ 2026-10-23  v1.1.0…3c9e1f2  1 commit  Looks safe, gate: Ready to ship
│ ↩ Roll back to v1.0.0 (fix_opened) https://github.com/acme/shop/pull/12
│
○ v1.1.0  was live in production
│ 2026-10-22  v1.0.0…8d1a4b7  2 commits  Looks safe, gate: Ready to ship
│ ! Checkout totals are 10% short
│
● v1.0.0  live in production
  2026-10-21  v0.9.0…5f2e0c1  1 commit  Looks safe

bumpkit loop ​

Beta, early access. Flag: close_the_loop.

Show what Bumpkit found, who it routed it to, the fix it opened, and what proved it done. Every rollback, back-port and fix task has a lifecycle: found, routed (to whom), fix opened (the pull request), and verified (by which gate decision, at which commit), or still open. Open items are listed by default.

A fix task comes from a gate run that left callers on an old contract: it lists each caller by file and line, the symbol change and the expected edit. When the change is mechanical (a rename, or one removed parameter, with every caller in the repository), Bumpkit opens the edit as a pull request into the author's branch; otherwise it routes the task to the authoring agent and the pull request. Only a later gate run marks a task verified, once it proves every listed place clean. Go code is analyzed today. gate.fix_tasks (block, approve or off) decides what open tasks do to the gate; see the bumpkit.yml Reference.

bumpkit loop [--branch BRANCH | --mine] [--check ID] [--kind rollback|backport|fix_task] [--all] [flags]

bumpkit loop --all

rollback Roll back v1.1.0 for Checkout total is 10% short  acme/shop (fix_opened)
  Pull request: https://github.com/acme/shop/pull/1
  Routed to: reviewers of https://github.com/acme/shop/pull/1
  d464ec7 feat: launch 10% discount on every price
  2026-10-23 14:45  found      Regression in v1.1.0 (incident f6fb0ef)
  2026-10-23 14:45  fix_opened Opened https://github.com/acme/shop/pull/1 reverting d464ec7 onto main

Playground previews ​

Run the same built-in sample and edited policy as the dashboard Playground, from any directory. A connected repository is not required. The hosted preview uses your signed-in user's workspace and feature access, applies the same usage and rate limits, and does not save a release decision or post to a code host.

bumpkit playground examples
bumpkit playground run --example session-token
bumpkit playground run --example agent-breaking --policy bumpkit.yml --json
bumpkit playground run --example drop-column --policy-stdin <<'BUMPKIT_POLICY'
gate:
  block_on: [secret, data_loss]
BUMPKIT_POLICY

Available example IDs are session-token, drop-column, stripe-key, and agent-breaking. Omit the policy flags to use the dashboard's default Playground policy. An explicitly supplied empty policy stays empty.

For a custom diff, pipe the diff to --diff-stdin and supply the policy as a file:

git diff main..HEAD | bumpkit playground run --diff-stdin --policy bumpkit.yml --message 'fix: update validation' --previous 1.2.3

When both the diff and edited YAML must come through stdin, use --request-stdin with one JSON object containing diff, message, policy, and previous, or example, policy, and previous. This mode cannot be combined with the other input flags. Stdin and policy text are treated as data; Bumpkit does not execute pasted scripts or repository commands.

--json prints the gate decision, findings, version, report preview, optional blast radar, checked diff, and explicit preview, saved, and posted flags. Exit codes are 0 for pass, 1 for fail or needs approval, and 2 when the preview cannot run. Built-in examples use the sample's previous version unless --previous overrides it. Limits are 1 MiB for diff, 32 KiB for policy, 16 KiB for commit message, and 64 bytes for previous version.