Git에서 사이트 배포하기

Git Deploy는 저장소를 사이트에 연결하여 선택한 브랜치에 푸시할 때마다 코드를 복제하고 빌드를 실행한 후 결과를 게시합니다. 이 가이드는 초기 연결, 설정을 완료하는 두 가지 저장소 쪽 단계, 배포 기록 읽기, 그리고 Node.js 앱이 어떻게 빌드되는지 결정하는 빌드팩 감지를 다룹니다.

Git Deploy의 위치

Websites를 열고, 사이트를 클릭한 후, 사이트 탭 스트립에서 Advanced 메뉴를 열고 Git Deploy를 선택합니다. 같은 메뉴에는 두 개의 관련 페이지가 있습니다:

• Deploys, 이 사이트의 전체 배포 기록.
• Buildpack, 감지된 빌드 전략 (Node.js 사이트의 경우).

Git Deploy 페이지는 자명하게 설명됩니다: 저장소를 연결하면 구성된 브랜치에 대한 모든 푸시가 빌드 및 배포를 트리거합니다.

저장소 연결하기

1. Provider 선택: GitHub, GitLab 또는 Bitbucket.
2. Repository URL을 입력합니다. SSH 형식이 필요한 형식입니다. 예를 들어 git@github.com:user/repo.git.
3. 배포할 Branch를 설정합니다. 필드는 main에서 시작합니다.
4. 선택적으로 Build command를 설정합니다. 예를 들어 npm run build.
5. 선택적으로 Output directory를 설정합니다. 예를 들어 dist, public, 또는 . (이미 빌드된 저장소의 경우).
6. Connect repo를 클릭합니다.

저장소가 그대로 배포 가능한 경우 (일반 PHP 또는 정적 사이트의 경우가 일반적) 빌드 명령 및 출력 디렉토리를 비워둡니다.

Advanced Scripts

Advanced를 확장하면 두 개의 추가 필드가 표시됩니다:

• Pre-deploy script, 빌드 전에 실행됩니다.
• Post-deploy script, 배포 후에 실행됩니다.

새 코드가 배치된 후 발생해야 하는 작업(애플리케이션 캐시 지우기, 데이터베이스 마이그레이션 실행, 워커 재시작)을 위해 post-deploy 훅을 사용합니다.

Auto-Deploy On Push

카드 맨 아래의 토글은 푸시가 배포를 트리거하는지 여부를 제어합니다. 토글이 켜져 있으면, 구성된 브랜치에 대한 모든 푸시가 배포를 트리거합니다. 토글이 꺼져 있으면, Deploy now로 수동으로 트리거할 때만 배포가 실행됩니다.

저장소에서 설정 마무리하기

KPanel에서 저장소를 연결하는 것은 3단계 중 첫 번째일 뿐입니다. 배포가 실행될 때까지 페이지에는 Complete setup: 2 steps remaining 배너가 표시되며 필요한 모든 것이 있습니다.

Step 2: Deploy Key 추가하기

Kapsule은 저장소를 복제하기 위해 읽기 권한이 필요합니다. 배너에는 Copy key 버튼이 있는 공개 키가 표시됩니다.

저장소의 배포 키에 붙여넣으세요. GitHub의 경우 배너는 올바른 설정 페이지로 바로 가는 Add to GitHub 단축키를 제공합니다. 읽기 권한만으로 충분하므로 쓰기 권한은 부여하지 마세요.

Step 3: Webhook 추가하기

웹훅은 Kapsule에 푸시가 발생했음을 알려줍니다. 배너는 다음 세 가지 값을 제공합니다:

각각을 저장소의 웹훅 설정에 복사합니다. GitHub의 경우 Add webhook to GitHub 단축키가 있습니다. 콘텐츠 타입을 기본 form-encoded가 아닌 JSON으로 설정하세요. 그렇지 않으면 페이로드가 파싱되지 않습니다.

수동으로 배포하기

Git Deploy 페이지에서 Deploy now를 클릭하여 푸시 커밋 없이 구성된 브랜치의 현재 헤드를 빌드하고 배포합니다. 이는 자동 배포의 켜짐/꺼짐 여부와 관계없이 작동하며, 이것이 동결 중에 올바른 도구인 이유입니다: 푸시는 무시되지만 여전히 수정 사항을 배포할 수 있습니다.

배포 기록 읽기

Advanced를 열고 Deploys를 엽니다. 페이지의 제목은 Deploy history이며 웹훅 또는 수동으로 트리거된 모든 배포를 최신순으로 나열합니다.

각 행에는 다음이 포함됩니다:

