Git 배포는 저장소를 사이트에 연결하여 선택한 브랜치에 푸시가 발생할 때마다 코드를 클론하고, 빌드를 실행하고, 결과를 게시하도록 해 줍니다. 이 가이드는 최초 연결, 설정을 마무리하는 저장소 측 두 단계, 배포 히스토리 확인, 그리고 Node.js 앱의 빌드 방식을 결정하는 빌드팩 감지를 다룹니다.
Git 배포 기능의 위치
웹사이트를 열고, 사이트를 클릭한 다음, 사이트 왼쪽 메뉴의 Environment 그룹을 열어 Git 배포를 선택하세요. 관련된 두 페이지가 근처에 있습니다:
- 배포: 같은 Environment 그룹에 있는 이 사이트의 전체 배포 히스토리입니다.
- Buildpack: Node.js 사이트에서 앱 그룹에 있는, 감지된 빌드 전략입니다.
Git Deploy 페이지는 자신의 역할을 명료하게 설명합니다. 저장소를 연결하면 설정한 브랜치로의 모든 푸시가 빌드와 배포를 트리거합니다.
저장소 연결하기
- Provider를 선택하세요: GitHub, GitLab 또는 Bitbucket.
- 저장소 URL을 입력하세요. SSH 형식을 사용하는 것이 좋습니다. 예:
git@github.com:user/repo.git. - 배포할 Branch를 설정하세요. 이 필드는
main에서 시작합니다. - 필요하다면 빌드 명령를 설정하세요. 예:
npm run build. - 필요하다면 출력 디렉토리를 설정하세요. 예:
dist,public, 또는 이미 빌드된 저장소라면.. - 저장소 연결를 클릭하세요.
저장소가 현재 상태 그대로 이미 배포 가능하다면(일반 PHP 사이트나 정적 사이트에서 흔한 경우입니다), 빌드 명령과 출력 디렉토리는 비워 두세요.
고급 스크립트
고급를 펼치면 두 개의 추가 필드가 나타납니다:
- 배포 전 스크립트: 빌드 전에 실행됩니다.
- 배포 후 스크립트: 배포 후에 실행됩니다.
새 코드가 적용된 후 반드시 일어나야 하는 작업, 즉 애플리케이션 캐시 지우기, 데이터베이스 마이그레이션 실행, 워커 재시작 등에는 배포 후 훅을 사용하세요.
푸시 시 자동 배포
카드 하단의 토글은 푸시가 배포를 트리거할지 여부를 제어합니다. 켜져 있으면 설정된 브랜치로의 모든 푸시가 배포를 트리거합니다. 꺼져 있으면 지금 배포로 수동으로 트리거할 때만 배포가 실행됩니다.
저장소 연결을 끊는 대신, 코드 프리즈나 장애 상황에서는 자동 배포를 꺼 두세요. 연결을 끊으면 배포 키와 webhook 시크릿이 폐기되므로, 이후 저장소 측 두 단계를 다시 수행해야 합니다.
저장소에서 설정 마무리하기
KPanel에서 저장소를 연결하는 것은 세 단계 중 첫 번째일 뿐입니다. 배포가 실행되기 전까지, 페이지에는 필요한 모든 정보와 함께 설정 완료: 2단계 남음이라는 배너가 표시됩니다.
2단계: 배포 키 추가하기
KapsuleHost는 저장소를 클론하기 위해 읽기 권한이 필요합니다. 배너에는 키 복사 버튼과 함께 공개 키가 표시됩니다.
이를 저장소의 배포 키 설정에 붙여넣으세요. GitHub의 경우 배너에서 올바른 설정 페이지로 바로 이동하는 GitHub에 추가 단축 버튼을 제공합니다. 읽기 권한이면 충분하며, 쓰기 권한은 부여하지 마세요.
3단계: Webhook 추가하기
webhook은 푸시가 발생했음을 KapsuleHost에 알려주는 역할을 합니다. 배너는 세 가지 값을 제공합니다:
| 필드 | 값 |
|---|---|
| 페이로드 URL | /api/git-deploy/webhook/으로 끝나고 이 사이트의 ID가 붙은 URL |
| Secret | 생성된 서명 시크릿으로, 눈 모양 아이콘을 클릭하기 전까지 숨겨져 있습니다 |
| 콘텐츠 유형 | application/json |
각 값을 저장소의 webhook 설정에 복사하세요. GitHub의 경우 GitHub에 webhook 추가 단축 버튼이 있습니다. 콘텐츠 유형은 기본값인 폼 인코딩이 아니라 JSON으로 설정하세요. 그렇지 않으면 페이로드가 파싱되지 않습니다.
webhook 시크릿은 비밀번호처럼 다루세요. 이를 가진 사람은 페이로드 URL과 함께 사이트의 배포를 트리거할 수 있습니다. 두 값 모두 이미 사이트를 관리할 수 있는 사람에게만 표시되며, 시크릿은 요청하기 전까지 눈 모양 아이콘 뒤에 숨겨져 있습니다.
수동으로 배포하기
Git Deploy 페이지에서 지금 배포를 클릭하면 커밋을 푸시하지 않고도 설정된 브랜치의 현재 head를 빌드하고 배포합니다. 이는 자동 배포가 켜져 있든 꺼져 있든 작동하며, 바로 이 점 때문에 프리즈 기간 중 올바른 도구가 됩니다. 푸시는 무시되지만, 수정 사항은 여전히 배포할 수 있습니다.
배포 히스토리 확인하기
Environment를 연 다음 배포를 여세요. 페이지 제목은 배포 히스토리이며, webhook 또는 수동으로 트리거된 모든 배포를 최신순으로 나열합니다.
각 행에는 다음이 표시됩니다:
- 상태 아이콘과 짧은 커밋 SHA, 그리고 알약 모양으로 표시된 브랜치.
- 커밋 메시지, 표시할 커밋 메시지가 없는 경우 수동 배포.
- 작성자, 실행된 지 얼마나 되었는지, 소요 시간, 그리고 무엇이 트리거했는지.
- 상태 알약(pill).
상태는 pending, building, deploying, success, failed가 있습니다. 무언가 진행 중인 동안에는 페이지가 5초마다 자동으로 새로고침되며 테이블 아래에 Refreshing automatically 메모가 표시되므로, 페이지를 열어둔 채 배포가 완료되는 것을 지켜볼 수 있습니다.
배포가 실패했을 때
실패한 행에는 오른쪽에 Error 버튼이 생깁니다. 클릭하면 페이지를 벗어나지 않고 캡처된 오류 출력이 인라인으로 펼쳐집니다. 이 출력은 빌드 자체의 오류 텍스트이므로, 보통 실패한 파일이나 명령을 알려줍니다.
다음 순서로 작업하세요: 오류를 읽고, 로컬에서 같은 빌드 명령을 재현하고, 수정한 다음, 푸시하세요. 로컬에서는 빌드가 되는데 여기서는 안 된다면, 그 차이는 거의 항상 환경 차이, 즉 로컬 머신에만 전역으로 설치된 누락된 의존성이나, 작업 디렉토리에는 있지만 커밋되지 않은 파일 때문입니다.
빌드팩 감지
Node.js 사이트에서는 앱 그룹의 Buildpack 페이지에서 KapsuleHost가 앱을 빌드하기로 결정한 방식을 보여줍니다. 감지는 저장소 루트의 파일들을 대상으로 실행되며, 가장 먼저 일치하는 항목이 적용됩니다:
| 감지된 항목 | 트리거 |
|---|---|
| 커스텀 빌드팩 | 루트에 kapsule.config.yaml 또는 kapsule.config.yml |
| Dockerfile 빌드팩 | 루트에 Dockerfile |
| Node.js | start, build 또는 dev 스크립트가 있는 package.json |
| Python | requirements.txt 또는 pyproject.toml |
| PHP | composer.json |
| 정적 사이트 | 루트에 index.html |
아무것도 일치하지 않으면 페이지에서 이를 알려주고 지원되는 트리거를 나열합니다. 빌드를 명시적으로 제어하려면 Dockerfile 또는 kapsule.config.yaml를 추가하세요.
빌드 실행하기
빌드 실행를 클릭하면 빌드가 대기열에 등록됩니다. 실행이 진행되는 동안 페이지는 3초마다 폴링하며, 최근 빌드 테이블에는 최근 실행 기록이 시작 시간, 유형, 상태, 소요 시간, 결과 이미지 참조와 함께 표시됩니다. 행을 클릭하면 로그 끝부분을 볼 수 있습니다.
한 번에 하나의 빌드만 진행할 수 있습니다. 하나가 대기 중이거나 실행 중일 때 두 번째 빌드를 트리거하면 빌드가 이미 진행 중입니다라는 메시지와 함께 거부되는데, 이는 의도된 동작입니다. 두 빌드가 동시에 같은 출력을 작성하면 절반만 배포된 사이트가 되기 때문입니다.
연결 끊기
Disconnect를 클릭하고 확인하세요. 확인 창에는 영향 범위가 명시적으로 안내됩니다. Git 배포 설정과 배포 키는 제거되지만, 사이트 파일에는 영향이 없습니다. 사이트는 마지막으로 배포된 내용을 계속 제공합니다.
이후 저장소 설정에서 배포 키와 webhook을 삭제하여 정리하세요. 삭제하지 않아도 그냥 작동하지 않게 될 뿐이지만, 사용하지 않는 항목을 남겨두면 다음 감사를 더 어렵게 만듭니다.
문제 해결
푸시가 아무것도 트리거하지 않습니다. 먼저 자동 배포 토글을 확인한 다음, 저장소의 webhook을 확인하세요. 대부분의 제공업체는 최근 전송 내역과 응답 코드를 보여주므로, 요청이 저장소를 벗어났는지 여부를 즉시 알 수 있습니다.
클론이 실패합니다. 배포 키가 누락되었거나, 줄바꿈이 포함된 채로 붙여넣어졌거나, 잘못된 저장소에 추가되었을 수 있습니다. 텍스트를 직접 선택하는 대신 키 복사 버튼으로 다시 복사하세요.
배포는 성공했지만 사이트가 바뀌지 않습니다. 출력 디렉토리가 잘못되었을 가능성이 큽니다. 빌드가 dist에 결과물을 작성하는데 출력 디렉토리가 비어 있다면, 빌드된 파일이 서빙되는 루트에 전혀 도달하지 못합니다.
모든 것이 pending 상태로 표시되고 진행되지 않습니다. 배포가 대기열에 등록되었지만 처리되지 않은 상태입니다. 수동으로 지금 배포를 트리거하고 Deploys 페이지에서 오류 행이 있는지 확인하세요.
다음으로 볼 만한 내용
- 풀 리퀘스트용 미리보기 배포는 이 설정 위에 PR별 URL을 추가합니다.
- 사이트용 앱 시크릿 저장하기는 빌드와 런타임에 필요한 자격 증명에 대해 다룹니다.
- 사이트 활동 로그는 여기서 이루어진 설정 변경 사항을 기록합니다.