웹훅

세부정보: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

웹훅(Webhooks)은 사용자가 정의하는 사용자 지정 HTTP 콜백(callbacks)입니다. 보통 이벤트(예: 리포지토리에 코드를 푸시하거나 이슈에 댓글을 게시하는 것과 같은)에 의해 트리거됩니다. 이벤트가 발생하면 소스 애플리케이션은 웹훅에 구성된 URI로 HTTP 요청을 합니다. 취해야 할 조치는 무엇이든 될 수 있습니다. 예를 들어 웹훅을 사용하여:

이벤트가 발생할 때 GitLab은 특정 이벤트에 대해 POST 요청과 데이터를 웹훅 URL로 보냅니다.

보통 새로운 코드가 푸시되거나 새로운 이슈가 생성될 때와 같은 이벤트가 발생할 때 프로젝트나 그룹에서 웹훅 URL을 트리거하도록 구성할 수 있습니다. 웹훅은 특정 이벤트에 대해 수신하며 GitLab은 웹훅 URL로 데이터를 담아 POST 요청을 보냅니다.

일반적으로 귀하의 요구에 따라 정보를 수신하기 위해 귀하의 웹훅 수신기(webhook receiver)를 설정하고 다른 앱으로 전송합니다. 프로젝트마다 Slack 알림을 보내기 위한 내장 수신기가 있습니다.

GitLab.com은 프로젝트 및 그룹 당 웹훅 및 웹훅 크기의 최대 개수와 웹훅 호출의 수에 대한 웹훅 제한을 적용합니다.

그룹 웹훅

세부정보: Tier: Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

그룹 웹훅은 그룹 및 하위 그룹의 모든 프로젝트에서 발생하는 이벤트에 의해 트리거되는 이벤트로 구성될 수 있습니다. 그룹과 프로젝트 모두 동일한 웹훅을 구성하는 경우, 해당 프로젝트의 이벤트에 의해 둘 다 트리거됩니다.

그룹 웹훅은 또한 그룹에 특정한 이벤트를 수신하기 위해 구성될 수 있는데, 이는 다음과 같습니다.

GitLab에서 웹훅 구성

프로젝트나 그룹에 웹훅을 구성하려면 다음을 수행하세요:

  1. 프로젝트나 그룹에서 왼쪽 사이드바에서 Settings > Webhooks을 선택합니다.
  2. 새 웹훅 추가를 선택합니다.
  3. URL에 웹훅 엔드포인트의 URL을 입력합니다. URL에 하나 이상의 특수 문자가 포함되어 있는 경우 URL은 퍼센트 인코딩이 되어야 합니다.
  4. Secret token페이로드를 유효화하기 위한 secret token을 입력합니다.
  5. Trigger 섹션에서 웹훅을 트리거하기 위한 이벤트를 선택합니다.
  6. 선택 사항. SSL 검증을 비활성화하려면 SSL 검증 활성화 확인란을 선택해제합니다.
  7. 웹훅 추가를 선택합니다.

웹훅 URL의 민감한 부분 가리기

웹훅 URL의 민감한 부분을 정의하고 마스킹된 값으로 교체하여 웹훅이 실행될 때 여러 차례 정의할 수 있습니다. 민감한 부분은 기록되지 않으며 데이터베이스에 저장된 채 암호화됩니다.

웹훅 URL의 민감한 부분을 가리려면 다음을 수행하세요:

  1. 왼쪽 사이드바에서 프로젝트나 그룹에서 Settings > Webhooks을 선택합니다.
  2. URL에 완전한 웹훅 URL을 입력합니다.
  3. URL 일부 가리기를 선택합니다.
  4. URL의 민감한 부분에 가리려는 부분을 입력합니다.
  5. UI에서의 모습에 마스킹할 값이 입력됩니다.

각 웹훅에 대해 민감한 부분을 내삽(interpolate)하려면 url_variables을 사용하세요. 예를 들어, 웹훅에 다음과 같은 URL이 있다면:

