GitHub 저장소 연결하기

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…

Orbit이 GitHub에서 배포하기 전에 Kapsule Orbit GitHub 앱을 GitHub 계정이나 조직에 설치하고 어떤 저장소를 볼 수 있는지 선택해야 합니다. 이 가이드는 설치, 저장소 선택, 프로젝트 생성, 그리고 예상했던 저장소가 나타나지 않을 때 할 일을 안내합니다.

시작하기 전에

저장소를 소유한 계정이나 조직에 GitHub 앱을 설치할 권한이 필요합니다. 개인 계정에서는 자동입니다. 조직에서는 조직의 소유자이거나 소유자가 조직의 설정에서 설치 요청을 승인해야 합니다.

Step 1: Kapsule Orbit GitHub 앱 설치

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

GitHub로 이동하여 Kapsule Orbit 앱을 설치합니다. GitHub에서 설치 위치(개인 계정 또는 조직)를 묻고 All repositories 또는 Only select repositories를 부여할지 묻습니다.

Only select repositories를 선택하고 배포할 저장소만 선택합니다. GitHub에서 나중에 더 추가할 수 있으며 Orbit에서 연결을 해제하거나 다시 생성할 필요가 없고, 통합의 영향 범위를 작게 유지합니다.

완료하면 GitHub에서 KPanel로 다시 보냅니다. 1단계는 이제 Just connected를 표시하고, 저장소가 2단계에 로드됩니다.

Step 2: 저장소 선택

접근 가능한 저장소가 목록으로 나타납니다. 배포하려는 저장소에서 Select를 클릭합니다. 비공개 저장소는 Private 배지를 가지고 있으며, Orbit은 공개 및 비공개 저장소를 모두 배포합니다.

선택하면 저장소에 Selected 배지가 표시되고, Change 링크로 다른 저장소를 선택할 수 있습니다.

저장소가 누락된 경우

Orbit은 GitHub 앱이 볼 수 있는 것만 나열할 수 있습니다. 예상했던 저장소가 없는 경우:

1단계에서 Reconnect GitHub를 클릭하여 설치 흐름을 다시 실행하거나 github.com/settings/installations을 직접 엽니다.
Kapsule Orbit 설치를 열고 Repository access 아래에 누락된 저장소를 추가합니다.
KPanel로 돌아갑니다. 목록이 새로고침됩니다.

패널에 No repos accessible이 표시되면 앱은 설치되었지만 저장소가 없습니다. GitHub 앱 설정을 열고 최소한 하나의 저장소에 접근 권한을 부여합니다.

기타 일반적인 원인:

저장소가 앱을 설치하지 않은 조직에 속합니다. 개인 계정에 설치하면 조직 저장소는 포함되지 않습니다.
조직 소유자가 설치 요청을 아직 승인하지 않았습니다. 승인할 때까지 앱은 존재하지만 아무것도 보지 못합니다.
저장소가 앱을 설치한 후 이전되거나 이름이 바뀌었습니다. 설치 흐름을 다시 실행하여 Orbit이 볼 수 있는 것을 새로고침합니다.

Step 3: 프로젝트 구성

저장소가 선택되면 3단계에서 두 개의 필드를 요청합니다:

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

Create project를 클릭합니다. Orbit이 저장소를 복제하고, 첫 번째 빌드를 대기열에 넣고, 로그 스트림을 볼 수 있는 프로젝트 개요로 이동합니다.

배포 URL 슬러그는 생성 시 한 번 설정되며 이후에 변경할 수 없습니다. 나중에 다른 공개 주소를 원하면 슬러그 이름을 바꾸려고 하지 말고 커스텀 도메인을 연결합니다. 프로젝트에 커스텀 도메인 추가를 참조하세요.

Orbit이 자동으로 설정하는 것

프로젝트를 생성하면 푸시-투-배포가 설정됩니다. 수동으로 구성할 웹훅은 없습니다:

프로덕션 브랜치로 푸시하면 프로덕션 배포가 대기열에 들어갑니다.
Branch previews가 활성화되면 다른 브랜치로 푸시하면 branch-<branch-name>.kaps.run에서 격리된 미리보기가 빌드됩니다. Orbit의 브랜치 미리보기 배포를 참조하세요.
풀 요청 활동이 추적되므로 미리보기 배포는 속한 PR 번호를 표시합니다.
풀 요청을 닫거나 병합하면 미리보기가 일시 중지되고 스토리지는 약 하루 이내에 회수됩니다.

GitHub Actions에서 배포 게이팅

GitHub Actions에서 테스트를 실행하는 경우 Orbit이 이를 기다리도록 할 수 있습니다. Settings에서 CI required checks로 이동하여 정확한 Actions 작업 이름을 쉼표로 구분하여 입력합니다 (예: build,test,lint). 모든 명명된 검사가 통과해야 푸시 트리거 프로덕션 배포가 진행됩니다. CI 실패가 Orbit 배포를 자동으로 취소합니다.

이는 프로덕션 브랜치에만 적용됩니다.

설치 다시 연결 또는 변경

Orbit이 볼 수 있는 저장소를 변경하려면:

Orbit을 클릭한 다음 New project를 클릭합니다.
1단계에서 Reconnect를 클릭하여 GitHub 앱 설치 흐름을 다시 실행합니다.

또는 github.com/settings/installations에서 설치를 직접 관리합니다. 거기서의 변경 사항은 Orbit이 다음 번에 저장소를 나열할 때 적용됩니다.

GitHub 연결 해제

New project의 1단계에서 Disconnect를 클릭합니다.

연결 해제는 Kapsule 계정과 GitHub 간의 링크를 제거합니다. 프로젝트와 배포 기록은 유지되고 현재 라이브 배포는 트래픽을 계속 제공하지만 다시 연결할 때까지 푸시 트리거 배포가 중지됩니다. 배포 훅은 계속 작동합니다. 훅은 제공자 연결을 통해 브랜치 헤드를 가져오기 때문입니다: 연결이 없으면 훅 호출은 오래된 코드를 배포하는 대신 오류와 함께 실패합니다.