- 그룹 웹훅
- GitLab에서 웹훅 구성
- 웹훅 요청 기록보기
- 웹훅 수신자 요구 사항
- 자동으로 비활성화된 웹훅
- 웹훅 테스트
- 전달 헤더
- 웹훅 디버깅
- 웹훅 본문에 표시되는 이미지 URL 처리 방법
- 상호 TLS를 지원하도록 웹훅 구성
- 관련 주제
- 문제 해결
웹훅
웹훅은 이벤트에 의해 트리거되는 사용자 정의 HTTP 콜백으로, 리포지터리에 코드를 푸시하거나 이슈에 댓글을 게시하는 등의 이벤트에 반응합니다. 웹훅은 이벤트에 대한 JSON 데이터를 웹훅에 구성된 URI로 전송합니다. 이러한 이벤트 및 웹훅 페이로드에 전송된 JSON 데이터에 대한 자세한 정보는 웹훅 이벤트를 참조하십시오.
웹훅을 사용하여 다음 작업을 수행할 수 있습니다.
- CI/CD 작업 트리거, 외부 이슈 트래커 및 백업 미러 업데이트, 또는 프로덕션 서버로의 배포.
- GitLab에서 특정 프로젝트 또는 그룹에 대한 문제가 생성될 때마다 Twilio와 통합하여 SMS 알림 수신.
- Merge Request에 자동으로 레이블을 할당하는 것처럼 Merge Request에 자동으로 레이블을 할당.
GitLab.com에서는 웹훅 제한이 강제되며 다음을 포함합니다:
- 프로젝트 또는 그룹 당 최대 웹훅 수
- 분당 웹훅 호출 수
- 웹훅 시간 초과 시간
GitLab Self-Managed의 경우, 관리자는 이러한 제한을 변경할 수 있습니다.
그룹 웹훅
그룹 및 그 하위 그룹의 모든 프로젝트에서 발생하는 이벤트에 의해 트리거되는 그룹 웹훅을 구성할 수 있습니다. 그룹과 프로젝트에서 동일한 웹훅을 구성하는 경우 이들은 모두 프로젝트의 이벤트로 트리거됩니다.
그룹 웹훅은 또한 그룹에 특정한 이벤트를 수신하도록 구성할 수 있으며, 이에는 다음이 포함됩니다:
GitLab에서 웹훅 구성
웹훅 생성
- 이름 및 설명은 GitLab 16.9에서 소개되었습니다.
프로젝트 또는 그룹에 웹훅을 생성하려면:
- 프로젝트 또는 그룹의 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
- 새 웹훅 추가를 선택합니다.
- URL에 웹훅 엔드포인트의 URL을 입력합니다. URL에 하나 이상의 특수 문자가 포함되어 있으면 URL을 퍼센트 인코드해야 합니다.
- 선택 사항. 이름에 웹훅의 이름을 입력합니다.
- 선택 사항. 설명에 웹훅의 설명을 입력합니다.
-
선택 사항. 비밀 토큰에 요청을 유효성 검사하기 위한 비밀 토큰을 입력합니다.
해당 토큰은 웹훅 요청과 함께
X-Gitlab-Token
HTTP 헤더로 전송됩니다. 웹훅 엔드포인트는 요청이 유효한지 확인하기 위해 토큰을 확인할 수 있습니다. - 트리거 섹션에서 웹훅을 트리거할 GitLab 이벤트의 확인란을 선택합니다.
- 선택 사항. [SSL 확인 사용 안 함] 확인란을 선택 해제하여 SSL 확인을 비활성화합니다.
- 웹훅 추가를 선택합니다.
웹훅 URL의 민감한 부분 마스킹
- GitLab 15.5에서 플래그
webhook_form_mask_url
로 소개되었습니다. 기본적으로 비활성화되어 있습니다.- GitLab 15.7에서는 일반적으로 사용 가능 합니다. 플래그
webhook_form_mask_url
이 제거되었습니다.
웹훅 URL의 민감한 부분을 정의하고 마스킹하여 실행 중일 때 웹훅에 구성된 값으로 교체할 수 있습니다. 민감한 부분은 로그에 기록되지 않으며 데이터베이스에 저장될 때 암호화됩니다.
웹훅 URL의 민감한 부분을 마스킹하려면:
- 프로젝트 또는 그룹의 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
- URL에 완전한 웹훅 URL을 입력합니다.
- URL 일부 마스킹을 선택합니다.
- URL의 민감한 부분에 마스킹하려는 부분을 입력합니다.
- UI에서의 보이는 모습에 마스킹 값 입력합니다.
개별 웹훅에 민감한 부분을 보간하려면 url_variables
를 사용하세요.
예를 들어, 웹훅에 다음과 같은 URL이 있는 경우:
https://webhook.example.com/{path}?key={value}
다음 변수를 정의해야 합니다:
path
value
변수 이름은 소문자 (a-z
), 숫자 (0-9
), 또는 밑줄 (_
)만 포함해야 합니다.
URL 변수는 REST API를 사용하여 직접 정의할 수 있습니다.
마스크 변수를 사용하지 않고도 유효한 호스트 부분(예: webhook.example.com
)을 사용해야 합니다.
그렇지 않으면 URI가 잘못되었음
또는 URL이 차단되었음
오류가 발생합니다.
사용자 정의 헤더
- GitLab 16.11에서 플래그
custom_webhook_headers
로 소개되었습니다. 기본적으로 활성화되어 있습니다.- GitLab 17.0에서는 일반적으로 사용 가능 합니다. 플래그
custom_webhook_headers
가 제거되었습니다.
요청의 일부로 웹훅 구성에 최대 20개의 사용자 정의 헤더를 추가할 수 있습니다. 이러한 사용자 정의 헤더를 외부 서비스에 인증에 사용할 수 있습니다.
사용자 정의 헤더는 최근 이벤트에 마스킹된 값으로 표시됩니다.
사용자 정의 웹훅 템플릿
- GitLab 16.10에서 플래그
custom_webhook_template
으로 소개되었습니다. 기본적으로 활성화되어 있습니다.- GitLab 17.0에서는 일반적으로 사용 가능 합니다. 플래그
custom_webhook_template
가 제거되었습니다.
웹훅 구성에서 사용자 정의 페이로드 템플릿을 설정할 수 있습니다. 요청 본문은 현재 이벤트의 데이터로부터 템플릿에서 렌더링됩니다. 템플릿은 유효한 JSON으로 렌더링되어야 합니다.
모든 이벤트의 페이로드에서 {{build_name}}
(작업 이벤트) 또는 {{deployable_url}}
(배포 이벤트)과 같은 필드를 사용할 수 있습니다. 객체에 중첩된 속성을 액세스하려면 .
으로 구분된 경로 세그먼트를 지정하십시오. 예를 들어:
다음과 같은 사용자 정의 페이로드 템플릿이 제공되는 경우:
{
"event": "{{object_kind}}",
"project_name": "{{project.name}}"
}
다음과 같은 요청 페이로드를 얻게 됩니다 (이 템플릿은 push
이벤트와 결합됨):
{
"event": "push",
"project_name": "Example"
}
브랜치로 푸시 이벤트 필터링
푸시 이벤트를 브랜치로 필터링할 수 있습니다. 웹훅 엔드포인트로 보내는 푸시 이벤트를 필터링하기 위해 다음 중 하나의 옵션을 사용할 수 있습니다:
- 모든 브랜치: 모든 브랜치에서의 푸시 이벤트
-
와일드카드 패턴: 와일드카드 패턴과 일치하는 브랜치에서의 푸시 이벤트(예:
*-stable
또는production/*
) -
정규 표현식: 정규 표현식 (regex)과 일치하는 브랜치에서의 푸시 이벤트. 정규 표현식 패턴은 RE2 구문을 따라야 합니다. 예를 들어,
main
을 제외하려면 다음을 사용할 수 있습니다:\b(?:m(?!ain\b)|ma(?!in\b)|mai(?!n\b)|[a-l]|[n-z])\w*|\b\w{1,3}\b|\W+
프로젝트 또는 그룹에 대한 브랜치 필터링을 구성하려면 GitLab에서 웹훅 구성을 참조하십시오.
웹훅 요청 기록보기
- GitLab 15.3에서 그룹 웹훅의 최신 이벤트가 소개되었습니다.
전제 조건:
- 프로젝트 웹훅의 경우, 프로젝트의 메인테이너 역할이 필요합니다.
- 그룹 웹훅의 경우, 그룹의 소유자 역할이 필요합니다.
GitLab은 각 웹훅 요청의 이력을 기록합니다. 최신 이벤트에서는 최근 2일간의 웹훅에 대한 모든 요청을 볼 수 있습니다.
웹훅의 요청 기록을 보려면 다음 단계를 따릅니다.
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
- 설정 > 웹훅을 선택합니다.
- 웹훅에 대해 편집을 선택합니다.
- 최신 이벤트 섹션으로 이동합니다.
표에는 각 요청에 대한 다음 세부 정보가 포함됩니다.
- HTTP 상태 코드 (초록색은
200
~299
코드, 빨간색은 기타 코드, 그리고내부 오류
는 전달에 실패한 경우) - 발생한 이벤트
- 요청의 경과 시간
- 요청이 이루어진 상대적인 시간
요청 및 응답 세부 정보 검사
전제 조건:
- 프로젝트 웹훅의 경우, 프로젝트의 메인테이너 역할이 필요합니다.
- 그룹 웹훅의 경우, 그룹의 소유자 역할이 필요합니다.
최신 이벤트에 있는 각 웹훅 요청에는 요청 세부 정보 페이지가 있습니다.
이 페이지에는 다음이 포함됩니다.
- 웹훅 수신 엔드포인트에서 GitLab이 받은 응답
- GitLab이 보낸 웹훅 요청
웹훅 이벤트의 요청 및 응답 세부 정보를 검사하려면 다음 단계를 따릅니다.
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
- 설정 > 웹훅을 선택합니다.
- 웹훅에 대해 편집을 선택합니다.
- 최신 이벤트 섹션으로 이동합니다.
- 이벤트의 세부 정보 보기를 선택합니다.
같은 데이터로 요청을 다시 보내려면 요청 다시 보내기를 선택합니다.
웹훅 URL이 변경된 경우에는 요청을 다시 보낼 수 없습니다.
웹훅 수신자 요구 사항
웹훅 수신자 엔드포인트는 빠르고 안정적이어야 합니다.
느리고 불안정한 수신자는 시스템 신뢰성을 보장하기 위해 자동으로 비활성화될 수 있습니다.
시간 초과된 웹훅은 중복 이벤트를 발생시킬 수 있습니다.
엔드포인트는 다음 모범 사례를 준수해야합니다.
-
빠르게
200
또는201
상태 응답을 반환합니다.
동일한 요청에서 웹훅의 중요한 처리를 피하십시오.
대신, 웹훅을 수신한 후 처리하기 위해 대기열을 구현하세요.
응답 시간 제한에 대한 응답이 없는 웹훅 수신자는 GitLab.com에서 자동으로 비활성화될 수 있습니다. -
중복 이벤트를 처리할 준비가 되어야 합니다.
웹훅이 시간 초과되면 동일한 이벤트가 두 번 전송될 수 있습니다.
이 문제를 완화하기 위해 엔드포인트가 안정적이고 빠른지 확인하세요. -
응답 헤더 및 본문을 최소화하세요.
GitLab은 응답 헤더와 본문을 저장하여 이후에 문제를 진단하는 데 도움이 되도록 할 수 있습니다.
반환된 헤더의 수와 크기를 제한해야 합니다.
또한 웹훅 요청에 빈 본문으로 응답할 수 있습니다. - 클라이언트 오류 상태 응답 (
4xx
범위)만 반환하여 웹훅이 잘못 구성되었음을 나타냅니다.
이 범위의 응답은 웹훅을 자동으로 비활성화할 수 있습니다.
예를 들어, 수신기가 푸시 이벤트만 지원하는 경우 이슈 페이로드에 대해400
을 반환할 수 있습니다.
또는 인식되지 않는 이벤트 페이로드를 무시할 수 있습니다. - 이벤트를 처리했음에도 불구하고
500
서버 오류 상태 응답을 반환해서는 안됩니다.
해당 응답은 웹훅을 자동으로 비활성화할 수 있습니다. - 잘못된 HTTP 응답은 실패한 요청으로 처리됩니다.
자동으로 비활성화된 웹훅
- GitLab 15.7에서 프로젝트 웹훅에 대해 일반 사용 가능합니다.
web_hooks_disable_failed
피처 플래그가 제거되었습니다.- GitLab 15.10에서 그룹 웹훅에 도입되었습니다.
- GitLab 15.10에서 Self-Managed에서 auto_disabling_web_hooks이라는 플래그로 비활성화되었습니다.
플래그:
Self-Managed GitLab의 경우 기본적으로 이 기능은 사용할 수 없습니다. 관리자는 auto_disabling_web_hooks
이라는 피처 플래그를 활성화할 수 있습니다.
GitLab.com에서는이 기능을 사용할 수 있습니다. GitLab Dedicated에는이 기능이 사용할 수 없습니다.
연속적으로 네 번의 실패한 프로젝트 또는 그룹 웹훅이 자동으로 비활성화됩니다.
자동으로 비활성화된 웹훅을 보려면 다음 단계를 따릅니다.
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
- 설정 > 웹훅을 선택합니다.
자동으로 비활성화된 웹훅은 프로젝트 또는 그룹 웹훅 디렉터리에 다음과 같이 나타납니다.
- 웹훅이 일시적으로 비활성화된 경우 연결 실패
- 웹훅이 영구적으로 비활성화된 경우 연결 실패
일시적으로 비활성화된 웹훅
응답 코드가 5xx
범위에 있는 웹훅 또는 시간 초과 또는 기타 HTTP 오류를 경험하는 경우
이러한 웹훅은 간헐적으로 실패하고 일시적으로 비활성화됩니다.
이러한 웹훅은 초기에는 1분 동안 비활성화되고, 각 후속 실패에 따라 최대 24시간까지 연장됩니다.
웹훅 수신기가 더 이상 오류를 반환하지 않는 경우 매뉴얼으로 일시적으로 비활성화된 웹훅을 다시 사용할 수 있습니다.
영구적으로 비활성화된 웹훅
응답 코드가 4xx
범위에 있는 웹훅은 잘못 구성되었으며 영구적으로 비활성화됩니다.
이러한 웹훅은 다시 매뉴얼으로 사용될 때까지 비활성화됩니다.
일시적으로 비활성화된 웹훅 다시 사용하기
- webhooks_failed_callout이라는 플래그가 기본적으로 사용 안 함으로 설정되고, GitLab 15.2에서 도입되었습니다.
- GitLab 15.7에서 일반 사용 가능합니다.
webhooks_failed_callout
피처 플래그가 제거되었습니다.
일시적으로 또는 영구적으로 비활성화된 웹훅을 매뉴얼으로 다시 활성화하려면 테스트 요청을 보냅니다.
테스트 요청이 2xx
범위의 응답 코드를 반환하면 웹훅이 다시 활성화됩니다.
웹훅 테스트
웹훅을 수동으로 트리거하여 정상적으로 작동하는지 확인할 수 있습니다.
또한 비활성화된 웹훅을 다시 사용하려면 테스트 요청을 보낼 수 있습니다.
예를 들어, push 이벤트
를 테스트하기 위해서는 프로젝트에 적어도 한 개의 커밋이 있어야 합니다. 웹훅은 이 커밋을 사용합니다.
자세한 내용은 이슈 379201을 참조하십시오.
전제 조건:
- 프로젝트 웹훅을 테스트하려면 프로젝트의 메인테이너 역할이 필요합니다.
- 그룹 웹훅을 테스트하려면 그룹의 소유자 역할이 필요합니다.
웹훅을 테스트하려면 다음 단계를 따릅니다.
- 프로젝트 또는 그룹에서 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
- 구성된 웹훅 디렉터리으로 아래로 스크롤합니다.
- 테스트 드롭다운 디렉터리에서 테스트할 이벤트 유형을 선택합니다.
또한 해당 편집 페이지에서 웹훅을 테스트할 수 있습니다.
전달 헤더
엔드포인트로의 웹훅 요청에는 다음 헤더가 포함됩니다.
헤더 | 설명 | 예시 |
---|---|---|
User-Agent
| 형식화된 사용자 에이전트 "Gitlab/<VERSION>" 입니다.
| "GitLab/15.5.0-pre"
|
X-Gitlab-Instance
| 웹훅을 보낸 GitLab 인스턴스의 호스트 이름입니다. | "https://gitlab.com"
|
X-Gitlab-Webhook-UUID
| 웹훅당 고유한 식별자입니다. | "02affd2d-2cba-4033-917d-ec22d5dc4b38"
|
X-Gitlab-Event
| 웹훅 유형의 이름입니다. 이벤트 유형에 대응하지만 "<EVENT> 후크" 형식으로 표시됩니다.
| "Push 후크"
|
X-Gitlab-Event-UUID
| 재귀적이지 않은 웹훅당 고유한 식별자입니다. 해당 헤더가 동일한 GitLab 인스턴스에 의해 트리거된 이전 웹훅에 의해 트리거된 후크인 경우 후크가 재귀적입니다. | "13792a34-cac6-4fda-95a8-c58e00a3954e"
|
웹훅 디버깅
GitLab 웹훅을 디버깅하고 페이로드를 캡처하려면 다음을 사용할 수 있습니다.
웹훅 이벤트 및 웹훅 페이로드에서 전송된 JSON 데이터에 대한 정보는 웹훅 이벤트를 참조하십시오.
공개 웹훅 검사 및 테스트 도구
공개 도구를 사용하여 웹훅 페이로드를 검사 및 테스트할 수 있습니다. 이러한 도구는 HTTP 요청에 대한 catch-all 엔드포인트로 작동하고 200 OK
HTTP 상태 코드로 응답합니다. 이러한 페이로드를 사용하여 웹훅 서비스를 개발할 수 있습니다.
이러한 도구를 사용할 때 주의가 필요합니다. 외부 도구에 민감한 데이터를 전송할 수 있으므로 이러한 도구를 사용할 때 테스트 토큰을 사용하고 실수로 제3자에게 전송된 비밀을 회전시켜야 합니다. 웹훅 페이로드를 비공개로 유지하려면 개인 웹훅 수신기를 생성하십시오.
이러한 공개 도구로는 다음이 있습니다:
- Beeceptor는 일시적인 HTTPS 엔드포인트를 만들고 들어오는 페이로드를 검사합니다.
- Webhook.site은 들어오는 페이로드를 검토합니다.
- Webhook Tester은 들어오는 페이로드를 검사 및 디버깅합니다.
GitLab 개발 키트 (GDK)
보다 안전한 개발 환경을 위해 GitLab 개발 키트 (GDK)를 로컬에서 GitLab 웹훅을 개발하는 데 사용할 수 있습니다. GDK를 사용하면 로컬 GitLab 인스턴스에서 로컬 머신에서 실행 중인 웹훅 수신기로 웹훅을 보낼 수 있습니다. 이 방법을 사용하려면 GDK를 설치하고 구성해야 합니다.
개인 웹훅 수신기 생성
필수 사항:
- Ruby가 설치되어 있어야 합니다.
공개 수신기로 웹훅 페이로드를 보낼 수 없는 경우 자체 개인 웹훅 수신기를 만들 수 있습니다.
개인 웹훅 수신기를 만들려면 다음을 수행하십시오:
-
다음 파일을
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
-
사용되지 않는 포트(예:
8000
)를 선택하고 스크립트를 시작하십시오:ruby print_http_body.rb 8000
- GitLab에서 웹훅 구성하여 수신기 URL(예:
http://receiver.example.com:8000/
)을 추가하십시오. -
테스트를 선택하십시오. 콘솔에서 비슷한 메시지가 표시되어야 합니다:
{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>} example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 - -> /
이 수신기를 추가하려면 로컬 네트워크로의 요청 허용해야 할 수 있습니다.
웹훅 본문에 표시되는 이미지 URL 처리 방법
상대적인 이미지 참조는 웹훅 본문에서 절대 URL을 사용하도록 다시 작성됩니다. 예를 들어, 이미지, Merge Request, 코멘트 또는 위키 페이지에 다음 이미지 참조가 포함된 경우:
![image](/uploads/$sha/image.png)
- GitLab이
gitlab.example.com
에 설치되어 있고, - 프로젝트가
example-group/example-project
에 있을 경우,
참조가 웹훅 본문에서 다음과 같이 다시 작성됩니다:
![image](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png)
이미지 URL은 다음과 같은 경우에는 다시 작성되지 않습니다:
- 이미 HTTP, HTTPS 또는 프로토콜 상대적 URL을 가리키고 있음.
- 링크 레이블과 같은 고급 마크다운 기능을 사용하고 있음.
상호 TLS를 지원하도록 웹훅 구성
- GitLab 16.9에서 도입되었습니다.
필수 사항:
- GitLab 관리자여야 합니다.
웹훅을 상호 TLS를 지원하도록 구성할 수 있습니다. 이를 위해 PEM 형식의 클라이언트 인증서를 구성합니다. 이 인증서는 글로벌로 설정되어 TLS 핸드셰이크 중에 서버에 제시됩니다. 또한 인증서는 PEM 패스프레이즈로 보호될 수 있습니다.
인증서를 구성하려면:
:::Tabs
-
/etc/gitlab/gitlab.rb
파일을 편집하십시오:gitlab_rails['http_client']['tls_client_cert_file'] = '<클라이언트 PEM 파일 경로>' gitlab_rails['http_client']['tls_client_cert_password'] = '<옵션 비밀번호>'
-
파일을 저장하고 GitLab을 다시 구성하십시오:
sudo gitlab-ctl reconfigure
-
docker-compose.yml
파일을 편집하십시오:version: "3.6" services: gitlab: image: 'gitlab/gitlab-ee:latest' restart: always hostname: 'gitlab.example.com' environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['http_client']['tls_client_cert_file'] = '<클라이언트 PEM 파일 경로>' gitlab_rails['http_client']['tls_client_cert_password'] = '<옵션 비밀번호>'
-
파일을 저장하고 GitLab을 다시 시작하십시오:
docker compose up -d
-
/home/git/gitlab/config/gitlab.yml
파일을 편집하십시오:production: &base http_client: tls_client_cert_file: '<클라이언트 PEM 파일 경로>' tls_client_cert_password: '<옵션 비밀번호>'
-
파일을 저장하고 GitLab을 다시 시작하십시오:
# systemd를 실행하는 시스템의 경우 sudo systemctl restart gitlab.target # SysV init을 실행하는 시스템의 경우 sudo service gitlab restart
:::EndTabs
관련 주제
문제 해결
unable to get local issuer certificate
SSL 검증이 활성화되어 있을 때 GitLab이 웹훅 엔드포인트의 SSL 인증서를 확인할 수 없다는 오류가 발생할 수 있습니다. 보통이 오류는 루트 인증서가 CAcert.org에서 확인한 신뢰할 수 있는 인증 기관에서 발급되지 않았기 때문에 발생합니다.
이 문제를 해결하려면 SSL Checker를 사용하여 오류를 확인하는 것을 고려해보세요. 중간 인증서가 누락되는 것이 확인 실패의 일반적인 원인입니다.
웹훅이 트리거되지 않음
- GitLab 16.3에서 도입된 Silent Mode에서 웹훅이 트리거되지 않음
웹훅이 트리거되지 않은 경우 다음을 확인하세요:
- 웹훅이 자동으로 비활성화되지 않았는지 확인합니다.
- GitLab 인스턴스가 Silent Mode로 설정되지 않았는지 확인합니다.