프리뷰 배포는 각 풀 리퀘스트마다 해당 브랜치의 코드로 빌드된 고유한 라이브 URL을 제공하므로, 리뷰어가 diff를 읽고 추측하는 대신 실제 변경 사항을 직접 클릭해볼 수 있습니다. 각 프리뷰는 새 커밋을 푸시할 때마다 업데이트되며, 풀 리퀘스트가 닫히면 자동으로 정리됩니다.
프리뷰 배포는 어디에 있나요
웹사이트를 열고 사이트를 클릭한 다음, 사이트의 왼쪽 메뉴에서 Environment 그룹을 열고 미리보기를 선택합니다. 페이지 제목은 미리보기 배포입니다.
프리뷰는 스테이징과는 별개입니다. 스테이징은 여러분이 의도적으로 푸시하는, 오래 유지되는 사이트의 단일 사본입니다. 반면 프리뷰는 풀 리퀘스트마다 생성되었다가 작업 후 폐기되는 짧은 수명의 환경입니다. 많은 팀이 둘 다 사용합니다. 나머지 절반에 대해서는 스테이징 환경을 참고하세요.
먼저 Git 배포를 설정하세요
프리뷰는 독립된 기능이 아닙니다. 프로덕션 사이트의 배포 키와 빌드 명령을 재사용하므로, 프리뷰를 활성화하려면 먼저 작동하는 Git Deploy 설정이 필요합니다.
Git Deploy가 설정되어 있지 않으면 페이지에 먼저 Git 배포를 설정하세요라는 문구가 표시되고, 활성화 양식 대신 Git 배포로 이동 버튼이 제공됩니다. Git에서 사이트 배포하기를 먼저 진행한 다음 돌아오세요.
Git Deploy가 연결되어 있지만 빌드 명령이 없는 경우, Preview 페이지에 경고가 표시됩니다. 이 경우 프리뷰는 저장소가 이미 빌드되어 있다고 가정하고, 정적 파일이 루트에 있다고 처리합니다. 이는 단순한 HTML 사이트에는 맞지만, 컴파일이 필요한 모든 것에는 잘못된 가정이므로, 프로젝트에 빌드 명령이 필요하다면 Git Deploy 페이지에서 설정해 주세요.
프리뷰 활성화하기
- 미리보기 배포 활성화 카드에서
owner/repo형식으로 저장소를 입력합니다. URL도 SSH 주소도 아닌, 단 두 개의 구간, 예를 들어acme/marketing-site만 입력합니다. - Enable을 클릭합니다.
owner/name과 일치하지 않는 입력값은 저장소는 owner/name 형식이어야 합니다라는 메시지와 함께 거부됩니다.
활성화 직후, KPanel은 웹훅 시크릿을 지금 복사하세요라는 제목의 카드에 웹훅 서명 시크릿을 표시하며, 다시는 볼 수 없다는 경고를 함께 보여줍니다.
페이지를 떠나기 전에 시크릿을 복사하세요. 이 값은 한 번만 생성되며 이후에는 다시 확인할 수 없습니다. 분실한 경우 해결 방법은 재생성뿐이며, 이는 기존 값을 무효화하므로 어차피 저장소 웹훅도 업데이트해야 합니다.
저장소에 웹훅 추가하기
설정이 완료된 카드에는 저장소 설정의 Webhooks 항목에 붙여넣을 웹훅 URL이 표시됩니다. 다음과 같이 구성하세요:
- 페이로드 URL: 페이지에 표시된 웹훅 URL.
- 시크릿: 방금 복사한 값.
- 콘텐츠 유형: JSON.
- 이벤트: 풀 리퀘스트 이벤트와 푸시 이벤트를 함께 선택해, 열려 있는 풀 리퀘스트에 새 커밋이 추가될 때 프리뷰가 다시 빌드되도록 합니다.
이 설정이 완료되면, 풀 리퀘스트를 열었을 때 몇 분 안에 프리뷰가 빌드됩니다. 백그라운드 작업이 매 분마다 새로운 프리뷰 작업이 있는지 확인하므로, KPanel에서 별도로 아무것도 누를 필요가 없습니다.
프리뷰 URL
각 프리뷰는 pr-<pull-request-number>-<site-id>.kapsulecloud.app 형식의 고유한 호스트명을 가지며, 와일드카드 인증서로 보호되므로 별도의 인증서 설정 없이도 HTTPS로 제공됩니다.
프리뷰를 여는 가장 안정적인 방법은 최근 프리뷰의 해당 프리뷰 행에 있는 Open 버튼을 이용하는 것으로, 이 버튼에는 해당 빌드에 할당된 정확한 URL이 연결되어 있습니다. 이 링크를 풀 리퀘스트에 붙여넣으면 리뷰어가 KPanel을 찾아갈 필요가 전혀 없습니다.
최근 프리뷰 목록 읽기
최근 프리뷰 섹션에는 최신순으로 가장 최근의 프리뷰 목록이 표시됩니다. 각 행에는 풀 리퀘스트 번호와 제목, 브랜치, 커밋, 그리고 상태가 표시됩니다:
| 상태 | 의미 |
|---|---|
| BUILDING | 현재 복제 및 빌드 중 |
| LIVE | 프리뷰 URL에서 서비스 중 |
| FAILED | 빌드 오류 발생, 로그를 펼쳐서 원인 확인 |
| DESTROYED | 정리됨, 보통 풀 리퀘스트가 닫혔기 때문 |
행에서 빌드 로그 전환을 클릭하면 해당 빌드 출력이 인라인으로 펼쳐집니다. 이 로그는 프리뷰가 실패했을 때 가장 먼저 확인해야 할 곳이며, 로컬에서 빌드할 때 나오는 출력과 동일합니다.
목록이 비어 있으면 페이지에 그렇게 표시됩니다. 저장소에서 풀 리퀘스트를 열면 몇 분 안에 프리뷰가 빌드될 것입니다.
웹훅 시크릿 교체하기
설정이 완료된 카드에서 시크릿 재생성을 클릭합니다. KPanel은 확인을 요청하며, 현재 시크릿이 즉시 작동을 멈추고 이후 저장소의 웹훅 설정을 업데이트해야 한다는 점을 명확히 안내합니다.
새 시크릿은 이전과 동일한 일회성 카드에 한 번만 표시됩니다. 이를 복사한 후, 저장소의 웹훅을 업데이트하세요. 이 두 시점 사이에는 들어오는 웹훅 전송이 거부되므로, 두 단계를 연이어 처리하세요.
저장소 관리자 권한을 가진 사람이 조직을 떠났거나, 시크릿이 공유 채팅 채널이나 티켓처럼 노출되면 안 될 곳에 붙여넣어진 적이 있다면 시크릿을 재생성하세요.
프리뷰 끄기
Disable을 클릭합니다. 설정이 비활성화되고 저장된 시크릿이 삭제됩니다. 기존 프리뷰는 더 이상 다시 빌드되지 않습니다.
저장소에서도 웹훅을 삭제해 정리하세요. 삭제하지 않으면 오류를 반환하기 시작할 뿐 해로운 일은 없지만, 영원히 오류를 반환하는 웹훅은 저장소의 전송 로그에 불필요한 잡음이 됩니다.
비용과 관리
프리뷰는 실제 코드를 빌드하고 서비스하므로, 사이트의 다른 배포와 동일한 리소스를 사용합니다. 다음 두 가지 습관으로 이를 관리할 수 있습니다:
- 더 이상 작업하지 않는 풀 리퀘스트는 닫으세요. 닫힌 풀 리퀘스트의 프리뷰는 자동으로 정리됩니다.
- 프리뷰가 프로덕션 자격 증명을 사용하지 않도록 하세요. Secrets 탭의 preview 환경을 통해 테스트용 키를 제공하세요. 이 환경은 정확히 프리뷰와 프로덕션 설정이 혼동되지 않도록 하기 위해 존재합니다.
프리뷰 URL은 비공개가 아닙니다. 유효한 인증서를 갖춘 실제의, 공개적으로 접근 가능한 호스트명이며, 링크를 가진 누구나 열어볼 수 있습니다. 실제 고객 데이터가 포함된 내용을 검토하는 데 프리뷰를 사용하지 말고, 프로덕션 데이터베이스 덤프로 프리뷰 환경을 채우지도 마세요.
문제 해결
풀 리퀘스트를 열어도 아무것도 빌드되지 않습니다. 저장소에서 웹훅의 최근 전송 내역을 확인하세요. 401 또는 403은 시크릿이 일치하지 않는다는 의미이므로 재생성한 다음 양쪽 모두 업데이트하세요. 전송 내역이 전혀 없다면 웹훅이 풀 리퀘스트 이벤트를 구독하고 있지 않은 것입니다.
프리뷰는 빌드되지만 디렉터리 목록이나 404가 표시됩니다. Git Deploy 페이지의 출력 디렉터리가 실제 빌드 결과물이 작성되는 위치와 일치하지 않는 것입니다. 프리뷰는 이 설정을 프로덕션에서 그대로 물려받습니다.
프리뷰에서만 빌드가 실패합니다. 가장 흔한 원인은 프로덕션에는 존재하지만 프리뷰 환경에는 추가되지 않은 의존성이나 환경 변수입니다. Secrets 페이지의 preview 탭을 확인하세요.
프리뷰 URL이 작동을 멈췄습니다. 해당 행의 상태를 확인하세요. DESTROYED는 풀 리퀘스트가 닫혀 환경이 회수되었음을 의미하며, 이는 의도된 동작입니다.
다음으로 볼 내용
- Git에서 사이트 배포하기, 사전 필요 설정입니다.
- 사이트의 앱 시크릿 저장하기, 환경별 자격 증명에 대한 내용입니다.
- 스테이징 환경, 지속적인 사전 프로덕션 사본에 대한 내용입니다.