# Connect a repository and get your first decision

Start on the **Repository** page of the [dashboard](https://dashboard.bumpkit.dev). Setup connects GitHub through the Bumpkit GitHub App. GitLab, Bitbucket and Azure DevOps gates are Beta, in early access, and connect from **Integrations** with an access token and a webhook, or run as `bumpkit gate` in CI; see [Release Gate](/docs/release-gate#gitlab-bitbucket-and-azure-devops). Cursor Origin is coming soon. This walkthrough uses GitHub with `acme/shop` as a placeholder repository.

Every dashboard page has **Web**, **CLI** and **MCP** modes at the top. CLI mode shows the page as a terminal session: for each section, a `#` line that says what it does, the exact `bumpkit` command for the current workspace, repository, pull request, check or period, and the output that command prints for the same data you see in Web mode. The page's actions follow as their exact commands; destructive ones spell out `--yes` and are never run for you. Copy one command, or copy them all as a script. MCP mode shows prompts you can paste into your coding agent, each with the exact Bumpkit MCP tool call it makes, plus setup for Claude Code, Codex and Cursor.

You need a Bumpkit workspace and permission to install a GitHub App on the test repository. The repository must have at least one commit and a `README.md` for this walkthrough. Use a repository you own or administer, and substitute its URL for `acme/shop` throughout. The GitHub App, release checks and the release gate are on for every workspace from the start.

You do **not** need a CLI, API key, teammate, custom policy or monitoring account for this first decision.

## 1. Install the GitHub App and verify the repository

1. Sign in to the Bumpkit workspace you want to use, then open **Repository**.
2. Choose **Connect GitHub**, or the **GitHub** card under **Code host**. Select the GitHub account that owns the repo.
3. Choose **Only select repositories**, select **shop**, review the permissions GitHub shows, and install.
4. Back in Bumpkit, the page verifies access as soon as you return.
5. Continue when the page says **Repository access verified** for that exact repository.

To add another repository later, choose **Add a repository**, pick it from the list of repositories the App can read, and choose **Verify access**.

If GitHub offers **Request** instead of **Install**, your GitHub organization owner needs to approve the install request. The Repository page says it's waiting for them, and Bumpkit connects the installation automatically once they approve it; **Check again** picks it up if you're back sooner. If the App is already installed on that account, GitHub shows **Configure** instead, and saving there connects it the same way. Review the repository access and permissions on GitHub's installation screen; you do not need to create a personal access token.

A GitHub account can be connected to one Bumpkit workspace. If it's already connected to another workspace, the page names that workspace: ask its owner to disconnect it under **Integrations → GitHub**, or install on a different GitHub account.

Using GitLab, Bitbucket or Azure DevOps? Pick it under **Code host** on the Repository page and follow the steps there. See [GitLab, Bitbucket and Azure DevOps](/docs/release-gate#gitlab-bitbucket-and-azure-devops).

GitHub sign-in only identifies you. **App access granted** means a GitHub installation is linked to the Bumpkit workspace. **Code access verified** (or **Repository access verified**) additionally means Bumpkit can read that repository's contents through the linked installation. These are separate states.

If verification fails, check that you selected the exact repository in the installation and are using the intended Bumpkit workspace. An API key does not replace the GitHub App installation.

## 2. Open a README pull request

Use a documentation change to test the connection before changing application behavior.

1. From setup, choose **Edit README on GitHub**.
2. Add a short note to the README, such as `Local smoke test: run the service and request its root endpoint.`
3. Choose **Create a new branch**, propose the change, and create a pull request.
4. Open the pull request's **Checks** tab. Wait for **Bumpkit release gate**.

An installed GitHub App runs the gate without a workflow file or API token. Bumpkit reads `bumpkit.yml` from the pull request's base branch, or uses its default policy when that file is absent. A README-only change should normally pass; inspect any findings rather than assuming the result.

## 3. Read the decision

Return to setup, refresh the result, then open the release decision. Saved results are listed under **Release decisions**. Check that the repository and head commit match your pull request before reading the findings. If they do not match, wait for your pull request's check to complete and refresh again.

| Gate outcome | Meaning | Next action |
| --- | --- | --- |
| Pass | The configured policy allows the change. | Review the change through your normal process. |
| Needs approval | A policy rule requires a qualifying reviewer. | Read the rule and request the required approval. |
| Fail | A policy rule blocks the change. | Open the finding, fix it, and push a new commit to rerun the gate. |

A release **check** lists findings. The **gate** applies policy and returns the decision. A passing gate does not deploy the application.

Setup is verified when a pull request in your selected repository has a gate result and you can open its findings in Bumpkit. A CLI analysis or a saved integration credential alone does not prove this flow works.

## If the check never appears

- Confirm the GitHub App is installed for the exact repository and linked to the workspace you signed into.
- Confirm the setup page shows the required beta features are enabled.
- Open a new pull request or push a commit after installation; an existing unchanged pull request may not produce a new event.
- If repository verification succeeds but new pull requests still receive no check, contact Bumpkit support with the repository and pull request URL. Do not paste API keys or tokens.

## Optional: let your agent assist

The setup page has **Copy setup prompt**. It copies a checklist for your coding agent; it does not connect accounts or install anything by itself. You approve GitHub permissions and review the proposed change before publishing. The agent must report a concrete gate result or explain the blocker.

## After the first decision

Add capabilities when you need them:

- **Check an existing pull request:** open **Checks**, choose a connected repository and an open pull request, then run the check. This reads the live PR revision, saves a decision and publishes a GitHub check; it does not merge or deploy the change.
- **Custom policy:** commit [`bumpkit.yml`](/docs/bumpkit-yml) to the default branch before testing changes that should follow it.
- **Enforce at merge:** require **Bumpkit release gate** in GitHub branch protection. Reporting a check and preventing a merge are separate actions.
- **Human approval:** invite a teammate when a policy requires approval. A pull request author's own approval does not count.
- **Local work:** install and sign in to the [CLI](/docs/cli), then add [agent hooks](/docs/agent-hooks) or the [MCP server](/docs/mcp).
- **Production feedback:** connect [monitoring and notifications](/docs/integrations) after the repository-to-gate flow works.