Connecting a Bitbucket Repo

Bitbucket connects to Orbit through OAuth: you authorise Kapsule once, Orbit lists the repositories your Bitbucket account can reach, and it registers a webhook per repository so every push triggers a build. This guide covers the connection, selecting a repository, creating the project, and what to check when a repository does not appear.

Before You Start

Orbit sees only what your Bitbucket account sees. For a workspace repository you need at least write access, and enough permission for a repository webhook to be created. If your workspace restricts third-party OAuth consumers, an administrator has to allow Kapsule Orbit before the connection will succeed.

Step 1: Connect Bitbucket

In KPanel, click Orbit in the left sidebar.
Click New project.
Leave the mode set to Import Git Repo.
On step 1, click Connect Bitbucket.

You are sent to Bitbucket to authorise the Kapsule Orbit OAuth consumer. Grant the requested permissions and Bitbucket returns you to KPanel with your repositories loaded. Step 1 then shows Just connected.

If the authorisation fails, KPanel shows the error Bitbucket returned. Read it rather than retrying blindly: a workspace policy block and a cancelled authorisation look similar but need different fixes.

Step 2: Select a Repository

Your accessible repositories appear as a list. Click Select next to the one you want to deploy. Private repositories carry a Private badge; Orbit deploys public and private repositories alike.

If a Repository Is Missing

Confirm your access level on the repository. Read access is not enough; you need write access for Orbit to register the webhook it needs.
Check that the repository is in a workspace you actually belong to, not one you only have a link to.
Click Reconnect Bitbucket on step 1 to re-run the OAuth flow and refresh the token and the repository list.

If the panel shows No repos accessible, the grant succeeded but returned nothing. Reconnect and confirm you approved the repository scopes.

Step 3: Configure Your Project

Field	What it does
Project Name	The display name in KPanel, for example `my-app`
Deploy URL	The subdomain under `kaps.run`, so `my-app` becomes `my-app.kaps.run`

Click Create project. Orbit clones the repository, queues the first build, and lands you on the project overview with the log streaming.

The Deploy URL slug is set once, at creation, and cannot be edited later. To serve under a different address, attach a custom domain. See Adding a Custom Domain to Your Project.

Automatic Deploys

Orbit registers a webhook on your Bitbucket repository at project creation. After that:

A push to your production branch queues a production deployment.
A push to any other branch builds an isolated preview at branch-<branch-name>.kaps.run, if Branch previews is enabled in Settings under Runtime. See Branch Preview Deployments in Orbit.
Deleting a branch pauses its preview environment, and the storage is reclaimed within about a day.

You never create or maintain the webhook yourself.

The CI required checks setting in Orbit gates deploys on GitHub Actions job names or a GitLab pipeline. It does not gate on Bitbucket Pipelines. If you need Bitbucket Pipelines to decide when a deploy happens, turn off push-triggered deploys for that branch and have your pipeline call a deploy hook on success instead. See Triggering Deployments Via Deploy Hooks.

Reconnecting or Disconnecting Bitbucket

Click Orbit, then New project.
On step 1, click Reconnect to re-run the OAuth flow, or Disconnect to remove the link.

Reconnecting is the right first step whenever repository listing breaks, because OAuth tokens expire and reconnecting mints a new one.

Disconnecting keeps your projects and their deployment history, and the live deployment keeps serving traffic. Push-triggered deploys stop. Deploy hooks stop too, because a hook reads the branch head through the provider connection to decide what to build.