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 계정이 액세스할 수 있는 프로젝트를 나열하고, 저장소당 웹훅을 등록하므로 모든 푸시가 빌드를 트리거합니다. 이 가이드에서는 연결, 저장소 선택, GitLab 파이프라인에서 배포 제어, 저장소가 표시되지 않는 일반적인 이유를 다룹니다.

시작하기 전에

Orbit은 자신의 계정이 볼 수 있는 GitLab 프로젝트만 볼 수 있습니다. 그룹이 소유한 프로젝트의 경우 최소한 Developer 액세스 권한이 필요하며, 저장소에서 웹훅을 생성할 수 있는 충분한 권한이 필요합니다. GitLab 인스턴스가 아웃바운드 웹훅을 제한하는 경우 해당 제한이 여기에도 적용됩니다.

단계 1: GitLab 연결

KPanel에서 왼쪽 사이드바의 Orbit을 클릭합니다.
New project를 클릭합니다.
모드를 Import Git Repo로 설정된 상태로 둡니다.
단계 1에서 Connect GitLab을 클릭합니다.

GitLab으로 이동하여 Kapsule Orbit 애플리케이션을 인증합니다. 요청된 범위를 승인하면 GitLab이 저장소가 로드된 상태로 KPanel로 돌아갑니다. 단계 1에는 Just connected가 표시됩니다.

연결이 실패하면 KPanel은 일반적인 메시지가 아닌 GitLab이 반환한 오류를 표시합니다. 다시 시도하기 전에 읽어보세요. 범위 거부와 만료된 인증에는 다른 수정이 필요합니다.

단계 2: 저장소 선택

액세스 가능한 저장소가 목록으로 표시됩니다. 원하는 항목 옆의 Select를 클릭합니다. 개인 저장소에는 Private 배지가 표시됩니다. Orbit은 공개 및 개인 저장소를 모두 배포합니다.

저장소가 누락된 경우

프로젝트에서의 역할을 확인합니다. Reporter 액세스로는 충분하지 않으며 최소한 Developer 권한이 필요합니다.
프로젝트가 그룹에 속한 경우 멤버십이 그룹이나 프로젝트 자체에 있으며 제한된 역할을 가진 상위 그룹에만 있지 않은지 확인합니다.
단계 1에서 Reconnect GitLab을 클릭하여 OAuth 흐름을 다시 실행합니다. 이렇게 하면 토큰이 새로 고쳐지고 프로젝트 목록이 다시 읽힙니다.

패널에 No repos accessible이 표시되면 OAuth 부여가 진행되었지만 아무것도 반환되지 않았습니다. 다시 연결하고 축소된 범위 집합이 아닌 저장소 범위를 승인했는지 확인합니다.

단계 3: 프로젝트 구성

필드	기능
Project Name	KPanel의 표시 이름 (예: `my-app`)
Deploy URL	`kaps.run` 아래의 서브도메인 (예: `my-app`은 `my-app.kaps.run`이 됨)

Create project를 클릭합니다. Orbit은 저장소를 복제하고 첫 번째 빌드를 큐에 넣은 다음 프로젝트 개요로 이동합니다.

Deploy URL 슬러그는 생성 시 고정되며 나중에 변경할 수 없습니다. 다른 주소에 게시하려면 대신 커스텀 도메인을 연결합니다. 프로젝트에 커스텀 도메인 추가를 참조합니다.

자동 배포

Orbit은 프로젝트가 생성될 때 GitLab 저장소에 웹훅을 등록합니다. 그 후:

프로덕션 브랜치에 푸시하면 프로덕션 배포를 큐에 넣습니다.
다른 브랜치에 푸시하면 Settings의 Runtime 아래에서 Branch previews가 활성화된 경우 branch-<branch-name>.kaps.run에서 격리된 미리보기를 빌드합니다. Orbit의 Branch Preview 배포를 참조합니다.
브랜치를 삭제하면 해당 미리보기 환경이 일시 중지되고 약 하루 내에 저장소가 회수됩니다.

웹훅을 수동으로 만들거나 유지보수할 필요가 없습니다.

GitLab CI 파이프라인 대기

GitLab CI에서 테스트를 실행하는 경우 Orbit은 파이프라인이 통과될 때까지 배포를 보류할 수 있습니다.

프로젝트를 열고 Settings을 클릭합니다.
CI required checks를 찾습니다.
0이 아닌 값을 입력하고 저장합니다.

GitLab에서 값 자체는 작업 이름과 비교되지 않습니다. 0이 아닌 값은 Orbit에 전체 파이프라인이 성공할 때까지 기다리라고 알립니다. 파이프라인 실패 시 Orbit 배포가 자동으로 취소됩니다. 이는 프로덕션 브랜치에서만 푸시로 트리거된 배포에 적용됩니다.

이것이 두 공급자가 다른 점입니다. GitHub는 명명된 Actions 작업에 대해 값을 비교하고, GitLab은 모든 값을 "전체 파이프라인 대기"로 처리합니다. GitHub와 GitLab 프로젝트 간에 설정을 복사하는 경우 동일한 필드가 동일하게 작동할 것으로 예상하지 마세요.

GitLab 다시 연결 또는 연결 해제

Orbit을 클릭한 다음 New project를 클릭합니다.
단계 1에서 Reconnect를 클릭하여 OAuth 흐름을 다시 실행하거나 Disconnect를 클릭하여 링크를 제거합니다.

저장소 목록이 작동 중지될 때마다 Reconnect가 올바른 첫 번째 조치입니다. OAuth 토큰은 만료되며, 다시 연결하면 새 토큰이 발급됩니다.

연결 해제하면 프로젝트와 배포 기록이 유지되며 라이브 배포가 트래픽 제공을 계속합니다. 중지되는 것은 푸시로 트리거된 배포입니다. 배포 훅도 작동 중지됩니다. 훅이 구성할 브랜치 헤드를 공급자 연결을 통해 읽어야 하기 때문입니다.