Connecting a GitHub Repo

Before Orbit can deploy anything from GitHub you install the Kapsule Orbit GitHub App on your GitHub account or organisation and choose which repositories it can see. This guide walks through the install, selecting a repository, creating the project, and what to do when a repository you expect does not appear.

Before You Start

You need permission to install a GitHub App on the account or organisation that owns the repository. On a personal account that is automatic. On an organisation you either need to be an owner, or an owner needs to approve your install request from the organisation's settings.

Step 1: Install the Kapsule Orbit GitHub App

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

You are sent to GitHub to install the Kapsule Orbit app. GitHub asks where to install it (your personal account or an organisation) and then whether to grant All repositories or Only select repositories.

Choose Only select repositories and tick just the repositories you plan to deploy. You can add more later from GitHub without disconnecting or recreating anything in Orbit, and it keeps the blast radius of the integration small.

When you finish, GitHub sends you back to KPanel. Step 1 now shows Just connected, and your repositories load into step 2.

Step 2: Select a Repository

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

Once selected, the repository shows a Selected badge, and a Change link lets you pick a different one.

If a Repository Is Missing

Orbit can only list what the GitHub App can see. If a repository you expect is not there:

Click Reconnect GitHub on step 1 to re-run the install flow, or open github.com/settings/installations directly.
Open the Kapsule Orbit installation and add the missing repository under Repository access.
Return to KPanel. The list refreshes.

If the panel shows No repos accessible, the app is installed but has been granted no repositories at all. Open the GitHub App settings and grant access to at least one.

Other common causes:

The repository belongs to an organisation you have not installed the app on. Installing it on your personal account does not cover organisation repositories.
An organisation owner has not yet approved your install request. Until they do, the app exists but sees nothing.
The repository was transferred or renamed after you installed the app. Re-run the install flow to refresh what Orbit can see.

Step 3: Configure Your Project

With a repository selected, step 3 asks for two fields:

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 your first build, and drops you on the project overview where you can watch the log stream.

The Deploy URL slug is set once at creation and cannot be changed afterwards. If you want a different public address later, attach a custom domain rather than trying to rename the slug. See Adding a Custom Domain to Your Project.

What Orbit Sets Up Automatically

Creating the project wires up push-to-deploy for you. There is no webhook to configure by hand:

Pushes to your production branch queue a production deployment.
If Branch previews is enabled, pushes to any other branch build an isolated preview at branch-<branch-name>.kaps.run. See Branch Preview Deployments in Orbit.
Pull request activity is tracked, so a preview deployment shows the PR number it belongs to.
Closing or merging a pull request pauses its preview, and the storage is reclaimed within about a day.

Gating Deploys On GitHub Actions

If you run tests in GitHub Actions you can make Orbit wait for them. In Settings, then CI required checks, enter the exact Actions job names, comma-separated, for example build,test,lint. All named checks must pass before a push-triggered production deploy proceeds. A CI failure cancels the Orbit deploy automatically.

This applies to the production branch only.

Reconnecting or Changing Your Installation

To change which repositories Orbit can see:

Click Orbit, then New project.
On step 1, click Reconnect to re-run the GitHub App install flow.

Or manage the installation directly at github.com/settings/installations. Changes there are picked up the next time Orbit lists your repositories.

Disconnecting GitHub

On step 1 of New project, click Disconnect.

Disconnecting removes the link between your Kapsule account and GitHub. Your projects and their deployment history are kept, and the currently live deployment carries on serving traffic, but push-triggered deployments stop until you reconnect. Deploy hooks keep working, because they fetch the branch head through the provider connection: if the connection is gone, a hook call fails with an error rather than deploying stale code.