Orbit에서 브랜치 미리보기 배포

Branch previews build every non-production, non-staging branch you push to its own isolated URL, so you can click through a change in a real environment before it merges. This guide covers turning…

브랜치 미리보기 활성화

Orbit에서 프로젝트를 엽니다.
Settings 탭을 엽니다.
Runtime 섹션을 찾아서 Branch previews를 활성화합니다.

활성화되면 프로덕션 브랜치도 아니고 스테이징 브랜치도 아닌 모든 브랜치에 푸시할 때마다 빌드가 트리거되고 자체 미리보기 환경에 배포됩니다.

Orbit 프로젝트 설정의 Branch previews 토글

브랜치 미리보기는 프로젝트별 토글이며 유료 추가 기능이 아닙니다. 무료 Launch 플랜을 포함한 모든 Orbit 플랜에서 사용할 수 있습니다. 플랜별로 다른 점은 단일 프로젝트가 한 번에 가질 수 있는 환경의 수입니다. Launch는 2개(프로덕션 + 미리보기 1개), Liftoff는 4개, Apex는 11개입니다. 프로젝트가 환경 한계에 도달하면 하나를 삭제할 때까지 추가 브랜치는 자체 미리보기를 받지 않습니다.

미리보기 URL

미리보기는 브랜치 이름에서 파생된 호스트명을 받습니다. 이름은 소문자로 변환되고, 문자, 숫자 또는 하이픈이 아닌 모든 문자는 하이픈이 되고, 하이픈의 연속은 축약되며, 결과는 48자로 잘리고 branch- 접두사가 붙습니다.

브랜치	미리보기 호스트명
`redesign`	`branch-redesign.kaps.run`
`feat/new-checkout`	`branch-feat-new-checkout.kaps.run`
`JB/Fix_Cart`	`branch-jb-fix-cart.kaps.run`

미리보기 URL은 링크를 가진 모든 사람이 공개적으로 접근할 수 있습니다. 색인 작성 또는 광고되지는 않지만 접근 제어도 없습니다. 팀을 벗어나면 안 되는 것을 검토하는 데 미리보기를 사용하지 마세요. 프로덕션 데이터를 미리보기로 지정하지 마세요. 보호된 사전 프로덕션 환경이 필요하면 staging 환경을 대신 사용하세요. 스테이징은 Settings의 Staging: access protection 및 Staging: IP allowlist 섹션에서 비밀번호와 IP 허용 목록을 지원합니다.

미리보기가 표시되는 위치

프로젝트 Overview 탭에는 모든 활성 미리보기를 나열하는 Preview deployments 섹션이 있습니다. 각 행은 다음을 표시합니다.

브랜치 이름 및 브랜치에 열린 풀 요청이 있을 때 이를 연결하는 PR #number 배지
현재 상태(QUEUED, BUILDING 또는 라이브)
배포된 지 얼마나 되었는지
미리보기 URL을 여는 링크
배포 상세 페이지를 열기 위한 View logs
삭제 버튼

각 미리보기는 자체 URL, 자체 빌드 및 자체 환경 변수가 있는 완전히 격리된 환경입니다. 이것이 수행하는 어떤 작업도 프로덕션에 영향을 줄 수 없습니다.

프로젝트 Branches 탭은 동일한 정보를 브랜치별로 구성하여 한 번에 여러 개가 열려 있을 때 더 쉽게 스캔할 수 있습니다.

미리보기의 환경 변수

이것이 올바르게 해야 할 부분입니다. **All environments (project-wide)**로 범위가 지정된 변수는 미리보기 빌드에 주입되고, 미리보기 URL은 공개입니다.

프로덕션 자격증명은 프로덕션 환경으로만 범위를 지정합니다.
미리보기에 제3자 서비스를 위한 테스트 모드 또는 샌드박스 자격증명을 제공합니다.
프로덕션 데이터베이스 URL이나 라이브 결제 키를 프로젝트 범위에 남기지 마세요.

추가 프로덕션 전용 변수를 추가하는 방법 및 스테이징 상속이 작동하는 방식을 포함한 전체 메커니즘은 환경별 환경 변수 설정에 있습니다.

미리보기의 빌드 로그