https://{subdomain}.example.com/{path}?key={value}

다음과 같은 변수를 정의해야 합니다:

  • subdomain
  • path
  • value

변수 이름은 소문자 (a-z), 숫자 (0-9), 또는 밑줄(_)만 포함할 수 있습니다. URL 변수는 REST API를 사용하여 직접 정의할 수 있습니다.

사용자 정의 웹훅 템플릿

플래그: 자체 관리형 GitLab에서는 기본적으로 이 기능이 사용 가능합니다. 특성을 숨기려면 관리자가 custom_webhook_template이라는 플래그를 비활성화할 수 있습니다. GitLab.com 및 전용 GitLab에서는 이 기능을 사용할 수 있습니다.

웹훅 구성에서 사용자 정의 페이로드 템플릿을 설정할 수 있습니다. 요청 본문은 현재 이벤트의 데이터로부터 템플릿에서 렌더링됩니다. 템플릿은 유효한 JSON으로 렌더링하여야 합니다.

모든 이벤트의 페이로드에서 {{build_name}}과 같은 필드를 사용할 수 있습니다. 작업 이벤트에는 {{build_name}}이 있고 배포 이벤트에는 {{deployable_url}}이 있습니다. 객체에 중첩된 속성에 액세스하려면 .로 구분된 경로 세그먼트를 지정하세요. 예를 들면:

다음과 같은 사용자 정의 페이로드 템플릿이 주어졌다면:

{
  "event": "{{object_kind}}",
  "project_name": "{{project.name}}"
}

이 템플릿과 push 이벤트를 결합한 이 요청 페이로드가 생성됩니다:

{
  "event": "push",
  "project_name": "Example"
}

웹훅 수신기 엔드포인트 구성

웹훅 수신기 엔드포인트는 빠르고 안정적이어야 합니다. 느립니다. 불안정한 수신기는 자동으로 비활성화될 수 있으며 시스템 신뢰성을 보장합니다. 실패한 웹훅은 중복 이벤트를 유발할 수 있습니다.

엔드포인트는 다음 모범 사례를 따라야 합니다:

  • 200 또는 201 상태 응답으로 빠르게 응답하세요. 동일한 요청에서 웹훅을 처리하는 중요한 작업을 피하세요. 대신, 수신된 웹훅을 처리하는 대기열을 구현하세요. 웹훅 수신기는 시간 초과 제한 이전에 응답하지 않으면 GitLab.com에서 자동으로 비활성화될 수 있습니다.
  • 중복 이벤트를 처리할 준비를 하세요. 일부 상황에서 동일한 이벤트가 두 번 전송될 수 있습니다. 이 문제를 완화하려면 엔드포인트가 신뢰할 수 있게 빠르고 안정적이도록 보장하세요.
  • 응답 헤더와 본문을 최소화하세요. GitLab은 응답 헤더나 본문을 검사하지 않습니다. 문제를 진단하기 위해 후에 로그에서 확인할 수 있도록 GitLab은 이러한 정보를 저장합니다. 반환되는 헤더의 수와 크기를 제한해야 합니다. 웹훅 요청에 빈 본문으로 응답할 수도 있습니다.
  • 클라이언트 오류 상태 응답(범위가 4xx인)만 반환하여 웹훅이 잘못 구성되었음을 나타내세요. 이 범위의 응답은 웹훅이 자동으로 비활성화될 수 있습니다. 예를 들어, 수신기가 푸시 이벤트만 지원하는 경우 이슈 페이로드가 전송되면 400을 반환할 수 있으며, 이는 훅이 잘못 설정되었다는 표시입니다. 또는 인식되지 않은 이벤트 페이로드를 무시할 수 있습니다.
  • 이벤트가 처리된 경우 절대 500 서버 오류 상태 응답을 반환하지 마세요. 이러한 응답은 웹훅이 자동으로 비활성화될 수 있습니다.
  • 유효하지 않은 HTTP 응답은 실패한 요청으로 간주됩니다.

