Bitbucket 저장소 연결하기

Bitbucket connects to Orbit through OAuth: you authorise Kapsule once, Orbit lists the repositories your Bitbucket account can reach, and it registers a webhook per repository so every push triggers…

Bitbucket는 OAuth를 통해 Orbit에 연결됩니다. 한 번 Kapsule을 인증하면 Orbit이 Bitbucket 계정에서 접근할 수 있는 저장소를 나열하고, 저장소당 하나의 웹훅을 등록하여 모든 푸시(push)가 빌드를 트리거합니다. 이 가이드는 연결, 저장소 선택, 프로젝트 생성, 그리고 저장소가 나타나지 않을 때 확인할 사항을 다룹니다.

시작하기 전에

Orbit은 Bitbucket 계정이 볼 수 있는 것만 봅니다. 워크스페이스 저장소의 경우 최소한 쓰기 접근 권한이 필요하며, 저장소 웹훅을 생성할 수 있는 충분한 권한이 필요합니다. 워크스페이스에서 타사 OAuth 소비자를 제한하는 경우 관리자가 연결이 성공하기 전에 Kapsule Orbit을 허용해야 합니다.

단계 1: Bitbucket 연결

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

Bitbucket으로 이동하여 Kapsule Orbit OAuth 소비자를 인증합니다. 요청된 권한을 부여하면 Bitbucket이 저장소가 로드된 상태로 KPanel로 돌아옵니다. 단계 1에는 Just connected가 표시됩니다.

인증이 실패하면 KPanel에 Bitbucket이 반환한 오류가 표시됩니다. 무작정 다시 시도하기보다는 오류를 읽어보세요. 워크스페이스 정책 차단과 취소된 인증은 비슷해 보이지만 다른 해결책이 필요합니다.

단계 2: 저장소 선택

접근 가능한 저장소가 목록으로 나타납니다. 배포할 저장소 옆의 Select를 클릭합니다. 개인 저장소에는 Private 배지가 표시되며, Orbit은 공개 및 개인 저장소 모두 배포합니다.

저장소가 누락된 경우

저장소에 대한 접근 수준을 확인하세요. 읽기 접근만으로는 부족하며, Orbit이 필요한 웹훅을 등록하기 위해 쓰기 접근 권한이 필요합니다.
저장소가 실제로 속한 워크스페이스에 있는지 확인하세요. 링크만 있는 워크스페이스에 속한 것이 아닌지 확인합니다.
단계 1에서 Reconnect Bitbucket을 클릭하여 OAuth 플로우를 다시 실행하고 토큰 및 저장소 목록을 새로고침합니다.

패널에 No repos accessible이 표시되면 승인은 성공했지만 아무것도 반환되지 않았습니다. 다시 연결하고 저장소 범위를 승인했는지 확인합니다.

단계 3: 프로젝트 구성

필드	역할
Project Name	KPanel의 표시 이름, 예를 들어 `my-app`
Deploy URL	`kaps.run` 아래의 서브도메인, 따라서 `my-app`은 `my-app.kaps.run`이 됩니다

Create project를 클릭합니다. Orbit이 저장소를 복제하고 첫 번째 빌드를 대기열에 추가한 후 로그가 스트리밍되는 프로젝트 개요 페이지로 이동합니다.

Deploy URL 슬러그는 생성 시점에 설정되며 나중에 편집할 수 없습니다. 다른 주소에서 제공하려면 사용자 정의 도메인을 연결합니다. 프로젝트에 사용자 정의 도메인 추가를 참조합니다.

자동 배포

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

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

웹훅을 직접 생성하거나 유지할 필요가 없습니다.

Orbit의 CI required checks 설정은 GitHub Actions 작업 이름 또는 GitLab 파이프라인에서 배포를 제어합니다. Bitbucket Pipelines에서는 제어하지 않습니다. Bitbucket Pipelines이 배포 발생 시기를 결정해야 하는 경우 해당 브랜치의 푸시 트리거 배포를 끄고 성공 시 파이프라인이 대신 배포 훅을 호출하도록 합니다. 배포 훅을 통한 배포 트리거를 참조합니다.

Bitbucket 재연결 또는 연결 해제

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

OAuth 토큰이 만료되고 재연결이 새로운 토큰을 발급하기 때문에 저장소 나열이 끊길 때마다 재연결이 올바른 첫 번째 단계입니다.

연결을 해제하면 프로젝트와 배포 기록이 유지되고 라이브 배포가 계속 트래픽을 제공합니다. 푸시 트리거 배포가 중지됩니다. 훅이 무엇을 빌드할지 결정하기 위해 공급자 연결을 통해 브랜치 헤드를 읽기 때문에 배포 훅도 중지됩니다.