미리보기 옆의 View logs를 클릭하여 배포 상세 페이지를 엽니다. 미리보기는 프로덕션 배포와 동일한 대우를 받습니다. 전체 스트리밍 빌드 로그, 빌드 단계, 커밋 및 작성자, 아티팩트 크기, 캐시 히트 또는 콜드 빌드, 감지된 프레임워크 및 패키지 관리자, 그리고 빌드가 실패할 때 AI 진단 버튼입니다.

미리보기 삭제

미리보기 행의 삭제 버튼을 클릭하고 확인합니다.

미리보기를 삭제하면 환경 및 전체 빌드 기록이 제거되고 현재 배포만 제거되지 않습니다. 실행 취소할 수 없습니다. 브랜치 자체는 건드려지지 않으므로 다시 푸시하면 처음부터 새로운 미리보기가 생성되고 기록이 없으며 콜드 빌드 캐시입니다.

자동 정리

정리 후 정리할 필요가 없습니다.

풀 요청이 닫히거나 병합되면 해당 미리보기 환경이 즉시 일시 중지되고 서빙을 중지합니다. 방문자는 오래된 빌드 대신 404를 받습니다.
브랜치를 삭제하면 해당 브랜치의 미리보기도 같은 방식으로 일시 중지됩니다.
일시 중지된 미리보기는 약 하루 후에 가비지 수집됩니다. 소스 타르볼, 빌드 아티팩트 및 빌드 캐시가 삭제되고 환경이 보관됩니다.

일정에 따라 미리보기를 만료하도록 설정할 수도 있습니다. Settings에서 Preview expiry를 찾아 Never, 7, 14, 30 또는 60일을 선택합니다. 그보다 오래된 미리보기는 자동으로 일시 중지되고 24시간 내에 정리됩니다.

바쁜 저장소에서 Preview expiry를 14 또는 30일로 설정합니다. 모든 활성 미리보기는 프로젝트의 환경 한계에 대해 계산되며, 만료된 것들은 새 브랜치가 조용히 미리보기를 받지 못하는 일반적인 이유입니다.

승인 및 미리보기

Deploy protection에서 Require approval for production이 활성화되면 프로덕션에만 적용됩니다. 미리보기 빌드는 승인을 위해 보류되지 않습니다.

미리보기를 삭제하지 않고 특정 미리보기가 추가 변경사항을 배포하는 것을 중지하려면 Environments 탭에서 환경을 일시 중지합니다. 일시 중지된 환경에 대한 새 배포는 재개할 때까지 건너뜁니다.

문제 해결

브랜치를 푸시했지만 미리보기가 표시되지 않았습니다. 순서대로 확인하세요. Settings에서 Runtime으로 이동한 후 Branch previews가 켜져 있습니까? 브랜치가 실제로 스테이징 브랜치입니까(스테이징은 미리보기가 아닌 스테이징에 배포됨)? 브랜치가 Branch ignore patterns 중 하나와 일치합니까(예: dependabot/*)? 프로젝트가 이미 플랜의 환경 한계에 도달했습니까?

미리보기가 빌드되었지만 404를 표시합니다. 빌드는 성공했지만 이 브랜치의 출력 디렉토리가 잘못되었을 수 있습니다. Settings에서 Output directory를 확인하고, 브랜치가 설정을 변경하지 않고도 빌드 출력을 변경할 수 있음을 기억하세요. 빌드 명령 및 출력 디렉토리 구성을 참조하세요.

미리보기가 이전 커밋을 표시합니다. 같은 브랜치에 대한 빌드가 아직 실행 중인 동안 새 커밋을 푸시하면 진행 중인 빌드가 취소되고 새 빌드가 시작됩니다. 취소된 배포 다음에 실행 중인 배포가 표시되면 예상된 것입니다. 두 번째 빌드가 완료될 때까지 기다립니다.

닫힌 PR의 미리보기가 여전히 접근 가능합니다. 일시 중지는 웹훅 이벤트에서 발생합니다. 풀 요청을 닫을 때 공급자 연결이 끊겨 있으면 이벤트가 도착하지 않습니다. Overview 탭에서 미리보기를 수동으로 삭제합니다.