Connecting a GitLab Repo

GitLab connects to Orbit through OAuth rather than an installed app: you authorise Kapsule once, Orbit lists the projects your GitLab account can reach, and it registers a webhook per repository so every push triggers a build. This guide covers the connection, selecting a repository, gating deploys on your GitLab pipeline, and the usual reasons a repository does not show up.

Before You Start

Orbit can only see GitLab projects your own account can see. For a group-owned project you need at least Developer access, and you need enough permission for a webhook to be created on the repository. If your GitLab instance restricts outbound webhooks, that restriction applies here too.

Step 1: Connect GitLab

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

You are sent to GitLab to authorise the Kapsule Orbit application. Approve the requested scopes and GitLab returns you to KPanel with your repositories loaded. Step 1 then shows Just connected.

If the connection fails, KPanel shows the error GitLab returned rather than a generic message. Read it before retrying: a scope refusal and an expired authorisation need different fixes.

Step 2: Select a Repository

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

If a Repository Is Missing

Check your role on the project. Reporter access is not enough; you need at least Developer.
If the project belongs to a group, confirm your membership is on the group or the project itself, not just an ancestor group with a restricted role.
Click Reconnect GitLab on step 1 to re-run the OAuth flow. This refreshes the token and re-reads your project list.

If the panel shows No repos accessible, the OAuth grant went through but returned nothing. Reconnect and check that you approved the repository scopes rather than a reduced set.

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 takes you to the project overview.

The Deploy URL slug is fixed at creation and cannot be changed later. To publish under a different address, attach a custom domain instead. See Adding a Custom Domain to Your Project.

Automatic Deploys

Orbit registers a webhook on your GitLab repository when the project is created. 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 do not create or maintain the webhook by hand.

Waiting For Your GitLab CI Pipeline

If you run tests in GitLab CI, Orbit can hold the deploy until the pipeline passes.

Open the project, then Settings.
Find CI required checks.
Enter any non-empty value and save.

On GitLab, the value itself is not matched against job names: any non-empty value tells Orbit to wait for the full pipeline to succeed. A pipeline failure cancels the Orbit deployment automatically. This applies to push-triggered deploys on the production branch only.

This is where the two providers differ. GitHub matches the value against named Actions jobs; GitLab treats any value as "wait for the whole pipeline". If you are copying settings between a GitHub and a GitLab project, do not expect the same field to behave identically.

Reconnecting or Disconnecting GitLab

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

Reconnect is the right first move whenever repository listing stops working: OAuth tokens expire, and reconnecting mints a fresh one.

Disconnecting keeps your projects and their deployment history, and the live deployment carries on serving traffic. What stops is push-triggered deploying. Deploy hooks stop working too, because a hook has to read the branch head through the provider connection to know what to build.