• 상태 아이콘과 짧은 커밋 SHA (브랜치는 pill로 표시).
• 커밋 메시지 또는 표시할 커밋 메시지가 없는 경우 Manual deploy.
• 작성자, 실행된 시간, 소요된 시간 및 트리거한 것.
• 상태 pill.

상태는 pending, building, deploying, success 및 failed입니다. 진행 중인 것이 있으면 페이지는 5초마다 새로 고침되고 표 아래에 Refreshing automatically 메모를 표시하므로 페이지를 열어 놓고 배포가 완료되는 것을 볼 수 있습니다.

배포 실패 시

실패한 행의 오른쪽에 Error 버튼이 있습니다. 이를 클릭하면 페이지를 떠나지 않고 캡처된 오류 출력이 인라인으로 확장됩니다. 그 출력은 빌드 자체의 오류 텍스트이므로 일반적으로 실패한 파일이나 명령을 이름으로 지정합니다.

이 순서대로 진행하세요: 오류를 읽고, 로컬에서 동일한 빌드 명령을 재현하고, 수정하고, 푸시합니다. 빌드가 로컬에서는 작동하지만 여기서는 작동하지 않으면, 그 차이는 거의 항상 환경 차이입니다. 머신에 전역적으로 설치된 누락된 종속성이거나 작업 디렉토리에는 있지만 커밋되지 않은 파일입니다.

Buildpack 감지

Node.js 사이트에서 Advanced 메뉴의 Buildpack 페이지는 Kapsule이 앱을 어떻게 빌드하기로 결정했는지 보여줍니다. 감지는 저장소 루트의 파일에 대해 실행되며, 첫 번째 일치가 우선입니다:

아무것도 일치하지 않으면, 페이지가 그렇게 표시되고 지원되는 트리거를 나열합니다. Dockerfile 또는 kapsule.config.yaml를 추가하여 빌드를 명시적으로 제어합니다.

빌드 실행하기

Run build를 클릭하여 하나를 큐에 추가합니다. 페이지는 실행 중인 동안 3초마다 폴링하며, Recent builds 테이블은 시작 시간, 유형, 상태, 소요 시간 및 결과 이미지 참조가 있는 최근 실행을 보여줍니다. 행을 클릭하여 로그 끝을 봅니다.

한 번에 하나의 빌드만 진행 중일 수 있습니다. 하나가 큐에 있거나 실행 중인 동안 두 번째를 트리거하면 A build is already in progress로 거부되며, 이는 의도적입니다: 두 빌드가 동일한 출력에 동시에 기록되는 것은 반 배포된 사이트를 얻는 방법입니다.

연결 해제하기

Disconnect를 클릭하고 확인합니다. 확인은 영향 범위를 명시적으로 설명합니다: Git 배포 구성과 배포 키가 제거되며, 사이트 파일은 영향을 받지 않습니다. 사이트는 마지막으로 배포된 것을 계속 제공합니다.

나중에 저장소 설정에서 배포 키와 웹훅을 삭제하여 정리합니다. 간단히 작동하지 않지만, 죽은 항목을 남겨 두면 다음 감사가 더 어려워집니다.

문제 해결

푸시가 아무것도 트리거하지 않습니다. 자동 배포 토글을 먼저 확인한 다음 저장소의 웹훅을 확인합니다. 대부분의 공급자는 최근 배포와 응답 코드를 표시하므로, 요청이 저장소를 떠났는지 여부를 즉시 알 수 있습니다.

복제가 실패합니다. 배포 키가 누락되었거나, 줄 바꿈이 있는 상태로 붙여넣어졌거나, 잘못된 저장소에 추가되었습니다. Copy key 버튼으로 다시 복사하되 직접 텍스트를 선택하지 마세요.

배포는 성공하지만 사이트가 변경되지 않습니다. 출력 디렉토리가 아마 잘못되었을 것입니다. 빌드가 dist로 쓰고 출력 디렉토리가 비어있으면, 빌드된 파일이 제공되는 루트에 도달하지 않습니다.

모든 것이 pending이라고 표시되고 움직이지 않습니다. 배포가 큐에 추가되었지만 선택되지 않았습니다. 수동 Deploy now를 트리거하고 Deploys 페이지에서 오류 행을 확인합니다.

다음으로 할 일

• Preview Deploys For Pull Requests 이 설정 위에 PR당 URL을 추가합니다.
• Storing App Secrets For a Site 빌드 및 런타임에 필요한 자격 증명을 위해.
• Site Activity Log 여기서 만든 구성 변경 사항을 기록합니다.