GitLab 웹훅에서 자주 발생하는 문제를 진단하고 해결합니다.

웹훅 디버그#

다음 방법으로 GitLab 웹훅을 디버그하고 페이로드를 확인합니다.

• 공개 웹훅 검사 도구
• 웹훅 요청 및 응답 세부 정보
• GitLab Development Kit(GDK)
• 비공개 웹훅 수신기

웹훅 이벤트와 JSON 페이로드에 대한 정보는 웹훅 이벤트를 참고합니다.

공개 웹훅 검사 도구 사용#

공개 도구를 사용하여 웹훅 페이로드를 검사하고 테스트합니다. 이 도구들은 HTTP 요청을 모두 받는 엔드포인트를 제공하고 200 OK 상태 코드로 응답합니다.

공개 웹훅 검사 도구에는 다음이 있습니다.

• Beeceptor: 임시 HTTPS 엔드포인트를 만들고 수신 페이로드를 검사합니다.

• Webhook.site: 수신 페이로드를 검토합니다.
• Webhook Tester: 수신 페이로드를 검사하고 디버그합니다.

GitLab Development Kit(GDK) 사용#

더 안전한 개발 환경이 필요하다면 GitLab Development Kit(GDK)로 GitLab 웹훅을 로컬에서 다룹니다. GDK를 사용하면 로컬 GitLab 인스턴스에서 자신의 머신에 있는 웹훅 수신기로 웹훅을 보낼 수 있습니다.

이 방법을 사용하려면 GDK를 설치하고 구성합니다.

비공개 웹훅 수신기 만들기#

웹훅 페이로드를 공개 수신기로 보낼 수 없다면 자체 비공개 웹훅 수신기를 만듭니다.

사전 요구 사항:

• 시스템에 Ruby가 설치되어 있어야 합니다.

비공개 웹훅 수신기를 만들려면 다음과 같이 진행합니다.

1. 다음 스크립트를 print_http_body.rb로 저장합니다.

   require 'webrick'
   
   server = WEBrick::HTTPServer.new(:Port => ARGV.first)
   server.mount_proc '/' do |req, res|
     puts req.body
   end
   
   trap 'INT' do
     server.shutdown
   end
   server.start
   

2. 사용하지 않는 포트(예: 8000)를 선택하고 스크립트를 시작합니다.

   ruby print_http_body.rb 8000
   

3. GitLab에서 수신기의 URL(예: http://receiver.example.com:8000/)로 웹훅을 구성합니다.

4. Test를 선택합니다. 다음과 비슷한 출력이 표시됩니다.

   {"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",}
   example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0
   - -> /
   

SSL 인증서 검증 오류 해결#

SSL 검증을 활성화하면 GitLab 이 웹훅 엔드포인트의 SSL 인증서를 검증하지 못하고 다음 오류가 발생할 수 있습니다.

unable to get local issuer certificate

이 오류는 대개 CAcert.org가 신뢰할 수 있다고 판단하는 인증 기관에서 루트 인증서를 발급하지 않은 경우에 발생합니다.

이 문제를 해결하려면 다음과 같이 진행합니다.

1. SSL Checker로 구체적인 오류를 확인합니다.
2. 검증 실패의 흔한 원인인 중간 인증서 누락 여부를 확인합니다.

웹훅이 트리거되지 않음#

웹훅이 트리거되지 않으면 다음을 확인합니다.

• 웹훅이 자동으로 비활성화되지 않았는지 확인합니다.
• GitLab 인스턴스가 사일런트 모드가 아닌지 확인합니다.
• Admin 영역의 Push event activities limit 및 Push event hooks limit 설정이 0보다 큰 값인지 확인합니다.

오류: Webhook rate limit exceeded#

속도 제한 때문에 웹훅이 실패할 수 있습니다. GitLab.com은 최상위 네임스페이스마다 분당 전체 웹훅 호출 수를 제한합니다. 자세한 내용은 속도 제한을 참고합니다.

속도 제한이 원인인지 확인하려면 다음과 같이 진행합니다.

1. GitLab 로그에 Webhook rate limit exceeded 메시지가 있는지 확인합니다.
2. 웹훅을 트리거하는 이벤트 수를 줄이거나, GitLab 지원팀에 문의하여 속도 제한 요건을 논의합니다.

따옴표 없는 플레이스홀더가 있는 사용자 정의 웹훅 템플릿을 저장할 수 없음#

GitLab 18.8부터 18.10까지는 페이로드 필드에 따옴표가 없는 사용자 정의 웹훅 템플릿을 저장할 수 없습니다. 이 문제는 GitLab 18.11에서 해결되었습니다. 임시 해결책으로 필드를 따옴표로 감싸거나 GitLab 18.11 이상으로 업그레이드합니다. 예를 들어 {"value": {{id}}}는 {"value": "{{id}}"}가 됩니다.

따옴표로 감싼 필드는 숫자 값이 아니라 문자열 값을 만듭니다. 이 동작이 사용 중인 웹훅과 맞지 않아 웹훅을 수정해야 한다면 업그레이드를 권장합니다.

거부 이후 중복되는 배포 실패 알림#

보호된 환경으로의 배포가 거부되면 GitLab은 status: "rejected" 웹훅을 보내고, 이어서 배포 job 이 중단될 때 같은 deployment_id에 대해 status: "failed" 웹훅을 보냅니다. failed 이벤트는 기존 라이프사이클 이벤트이며 승인 관련 필드를 포함하지 않으므로, status: "failed"를 기준으로 알림을 보내는 수신기는 의도적으로 거부된 배포에 대해 중복 알림을 올릴 수 있습니다.

중복 알림을 피하려면 다음과 같이 진행합니다.

1. deployment_id로 이벤트를 연관 지어, 같은 배포에서 status: "rejected" 이벤트 뒤에 오는 status: "failed" 이벤트를 같은 이벤트로 처리합니다.
2. 거부로 인한 실패와 실제 실패를 구분하려면 status: "rejected" 이벤트를 수신하여 거부된 배포 ID를 저장합니다. status: "failed" 이벤트가 도착하면 해당 deployment_id가 그 집합에 있을 때 알림을 억제합니다.