웹훅 타임아웃 한도

GitLab.com의 웹훅 타임아웃 한도는 10초입니다. 자체 관리형 GitLab에서는 관리자가 웹훅 타임아웃 한도를 변경할 수 있습니다.

자동으로 비활성화된 웹훅

  • 프로젝트 웹훅용으로 소개되었습니다. GitLab 13.12에서 web_hooks_disable_failed라는 플래그와 함께 소개됨. 기본적으로 비활성화되어 있습니다.
  • GitLab 15.7의 프로젝트 웹훅을 대상으로 한 일반 사용 가능한 항목. 플래그 web_hooks_disable_failed가 제거되었습니다.
  • 그룹 웹훅을 대상으로하는 GitLab 15.10의 소개
  • GitLab 15.10에서 자체 관리형에서 비활성화됨. auto_disabling_web_hooks라는 플래그로 함께 소개되었습니다.

플래그: 자체 관리형 GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용하려면 관리자가 auto_disabling_web_hooks라는 플래그를 사용할 수 있도록 설정할 수 있습니다. GitLab.com에서 이 기능을 사용할 수 있습니다. 전용 GitLab에서는 이 기능을 사용할 수 없습니다.

연속 네 번의 실패한 프로젝트 또는 그룹 웹훅은 자동으로 비활성화됩니다.

응답 코드가 5xx 범위에 있는 웹훅 또는 타임아웃 또는 기타 HTTP 오류가 발생한 웹훅은 일시적으로 실패했다고 이해되며 일시적으로 비활성화됩니다. 이러한 웹훅은 초기에 1분 동안 비활성화되며, 각 연속적인 실패마다 최대 24시간까지 연장됩니다.

응답 코드가 4xx 범위에 있는 웹훅은 잘못 구성되었다고 이해되며 사용자가 수동으로 웹훅을 다시 활성화할 때까지 영구적으로 비활성화됩니다.

비활성화된 웹훅 다시 활성화하기

  • GitLab 15.2에 도입되었으며 기본적으로 비활성화된 webhooks_failed_callout라는 플래그가 함께 도입되었습니다.
  • GitLab 15.7에서 일반적으로 이용 가능. webhooks_failed_callout 기능 플래그가 제거되었습니다.

웹훅이 실패하면 수정 페이지 상단에 배너가 표시되어 해당 웹훅이 왜 비활성화되었는지와 자동으로 다시 활성화되는 시기에 대해 설명합니다. 예를 들어:

실패한 웹훅에 대한 배너, 연결에 실패했음을 경고하고 60분 후에 다시 시도한다는 경고

실패한 웹훅의 경우 오류 배너가 표시됩니다:

실패한 웹훅의 오류 상태를 보여주고 다시 활성화하는 방법을 설명하는 오류 배너

실패한 또는 실패한 웹훅을 다시 활성화하려면 테스트 요청을 보냅니다. 테스트 요청이 성공하면 웹훅이 다시 활성화됩니다.

웹훅 테스트

웹훅을 수동으로 트리거하여 올바르게 작동하는지 확인할 수 있습니다. 또한 비활성화된 웹훅을 다시 활성화하려면 테스트 요청을 보낼 수 있습니다.

예를 들어, push 이벤트를 테스트하려면 프로젝트에 적어도 하나의 커밋이 있어야 합니다. 웹훅은 이 커밋을 사용합니다.

참고: 프로젝트 및 그룹 웹훅의 일부 이벤트에 대해 테스트를 지원하지 않습니다. 더 많은 정보는 issue 379201을 참조하십시오.

필수 조건:

  • 프로젝트 웹훅을 테스트하려면 프로젝트에 적어도 Maintainer 역할이 있어야 합니다.
  • 그룹 웹훅을 테스트하려면 그룹에 Owner 역할이 있어야 합니다.

