连接 GitLab 存储库

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…

GitLab 通过 OAuth 而非已安装的应用连接到 Orbit：您授权 Kapsule 一次，Orbit 列出您的 GitLab 账户可以访问的项目，并为每个存储库注册一个 webhook，这样每次推送都会触发构建。本指南涵盖连接、选择存储库、在 GitLab 管道上限制部署以及存储库未显示的常见原因。

开始前

Orbit 只能看到您自己的账户可以看到的 GitLab 项目。对于由群组拥有的项目，您至少需要开发者访问权限，并且需要足够的权限来在存储库上创建 webhook。如果您的 GitLab 实例限制出站 webhook，这个限制也适用于此处。

步骤 1：连接 GitLab

在 KPanel 中，单击左侧栏中的 Orbit。
单击新建项目。
将模式保持为导入 Git 存储库。
在步骤 1 上，单击连接 GitLab。

您将被发送到 GitLab 来授权 Kapsule Orbit 应用程序。批准所请求的范围，GitLab 会将您返回到 KPanel，并加载您的存储库。步骤 1 随后显示刚刚连接。

如果连接失败，KPanel 会显示 GitLab 返回的错误，而不是通用消息。在重试之前阅读它：范围拒绝和过期授权需要不同的修复。

步骤 2：选择存储库

您可访问的存储库显示为列表。单击所需存储库旁边的选择。私有存储库带有私有徽章；Orbit 部署公共和私有存储库。

如果存储库缺失

检查您在项目上的角色。报告者访问权限不足；您至少需要开发者权限。
如果项目属于某个群组，请确认您的成员资格在该群组或项目本身上，而不仅仅是在具有受限角色的祖先群组上。
单击步骤 1 上的重新连接 GitLab 以重新运行 OAuth 流程。这会刷新令牌并重新读取您的项目列表。

如果面板显示无可访问的存储库，OAuth 授权通过了但未返回任何内容。重新连接并检查您是否批准了存储库范围而不是缩减的范围。

步骤 3：配置您的项目

字段	用途
项目名称	KPanel 中的显示名称，例如 `my-app`
部署 URL	`kaps.run` 下的子域，因此 `my-app` 变为 `my-app.kaps.run`

单击创建项目。Orbit 克隆存储库，将第一个构建加入队列，并将您带到项目概览。

部署 URL 段在创建时是固定的，之后无法更改。要在不同地址下发布，请改为附加自定义域。请参阅向您的项目添加自定义域。

自动部署

创建项目时，Orbit 会在您的 GitLab 存储库上注册一个 webhook。之后：

推送到您的生产分支将队列一个生产部署。
推送到任何其他分支将在 branch-<branch-name>.kaps.run 构建一个隔离的预览，如果在设置下的运行时中启用了分支预览。请参阅 Orbit 中的分支预览部署。
删除分支会暂停其预览环境，存储空间将在大约一天内被回收。

您无需手动创建或维护 webhook。

等待您的 GitLab CI 管道

如果您在 GitLab CI 中运行测试，Orbit 可以在管道通过后才部署。

打开项目，然后打开设置。
找到 CI 必需的检查。
输入任何非空值并保存。

在 GitLab 上，该值本身不会与作业名称匹配：任何非空值都会告诉 Orbit 等待完整管道成功。管道失败会自动取消 Orbit 部署。这仅适用于生产分支上由推送触发的部署。

这是两个提供者不同之处。GitHub 根据命名的 Actions 作业匹配该值；GitLab 将任何值视为"等待整个管道"。如果您在 GitHub 和 GitLab 项目之间复制设置，请不要期望同一字段的行为相同。

重新连接或断开 GitLab

单击 Orbit，然后单击新建项目。
在步骤 1 上，单击重新连接以重新运行 OAuth 流程，或单击断开以移除链接。

只要存储库列表停止工作，重新连接是正确的首选步骤：OAuth 令牌会过期，重新连接会生成一个新令牌。

断开连接会保留您的项目及其部署历史，并且实时部署继续提供流量。停止的是由推送触发的部署。部署 hook 也停止工作，因为 hook 必须通过提供者连接读取分支头来了解要构建的内容。