Deploy Hooks를 통한 배포 트리거하기

A deploy hook is a secret URL that queues a new deployment when something sends it an HTTP POST. There is no authentication header: the secrecy of the URL is the authentication. Use hooks to let a…

Deploy hook는 무언가가 HTTP POST를 보낼 때 새로운 배포를 큐에 추가하는 비밀 URL입니다. 인증 헤더는 없습니다: URL의 비밀성이 인증입니다. Hook을 사용하여 헤드리스 CMS, cron 작업, CI 파이프라인 또는 다른 webhook이 git push 없이 프로젝트를 다시 빌드하도록 할 수 있습니다.

Deploy Hook 찾기

Hook은 자체 탭을 가지고 있습니다: Orbit에서 프로젝트를 열고 Hooks를 클릭합니다. /orbit/<project-id>/hooks 위치에 있습니다.

동일한 Deploy hooks 패널은 프로젝트의 Settings 탭 중간 부분에도 나타나므로, 두 위치 중 어느 곳에서나 관리할 수 있습니다.

Orbit의 Deploy hooks 패널

Deploy Hook 생성

Orbit을 열고, 프로젝트를 열고, Hooks를 열기
Add deploy hook를 클릭
6개월 후에도 의미 있을 Hook name을 입력합니다. 자리 표시자는 형식을 제안합니다: "Contentful publish", "Nightly cron"
Target environment를 선택합니다. 기본값은 **Production (default)**입니다. 프로젝트에 스테이징 환경이 있는 경우, hook을 대신 스테이징으로 지정할 수 있습니다.
Create hook을 클릭합니다.

Hook은 URL, Copy URL 버튼 및 Delete hook 버튼과 함께 목록에 나타납니다.

Hook URL

Hook URL은 다음과 같이 보입니다:

https://kpanel.kapsulehost.com/api/orbit/hooks/<token>

토큰은 hook을 생성할 때 생성되는 고유한 비밀입니다.

Hook URL을 정확히 API 키처럼 취급합니다. 이를 소유한 모든 사람이 프로젝트의 배포를 트리거할 수 있으며, Orbit의 배포 게이트 중 어느 것도 이를 막지 못합니다: 배포 잠금, 필수 승인, CI 필수 확인 및 필수 스테이징 성공은 모두 push로 트리거된 배포에만 적용되며, hook은 직접 통과합니다. Hook URL을 공개 저장소, 공유 문서, 스크린샷 또는 지원 티켓에 절대 붙여 넣지 마세요.

Hook 트리거

POST 요청을 보냅니다. 본문과 헤더는 필요하지 않습니다.

curl -X POST \
  https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Orbit은 HTTP 202와 배포 ID로 응답합니다. 배포는 몇 초 내에 Deployments 탭에 나타납니다.

엔드포인트는 POST만 허용합니다. GET 요청은 배포를 트리거하지 않습니다. 일부 이전 webhook 통합은 기본값으로 GET을 사용하므로, 구성한 hook이 절대 작동하지 않으면 메서드를 확인하세요.

Hook이 실제로 배포하는 것

Hook은 대상 환경(선택한 환경 또는 프로젝트의 프로덕션 환경)을 확인하고, 해당 환경의 분기를 읽고, git 제공자에게 해당 분기의 현재 head 커밋을 요청합니다. 그런 다음 해당 커밋의 배포를 큐에 추가합니다.

이는 알아야 할 세 가지 결과를 낳습니다:

Hook은 항상 분기 head를 배포합니다. 요청 본문에 커밋 SHA 또는 분기 이름을 전달할 수 없습니다: 요청 본문은 완전히 무시됩니다.
Hook은 작동하는 제공자 연결이 필요합니다. GitHub, GitLab 또는 Bitbucket을 연결 해제한 경우, hook은 분기 head를 읽을 수 없고 구식 코드를 배포하지 않고 오류와 함께 실패합니다.
Hook은 전체 빌드를 다시 실행합니다. 롤백도 아니고 프로모션도 아닙니다: 현재 분기에 있는 것의 새로운 빌드입니다.

반복 및 겹치는 호출

Orbit은 각 호출에 대해 빌드를 큐에 추가하기보다는 burst of hook 호출을 합리적으로 처리합니다.

동일한 commit에 대한 배포가 이미 해당 환경에서 진행 중인 경우, hook은 기존 배포를 반환하고 응답을 중복 제거된 것으로 표시합니다. 두 번째 빌드는 시작되지 않습니다.
해당 환경에서 다른 commit에 대해 빌드가 실행 중인 경우, 자동으로 취소되고 새로운 것으로 대체되므로, 출력이 이미 대체된 빌드에 대한 비용을 지불하지 않습니다.

이것은 게시된 항목당 webhook을 실행하는 CMS를 위해 hook을 안전하게 만듭니다. 1분 안에 6개의 페이지를 게시하면 6개가 아닌 1개의 빌드를 생성하고, 6개 빌드분의 분을 소비하지 않습니다.