웹훅을 테스트하려면:

  1. 왼쪽 사이드바에서 프로젝트 또는 그룹을 선택한 후 설정 > 웹훅을 선택합니다.
  2. 구성된 웹훅 목록으로 스크롤합니다.
  3. 테스트 드롭다운 목록에서 테스트할 이벤트 유형을 선택합니다.

또한 해당 웹훅의 수정 페이지에서 웹훅을 테스트할 수 있습니다.

웹훅 테스트

예제 웹훅 리시버 생성

GitLab 웹훅이 작동하는지 테스트하려면 콘솔 세션에서 실행되는 echo 스크립트를 사용할 수 있습니다. 다음 스크립트가 작동하려면 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. 테스트를 선택합니다. 콘솔에 다음과 유사한 내용이 표시되어야 합니다:

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

참고: 이 수신기를 추가하려면 로컬 네트워크로의 요청 허용이 필요할 수 있습니다.

시크릿 토큰 사용하여 페이로드 유효성 검사

수신된 페이로드를 유효성 검사하기 위해 시크릿 토큰을 지정할 수 있습니다. 토큰은 X-Gitlab-Token HTTP 헤더에 함께 웹훅 요청과 함께 보내집니다. 웹훅 엔드포인트는 요청이 정당한지를 확인하기 위해 토큰을 검사할 수 있습니다.

브랜치별 push 이벤트 필터링

