# How Bumpkit Works

> **Beta, early access.** A workspace without access gets `403 FEATURE_EARLY_ACCESS` and a link to request it.

Bumpkit answers four questions about every change you ship:

1. **What changed?**
2. **Is it safe to ship?**
3. **Who or what made it, and was that allowed?**
4. **What did it do in production?**

Each question has its own set of features. Most of them are Beta and sit behind their own flag. Run `bumpkit features` to see which are on for your workspace.

To start using Bumpkit, pick the guide for your role: [Engineering Leads](/docs/quickstart-engineering), [Platform & Security](/docs/quickstart-platform) or [AI Agent Teams](/docs/quickstart-agents).

## 1. What changed?

Bumpkit reads the code between two versions and proves what changed. It doesn't guess from commit messages. It reads 15 languages; see [Supported Languages](/docs/supported-languages). Each finding points to a file and line: a removed API or route, a destructive migration, a committed secret, untested code, a vulnerable dependency.

It also follows the change through the code. Blast radius traces each changed function to every caller, and names the product areas the change reaches. Contract checks compare API schemas on both sides. Quality checks catch code that breaks your architecture or slows things down.

| Feature | What it tells you |
|---|---|
| [Release Checks & Blast Radius](/docs/release-checks) | Every proven finding, the verdict (`ship`, `review` or `block`) and the next version |
| [Blast radius](/docs/release-checks#blast-radius) | Which areas of the product a change reaches, call by call |
| [Regression evidence](/docs/release-checks#regression-evidence) | Whether the tests this change can break passed on the exact commit |
| [Behavioral verification](/docs/release-checks#behavioral-verification) and [test evolution](/docs/release-checks#test-evolution) | Whether behavior changed, and whether the tests changed with it |
| [Intent versus implementation](/docs/release-checks#intent-versus-implementation) | Whether the change does what its ticket asked, with `bumpkit criteria` |
| [Contract Checks](/docs/contract-checks) | Breaking changes in OpenAPI, GraphQL, protobuf and JSON Schema |
| [Code Quality & Architecture](/docs/quality) | Architecture drift, low-quality new code and performance regressions |
| [Cross-Repo Impact](/docs/cross-repo) | Which of your other repositories a breaking change hits |
| [Release Notes & Digests](/docs/release-notes) | Notes for engineers and customers, and migration guides, from the proven changes |
| [Changelog Pages](/docs/changelog-pages) | A hosted changelog and RSS feed for each repository |

## 2. Is it safe to ship?

The release gate takes what changed and applies your policy. It returns one of three outcomes: **pass**, **needs approval** or **fail**.

The policy lives in `bumpkit.yml`. The gate reads it from the base of the change, so a pull request can't loosen its own rules. With the GitHub App installed, Bumpkit reads the file from the base itself, whatever policy the client sends. An org policy can set rules for every repository and lock them. Freezes and release windows stop releases at set times. When a rule needs a person, Bumpkit collects the approval from GitHub, Slack or the dashboard. When something has to ship anyway, an owner, admin or policy admin can break glass, and that is recorded too.

| Feature | What it decides |
|---|---|
| [Release Gate](/docs/release-gate) | Pass, needs approval or fail, on every pull request |
| [bumpkit.yml Reference](/docs/bumpkit-yml) | Every policy key the gate reads |
| [Approvals](/docs/approvals) | Which approvals count, and where people give them |
| [Org Policies & Freezes](/docs/org-policies) | Workspace-wide rules, locked keys, release windows and change freezes |
| [Hotfixes & Break Glass](/docs/hotfixes) | Fast, scoped releases and recorded overrides with a review afterwards |
| [Confidence Score & Leadership](/docs/confidence-score) | A 0 to 100 score on each decision, a per-file risk model and leadership reports with `bumpkit report` |
| [Cross-repo impact in the gate](/docs/cross-repo#cross-repo-impact-in-the-gate) | Approval when a change breaks another repository |
| [Change management](/docs/jira) | Gate decisions sent to Jira, ServiceNow, Vanta and Drata as change-management records |

## 3. Who or what made it, and was that allowed?

Bumpkit works out whether a coding agent wrote each change, and which one. Provenance hooks record the agent, model and session, and the tools it used. Your policy can treat agent-written code differently, for example asking for approval unless a person is confirmed to have written it.

Agent controls keep agents inside the rules while they work. The guard checks their work before they finish. The pause hook stops risky commands until a person agrees. Memory gives every session what the team learned. When several agents share a repository, swarm features stop them colliding and check what they claim to have done.

People get roles, and every decision lands in a tamper-evident evidence record you can give an auditor.

| Feature | What it controls or records |
|---|---|
| [Agent Hooks](/docs/agent-hooks) | Bumpkit inside Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Cline and git |
| [Agent Controls](/docs/agent-controls) | The [guard](/docs/agent-controls#agent-guard), [paused commands](/docs/agent-controls#pause-risky-commands), [codebase memory](/docs/agent-controls#codebase-memory), [provenance](/docs/agent-controls#ai-change-provenance) and [scorecards](/docs/agent-controls#agent-scorecards) |
| [Agent Swarms](/docs/agent-swarms) | Claims, intent, merge planning, verified reports, swarm lessons, the approval inbox, agent budgets and track records, and fix tasks |
| [SSO, SCIM & Roles](/docs/sso) | Who can sign in, and what each person may do |
| [Compliance Evidence](/docs/compliance) | Tamper-evident, signed evidence, SIEM streaming and auditor access |
| [Data Handling](/docs/data-handling) | What Bumpkit stores and sends, and zero retention |

## 4. What did it do in production?

Bumpkit follows a release after it ships. You record each deploy. Bumpkit counts production errors from PostHog, Sentry or a signed webhook, compares the error rate before and after, and names the commit most likely behind a regression.

When something breaks, forensics traces the failure to the release behind it. Rollback plans the smallest revert that undoes it. The time machine finds the release where a symbol, file or finding first appeared.

| Feature | What it shows |
|---|---|
| [Release Health & Forensics](/docs/release-health) | [Deploys](/docs/release-health#record-deploys), [regression verdicts](/docs/release-health#regression-verdicts), [suspect commits](/docs/release-health#suspect-commits) and [what broke production](/docs/release-health#what-broke-production) |
| [Rollback & Time Machine](/docs/rollback) | [Intelligent rollback](/docs/rollback#intelligent-rollback), the [release time machine](/docs/rollback#release-time-machine) and [history queries](/docs/rollback#history-queries) |
| [Regression predictor](/docs/rollback#regression-predictor) | What a change can break, with a likelihood, based on past incidents |
| [Incident sources](/docs/release-health#incident-sources) and [deploy events](/docs/built-in#deploy-events) | Incidents from PagerDuty and Datadog, and deploys from your pipeline |

## Where Bumpkit runs

The same checks and the same gate run wherever you work:

| Where | How |
|---|---|
| CLI | `bumpkit check`, `bumpkit gate` and every other command. See [Getting Started](/docs/) and the [CLI Reference](/docs/cli). |
| GitHub App | A **Bumpkit release gate** check on every pull request, with no workflow to set up. See [The GitHub App](/docs/release-gate#the-github-app). |
| GitLab, Bitbucket and Azure DevOps | A webhook connection, or `bumpkit gate` in your CI pipeline. See [Release Gate](/docs/release-gate#gitlab-bitbucket-and-azure-devops). |
| GitHub Enterprise Server | A webhook connection, or `bumpkit gate` in GitHub Actions on your server. See [Release Gate](/docs/release-gate#github-enterprise-server). |
| Coding agents | Hooks for each agent, and `bumpkit mcp` for any MCP client. See [Agent Hooks](/docs/agent-hooks) and [MCP Server](/docs/mcp). |
| Dashboard | Releases, approvals, policy, settings and evidence at `https://dashboard.bumpkit.dev`. |
| API | Everything above over HTTP at `https://bumpkit.dev/v1`. See the [API Reference](/docs/api-reference). |