헤드리스 CMS 연결

대부분의 헤드리스 CMS에는 "webhook on publish" 기능이 있습니다. 패턴은 항상 동일합니다: webhook을 hook URL에 지정하고, POST를 사용하고, 인증 설정을 비워 둡니다.

Contentful

Settings로 이동한 후 Webhooks로 이동한 후 Add webhook을 클릭합니다.
URL을 Orbit hook URL로 설정합니다.
메서드를 POST로 설정합니다.
트리거를 Publish 또는 사이트를 다시 빌드해야 하는 콘텐츠 이벤트로 설정합니다.
저장합니다.

Sanity

프로젝트 대시보드에서 API로 이동한 후 Webhooks로 이동한 후 Create webhook을 클릭합니다. URL을 hook URL로, 메서드를 POST로 설정하고, 데이터 세트와 트리거 이벤트를 선택합니다.

Prismic

대시보드에서 Settings로 이동한 후 Webhooks로 이동하고 hook URL을 추가합니다. Prismic은 모든 문서 게시에 대해 이를 호출합니다.

Cron 작업 또는 CI 파이프라인 연결

HTTP 요청을 할 수 있는 모든 스케줄러가 작동합니다:

# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

CI의 경우, deploy hook은 파이프라인이 배포 발생 여부를 결정하려고 할 때 가장 간단한 옵션입니다. Bitbucket Pipelines의 권장 방법입니다. Orbit의 CI 필수 확인은 GitHub Actions 작업 이름 또는 GitLab 파이프라인에서 게이트되지만, Bitbucket에서는 게이트되지 않기 때문입니다.

"분기 head 배포"보다 더 필요한 경우, hook 대신 API 토큰을 사용합니다. Orbit으로 이동한 후 Tokens은 문서화된 REST API 및 준비된 GitHub Actions 워크플로우를 사용하여 CI/CD용 범위 지정 bearer 토큰을 생성합니다. API 액세스는 Apex 플랜에 포함되어 있습니다.

Hook 없이 일정에 따라 다시 빌드

모든 작업이 정기적인 다시 빌드인 경우, hook이 전혀 필요하지 않습니다. Settings의 Runtime 아래 Scheduled rebuild는 프로덕션을 1시간, 6시간, 12시간, 매일, 2일마다 또는 매주 자동으로 다시 빌드합니다. CMS 기반 사이트 사례를 위해 정확히 구성되었으며 보호할 비밀 URL이 없습니다.

Hook 활동 확인

각 hook 행은 "Used 14 times, last 3 Jul" 형식으로 사용된 횟수와 마지막 사용 시간을 표시합니다. 이는 CMS가 실제로 생각하는 때에 hook을 호출하고 있는지 확인하는 가장 빠른 방법입니다.

횟수가 증가하지 않으면, 문제는 호출 측에 있습니다: 메서드가 POST인지, URL이 정확한지, 통합이 TLS 또는 방화벽 오류에서 자동으로 실패하지 않는지 확인하세요.

Hook 삭제

행의 Delete hook을 클릭하고 확인합니다. 대화상자는 이를 사용하는 모든 서비스가 작동하지 않을 것이라는 경고를 제공하며, 이것이 정확히 일어나는 일입니다.

hook의 토큰을 제자리에서 회전할 방법이 없습니다. URL이 누출되면, hook을 삭제하고 새로운 것을 생성한 다음, 이전 URL을 사용한 모든 시스템을 업데이트합니다. 삭제는 즉시 적용되므로, 삭제 후가 아니라 삭제 전에 교환을 계획합니다.

문제 해결

Hook을 호출할 때 아무것도 일어나지 않습니다. 메서드가 POST인지 확인합니다. URL을 토큰을 포함하여 문자 단위로 확인합니다. Hooks 탭에서 hook의 사용량 개수를 확인합니다: 증가하지 않으면, 요청이 도착하지 않았습니다.

Hook은 최신 커밋에 대한 오류를 반환합니다. Orbit은 git 제공자로부터 분기 head를 읽을 수 없습니다. Orbit에서 제공자를 다시 연결한 후 New project로 이동한 후 Reconnect로 이동하고, 저장소가 여전히 액세스 가능한지 확인합니다.

Hook은 대상 환경에 대한 오류를 반환합니다. Hook이 지정한 환경이 더 이상 존재하지 않습니다. 스테이징 환경이 삭제되었을 가능성이 큽니다. Hook을 삭제하고 활성 환경에 대해 새로운 것을 생성합니다.

Hook은 작동하지만 배포는 마지막 시간과 동일합니다. 이는 중복 제거 동작입니다: 분기 head가 변경되지 않았으므로, 빌드할 새로운 것이 없습니다. 커밋을 push하거나, 특별히 동일한 커밋을 다시 빌드하려는 경우 Deploy now를 사용합니다.