브랜치별로 push 이벤트를 필터링할 수 있습니다. 웹훅 엔드포인트로 보내는 push 이벤트를 필터링하는 데 사용할 수 있는 옵션 중 하나를 사용할 수 있습니다:

  • 모든 브랜치: 모든 브랜치의 push 이벤트.
  • 와일드카드 패턴: 와일드카드 패턴과 일치하는 브랜치(예: *-stable 또는 production/*)의 push 이벤트.
  • 정규 표현식: 정규 표현식(regex)과 일치하는 브랜치의 push 이벤트. 정규 표현식 패턴은 RE2 syntax를 따라야 합니다. 예를 들어, main을 제외하려면 다음과 같이 사용할 수 있습니다:

    \b(?:m(?!ain\b)|ma(?!in\b)|mai(?!n\b)|[a-l]|[n-z])\w*|\b\w{1,3}\b|\W+
    

프로젝트 또는 그룹의 브랜치 필터링을 구성하려면 GitLab에서 웹훅을 구성을 참조하세요.

이미지 URL이 Webhook 본문에 표시되는 방법

Webhook의 본문에서 상대적 이미지 참조는 절대 URL을 사용하도록 다시 작성됩니다. 예를 들어, 이미지, 병합 요청, 코멘트 또는 위키 페이지에 다음 이미지 참조가 포함되어 있다면:

![이미지](/uploads/$sha/image.png)

만약:

  • GitLab이 gitlab.example.com에 설치되어 있고,
  • 프로젝트가 example-group/example-project에 있는 경우,

다음과 같이 웹훅 본문에서 참조가 다시 작성됩니다:

![이미지](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png)

이미지 URL은 다음과 같은 경우에는 다시 작성되지 않습니다:

  • 이미 HTTP, HTTPS 또는 프로토콜 관련 URL을 가리키고 있는 경우.
  • 링크 라벨과 같은 고급 Markdown 기능을 사용하는 경우.

이벤트

웹훅을 위한 지원되는 이벤트에 대한 자세한 정보는 웹훅 이벤트를 참조하세요.

전달 헤더

  • X-Gitlab-Event-UUID 헤더는 GitLab 14.8에 도입되었습니다.
  • X-Gitlab-Instance 헤더는 GitLab 15.5에 도입되었습니다.
  • X-Gitlab-Webhook-UUID 헤더는 GitLab 16.2에 도입되었습니다.

엔드포인트로의 웹훅 요청은 다음 헤더를 포함합니다:

헤더 설명 예시
User-Agent 형식이 "Gitlab/<VERSION>"인 사용자 에이전트. "GitLab/15.5.0-pre"
X-Gitlab-Instance 웹훅을 보낸 GitLab 인스턴스의 호스트명. "https://gitlab.com"
X-Gitlab-Webhook-UUID 웹훅마다 고유한 ID. "02affd2d-2cba-4033-917d-ec22d5dc4b38"
X-Gitlab-Event 웹훅 유형의 이름. 이벤트 유형에 해당하지만 "<EVENT> Hook" 형식으로 표시됩니다. "Push Hook"
X-Gitlab-Event-UUID 재귀적이지 않은 웹훅마다 고유한 ID. GitLab 인스턴스에 도달한 이전 웹훅으로 인해 트리거된 경우 해당 웹훅은 재귀적입니다. 재귀적인 웹훅은 이 헤더에 대해 동일한 값이 있습니다. "13792a34-cac6-4fda-95a8-c58e00a3954e"

웹훅 개발

기존의 HTTPS 엔드포인트나 웹훅 설정을 위한 URL이 없는 경우 서버에 배포해야 합니다. 이 HTTPS 엔드포인트는 구성에서 사용됩니다. GitLab 웹훅을 개발하고 페이로드를 캡처하기 위해 다음을 사용할 수 있습니다:

공개 웹훅 검사 및 테스트 도구

공개 도구를 사용하여 웹훅 페이로드를 검사하고 테스트할 수 있습니다. 이러한 도구는 HTTP 요청에 대한 캐치올 엔드포인트로 작용하며 200 OK HTTP 상태 코드로 응답합니다. 이러한 페이로드를 사용하여 웹훅 서비스를 개발할 수 있습니다.

이러한 도구를 사용할 때 민감한 데이터가 외부 도구로 전송될 수 있으므로 주의해야 합니다. 이러한 도구에 대해 테스트 토큰을 사용하고 제3자에게 무단으로 전송된 비밀을 회전해야 합니다.

이러한 공개 도구에는 다음이 포함됩니다:

  • Beeceptor: 임시 HTTPS 엔드포인트를 생성하고 들어오는 페이로드를 검사하는 데 사용
  • Webhook.site: 들어오는 페이로드를 검토하는 데 사용
  • Webhook Tester: 들어오는 페이로드를 검사하고 디버그하는 데 사용

GitLab Development Kit (GDK)

더 안전한 개발 환경을 위해 GitLab Development Kit (GDK)를 사용하여 로컬에서 GitLab 웹훅을 개발할 수 있습니다. GDK를 사용하면 로컬 GitLab 인스턴스에서 로컬 기계에서 실행 중인 웹훅 수신기로 웹훅을 보낼 수 있습니다. 이 방법을 사용하려면 GDK를 설치하고 구성해야 합니다.

GitLab 설정에서 최근에 트리거된 웹훅 페이로드

GitLab 설정에서 최근에 트리거된 웹훅 페이로드를 확인할 수 있습니다. 각 웹훅 이벤트에 대해 데이터 GitLab이 웹훅 엔드포인트로부터 보내고 받는 정보를 포함하는 상세 페이지가 있습니다.

상호 TLS를 지원하는 웹훅 구성

자세한 내용: Offering: Self-managed, GitLab Dedicated

전제 조건:

  • GitLab 관리자여야 합니다.

상호 TLS를 지원하도록 웹훅을 구성하기 위해 PEM 형식의 클라이언트 인증서를 구성할 수 있습니다. 이 인증서는 전역적으로 설정되며 TLS 핸드셰이크 중에 서버에 제시됩니다. 또한 인증서는 PEM 패스프레이즈로 보호할 수도 있습니다.

인증서를 구성하려면 아래 지시 사항을 따르세요.

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    gitlab_rails['http_client']['tls_client_cert_file'] = '<클라이언트 PEM 파일 경로>'
    gitlab_rails['http_client']['tls_client_cert_password'] = '<선택적인 패스워드>'
    
  2. 파일을 저장한 후 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Docker
  1. 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'] = '<선택적인 패스워드>'
    
  2. 파일을 저장한 후 GitLab을 다시 시작합니다:

    docker compose up -d
    
Self-compiled (source)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

    production: &base
      http_client:
        tls_client_cert_file: '<클라이언트 PEM 파일 경로>'
        tls_client_cert_password: '<선택적인 패스워드>'
    
  2. 파일을 저장한 후 GitLab을 다시 시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init을 실행 중인 시스템의 경우
    sudo service gitlab restart
    

관련 주제

문제 해결

  • GitLab 15.3에서 도입된 그룹 웹훅의 최근 이벤트 소개.

GitLab은 각 웹훅 요청의 이력을 기록합니다. 최근 이벤트 테이블에서 최근 2일간의 요청을 확인할 수 있습니다.

전제 조건:

  • 프로젝트 웹훅을 문제 해결하려면 프로젝트의 유지자 역할을 최소한으로 가져야 합니다.
  • 그룹 웹훅을 문제 해결하려면 그룹의 소유자 역할을 가져야 합니다.

테이블 보기:

  1. 프로젝트 또는 그룹에서 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
  2. 웹훅으로 스크롤합니다.
  3. 자동 비활성화된 웹훅에는 다음과 같은 뱃지가 있습니다:

    • 구성 오류로 수동으로 다시 활성화해야 하는 경우 연결에 실패.
    • 일시적으로 비활성화되어 타임아웃 제한 시간이 경과하면 자동으로 다시 활성화되는 경우 연결에 실패함.

    실패한 웹훅에 대한 뱃지들

  4. 보려는 웹훅의 편집을 선택합니다.

테이블에는 각 요청에 대한 다음과 같은 세부 정보가 포함됩니다:

  • HTTP 상태 코드 (200-299 코드에 대한 녹색, 그 외에 대한 빨간색, 및 실패한 전달에 대한 내부 오류)
  • 트리거된 이벤트
  • 요청의 경과 시간
  • 요청이 이루어진 상대적인 시간

최근 전송

각 웹훅 이벤트에 해당하는 세부 정보 페이지가 있습니다. 이 페이지에서 GitLab이 보냈던 데이터(요청 헤더 및 본문)와 받은 데이터(응답 헤더 및 본문)의 세부 정보가 포함되어 있습니다. 세부 정보 페이지를 보려면 웹훅 이벤트의 세부 정보 보기를 선택합니다.

동일한 데이터로 전송을 다시 하려면 요청 다시 보내기를 선택합니다.

참고: 웹훅의 URL 또는 시크릿 토큰을 업데이트하면 데이터가 새 주소로 전달됩니다.

로컬 발급자 인증서를 가져 올 수 없음

SSL 검증이 활성화된 경우, GitLab이 웹훅 엔드포인트의 SSL 인증서를 확인할 수 없다는 오류가 발생할 수 있습니다. 일반적으로, 이 오류는 루트 인증서가 CAcert.org에서 정한 신뢰할 수 있는 인증 기관에 의해 발급되지 않아 발생합니다.

그렇지 않은 경우 SSL Checker를 사용하여 결함을 확인해보십시오. 중간 인증서의 누락은 검증 실패의 일반적인 원인입니다.

웹훅이 실패하거나 여러 웹훅 요청이 트리거됨

여러 웹훅 요청을 받는 경우 웹훅이 타임아웃되었을 수 있습니다.

웹훅이 트리거되지 않음

  • Silent Mode에서 웹훅이 작동하지 않음 소개 in GitLab 16.3.

웹훅이 트리거되지 않는 경우 확인해야 할 사항: