웹사이트
Preview Deploys For Pull Requests에 대한 미리보기 배포
Preview deploys give every pull request its own live URL, built from that branch's code, so reviewers can click through the actual change instead of reading a diff and guessing. Each preview updates…
프리뷰 배포는 모든 풀 리퀘스트에 자신의 라이브 URL을 제공하며, 해당 브랜치의 코드로 빌드되므로 리뷰어가 diff를 읽고 추측하는 대신 실제 변경 사항을 클릭할 수 있습니다. 각 프리뷰는 새 커밋을 푸시할 때 업데이트되며 풀 리퀘스트가 닫힐 때 자동으로 정리됩니다.
프리뷰 배포 위치
Websites를 열고 사이트를 클릭한 다음 사이트 탭 스트립에서 Environments 메뉴를 열고 Preview를 선택합니다. 페이지의 제목은 Preview deploys입니다.
프리뷰는 스테이징과 별개입니다. 스테이징은 의도적으로 푸시하는 사이트의 한 개의 장기 복사본이고, 프리뷰는 풀 리퀘스트당 생성되는 단기 환경으로 나중에 폐기됩니다. 많은 팀이 둘 다 사용합니다. 다른 절반은 Staging Environments를 참조하세요.
먼저 Git 배포 설정
프리뷰는 독립형 기능이 아닙니다. 프리뷰는 프로덕션 사이트의 배포 키와 빌드 명령을 재사용하므로 프리뷰를 활성화하기 전에 사이트에서 작동하는 Git 배포 구성이 필요합니다.
Git 배포가 구성되지 않은 경우 페이지에 Set up Git deploy first가 표시되고 활성화 양식 대신 Go to Git deploy 버튼이 제공됩니다. Deploying a Site From Git를 진행한 다음 돌아오세요.
Git 배포가 연결되었지만 빌드 명령이 없는 경우 프리뷰 페이지에 경고가 표시됩니다. 프리뷰는 저장소가 이미 빌드되었고 루트에 정적 파일이 있다고 가정합니다. 이는 순수 HTML 사이트에는 올바르지만 컴파일되는 모든 것에는 잘못되었으므로, 프로젝트에 필요한 경우 Git 배포 페이지에서 빌드 명령을 설정하세요.
프리뷰 활성화
- Enable preview deploys 카드에서
owner/repo형식으로 저장소를 입력합니다. URL이 아니고 SSH 주소도 아닙니다. 두 개의 세그먼트만 입력하세요. 예를 들어acme/marketing-site입니다. - Enable을 클릭합니다.
owner/name과 일치하지 않는 모든 것은 Repo must be in owner/name format 오류로 거부됩니다.
활성화 직후, KPanel은 Copy your webhook secret now라는 제목의 카드에 웹훅 서명 시크릿을 표시하며 다시 볼 수 없다는 경고가 표시됩니다.
페이지를 떠나기 전에 시크릿을 복사하세요. 이것은 한 번만 생성되며 나중에 검색할 수 없습니다. 시크릿을 잃어버린 경우 해결 방법은 다시 생성하는 것이며, 이는 기존 시크릿을 무효화하고 저장소 웹훅을 어차피 업데이트해야 함을 의미합니다.
저장소에 웹훅 추가
구성된 카드는 저장소 설정의 Webhooks 아래에 붙여넣을 Webhook URL을 표시합니다. 다음으로 구성하세요:
- Payload URL: 페이지에 표시된 웹훅 URL입니다.
- Secret: 방금 복사한 값입니다.
- Content type: JSON입니다.
- Events: 풀 리퀘스트 이벤트와 푸시이므로 열린 풀 리퀘스트의 새 커밋이 프리뷰를 다시 빌드합니다.
이것이 설정되면 풀 리퀘스트를 열면 몇 분 이내에 프리뷰가 빌드됩니다. 백그라운드 작업이 매분마다 새 프리뷰 작업을 확인하므로 KPanel에서 아무것도 누를 필요가 없습니다.
프리뷰 URL
각 프리뷰는 pr-<pull-request-number>-<site-id>.kapsulecloud.app 형식의 자체 호스트명을 가지며, 와일드카드 인증서로 보호되므로 자신의 인증서 단계 없이 HTTPS를 통해 제공됩니다.
하나를 열 수 있는 안정적인 방법은 Recent previews에서 프리뷰의 행에 있는 Open 버튼이며, 이는 해당 빌드를 위해 프로비저닝된 정확한 URL을 포함합니다. 리뷰어가 KPanel을 찾을 필요가 없도록 해당 링크를 풀 리퀘스트에 붙여넣으세요.
최근 프리뷰 목록 읽기
Recent previews 섹션은 가장 최근 프리뷰를 최신순으로 나열합니다. 각 행은 풀 리퀘스트 번호와 제목, 브랜치, 커밋 및 상태를 표시합니다:
| 상태 | 의미 |
|---|---|
| BUILDING | 지금 복제 및 빌드 중 |
| LIVE | 프리뷰 URL에서 제공 중 |
| FAILED | 빌드 오류 발생, 로그를 확장하여 이유 확인 |
| DESTROYED | 정리됨, 보통 풀 리퀘스트가 닫혔기 때문 |
행의 Toggle build log를 클릭하여 빌드 출력을 인라인으로 확장합니다. 이 로그는 프리뷰가 실패할 때 확인할 첫 번째 장소이며, 빌드가 로컬에서 생성할 출력과 동일합니다.
목록이 비어 있으면 페이지에 그렇게 표시됩니다. 저장소에서 풀 리퀘스트를 열면 프리뷰가 몇 분 내에 빌드됩니다.
웹훅 시크릿 회전
구성된 카드에서 Regenerate secret을 클릭합니다. KPanel이 확인을 요청하며, 현재 시크릿이 즉시 작동을 중지하고 저장소의 웹훅 설정에서 업데이트해야 한다는 점이 명시됩니다.
새 시크릿은 이전과 동일한 일회용 카드에 한 번 표시됩니다. 복사한 다음 저장소의 웹훅을 업데이트합니다. 이 두 순간 사이에 들어오는 웹훅 전달은 거부되므로 두 단계를 연속으로 수행하세요.
저장소 관리 액세스 권한이 있는 누군가가 떠날 때 또는 시크릿이 공유 채팅 채널이나 티켓처럼 있으면 안 되는 곳에 붙여넣은 적이 있을 때 시크릿을 다시 생성하세요.
프리뷰 끄기
Disable을 클릭합니다. 구성이 꺼지고 저장된 시크릿이 지워집니다. 기존 프리뷰는 더 이상 다시 빌드되지 않습니다.
저장소에서 웹훅도 삭제하여 정리하세요. 해로운 작업을 하지 않고 시작하는 대신 오류를 반환하지만, 영원히 오류를 반환하는 웹훅은 저장소의 전달 로그에서 불필요합니다.
비용 및 하우스키핑
프리뷰는 실제 코드를 빌드하고 제공하므로 사이트의 다른 배포와 동일한 리소스를 사용합니다. 두 가지 습관은 이를 제어하는 상태로 유지합니다:
- 더 이상 작업 중이 아닌 풀 리퀘스트를 닫으세요. 닫힌 풀 리퀘스트는 프리뷰가 자동으로 정리됩니다.
- 프리뷰를 프로덕션 자격 증명으로 지정하지 마세요. Secrets 탭의 preview 환경을 통해 테스트 키를 제공하세요. 이는 프리뷰와 프로덕션 구성이 혼동될 수 없도록 정확히 존재합니다.
프리뷰 URL은 비공개가 아닙니다. 이는 실제, 공개적으로 도달 가능한 호스트명이며 유효한 인증서를 가지고 있으며 링크를 가진 누구나 열 수 있습니다. 실제 고객 데이터를 포함하는 모든 것을 검토하기 위해 프리뷰를 사용하지 마세요. 프로덕션 데이터베이스 덤프에서 프리뷰 환경에 시드를 주지 마세요.
문제 해결
풀 리퀘스트를 열 때 아무것도 빌드되지 않습니다. 저장소에서 웹훅의 최근 전달을 확인하세요. 401 또는 403은 시크릿이 일치하지 않음을 의미하므로 다시 생성하고 양쪽을 업데이트하세요. 전달이 없으면 웹훅이 풀 리퀘스트 이벤트를 구독하지 않습니다.
프리뷰는 빌드되지만 디렉토리 목록이나 404를 표시합니다. Git 배포 페이지의 출력 디렉토리가 빌드가 실제로 쓰는 위치와 일치하지 않습니다. 프리뷰는 프로덕션에서 해당 설정을 상속합니다.
빌드가 프리뷰에서만 실패합니다. 가장 일반적인 원인은 프로덕션에는 존재하지만 프리뷰 환경에 추가된 적이 없는 종속성 또는 환경 변수입니다. Secrets 페이지의 preview 탭을 확인하세요.
프리뷰 URL이 작동을 중지합니다. 해당 행의 상태를 살펴보세요. DESTROYED는 풀 리퀘스트가 닫혔고 환경이 회수되었다는 의미이며, 이는 의도된 동작입니다.
다음 단계
- Deploying a Site From Git, 필수 구성입니다.
- Storing App Secrets For a Site 환경별 자격 증명 관련.
- Staging Environments 영구적인 사전 프로덕션 복사본 관련.