Git 연동 & Webhook, 브랜치/PR 트리거 설계

Git 저장소에서 발생하는 이벤트를 Jenkins로 전달하려면, 먼저 Git 저장소에 Webhook을 등록해 두어야 합니다.
Webhook은 push, pull_request, PR closed 등의 이벤트가 발생했을 때 미리 지정한 URL로 HTTP 요청을 보내주는 기능입니다. Jenkins에서는 이 요청을 받아 조건에 맞는 이벤트일 시 제작해둔 파이프라인을 수행합니다. 이 글에서는 Git과 Jenkins를 Webhook으로 연결하고, "특정 브랜치에 대한 PR이 merged되어 closed 되었을 때만" Jenkins 파이프라인을 트리거하는 방법을 정리해 보겠습니다.

Webhook과 Trigger(트리거)

Webhook은 Git의 이벤트인 push나 pull_request 등이 발생하면 지정된 URL로 HTTP POST 요청을 보내주는 기능입니다. 그리고 Jenkins에서는 Git이 보낸 내용을 보고 조건 검사를 거쳐 지정해둔 빌드를 실행하는 것이 Trigger(트리거)라고 합니다.

Webhook의 주요 JSONPath 컬럼

• $.action : Git 저장소의 상태 변화 값입니다.
  • opened : PR이 생성되었을 때 발생
  • closed : PR이 닫혔을 때 발생. Merge 성공(true) 또는 수동(false) 두 상황 모두 Webhook이 발생합니다.
  • synchronize : PR이 open된 상태에서 head에 새 커밋을 추가하거나 강제 push 시 발생하는 Webhook. 테스트를 재실행할 때 많이 사용합니다.
• $.pull_request.merged : PR이 실제로 성공했는지 확인하는 플래그 값
  • PR이 실제 merge(병합)된 경우만 true로, 빌드 트리거 핵심 조건입니다.
  • PR이 발생하고, closed $.action이 발생해야 이 값으로 배포 빌드 트리거 여부를 판단합니다.
• $.pull_request.base.ref : PR의 대상 브랜치. 즉, merge될 곳을 나타내는 값입니다.
• $.ref : push 이벤트가 일어날 때 나오는 값이며, push 이벤트를 직접 트리거할 때 사용합니다.
  

주요 트리거 유형

트리거에는 Webhook을 처리하는 폴링 방식과 이벤트 기반으로 나누어져 있습니다.

• 폴링 방식(Github Hook Trigger for GITScm Polling)은 Jenkins에서 지원하는 GitHub 전용 플러그인으로 간단한 push 이벤트에 적합합니다.
  • 엔드포인트 : 자동 /github-webhook/ (토큰 불필요)
  • push/PR을 자동 처리하고, Jenkins에서 SCM Branches에 push 했을 때 빌드하고 싶은 브랜치를 작성하면 됩니다.
  • merged=true 같은 분기를 설정할 수 없으며, 사용자가 push를 조심해야 하는 단점이 있습니다.
• 이벤트 기반(Generic Webhook Trigger)는 Jenkins에서 범용 플러그인을 사용하며 Webhook에서 전송하는 JSONPath를 좀 더 세밀하게 필터링하여 트리거 설정을 할 수 있습니다.
  • 엔드포인트: /generic-webhook-trigger/invoke?token=YOUR_TOKEN
  • $.action="closed"(PR이 닫히고) 일 때, $.pull_request.merged=true(merge가 성공적이면 실행) 같은 Webhook 요청에 대해서만 빌드할 수 있도록 처리할 수 있습니다.

Webhook 설정 방법

본글에서는 이벤트 기반(Generic Webhook Trigger)로 진행하겠습니다.

1. Jenkins Trigger 플러그인 설치

먼저 Setting > Plugins > Available plugins 클릭하여 Generic Webhook Trigger Plugin을 검색하여 설치해줍니다.

설치하면 사진과 같이 Installed plugins에서 조회할 수 있습니다.

2. Jenkins 파이프라인 설정

1. New Item을 클릭하여 파이프라인 이름을 설정해준 뒤 Pipeline을 클릭하고 OK를 눌러줍니다.
   

2. Trigger에서 Generic Webhook Trigger를 체크해줍니다.
   

   만약, 해당 항목이 없다면 플러그인 설치가 제대로 안 된겁니다.

3. 체크했다면 다음과 같은 메뉴가 나올 것인데 Post content parameters에서 +추가 버튼을 클릭하여 다음과 같이 3개의 항목을 설정해줍니다.

• Git 저장소 상태 변화값 설정
  • Variable : ACTION
  • Expression : $.action
  • JSONPath 체크
• Git 저장소 상태 변화값 설정
  • Variable : MERGED
  • Expression : $.pull_request.merged
  • JSONPath 체크
• Git 저장소 상태 변화값 설정
  • Variable : BRANCH
  • Expression : $.pull_request.base.ref
  • JSONPath 체크

4. Git Webhook 엔드포인트에 사용할 Token 값을 지정해 줍니다.

5. 마지막으로 Optional filter에 표현식을 작성해줍니다.

• Expression : (?=.*closed)(?=.*true)(?=.*develop).*
  • action=="closed" : PR closed 상태
  • merged==true : 실제 merge 성공
  • branch=.develop.* : 브랜치명이 develop으로 시작하는 경우 (정규식)
• Text : $ACTION $MERGED $BRANCH
  • Expression의 RegEX 정규식과 매칭되는지 확인하기 위한 테스트 문자열 생성하는 역할

6. 아래 Pipeline의 스크립트를 작성하고, 저장해주면 Jenkins 설정 끝입니다.

3. GitHub Webhook 설정

배포 Repository > Settings > Webhooks > Add webhook 클릭하여 다음과 같이 작성

• Payload URL : http://<배포서버 주소>:9090/generic-webhook-trigger/invoke?token=<Jenkins에서 작성한 토큰>
• Content type : application/json
• Let me select individual events. 체크 후 Pull requests 체크 및 모든 이벤트 체크 해제

4. 테스트

테스트 방법은 간단합니다. 테스트 PR을 생성해 develop 브랜치로 merge 하세요. 그리고 Jenkins에서 빌드되는지 확인하세요. 만약 아무런 반응이 없다면 GitHub Webhook 설정했던 곳으로 들어가 Recent Deliveries를 확인해 보세요.

• Response 200응답이 아닌 경우 : Webhook과 Jenkins Generic Webhook Trigger 설정이 잘못된 경우입니다. 토큰값이 파이프라인 작성과 Webhook이 동일한지 확인하고, IP주소와 Jenkins 포트가 맞는지 재확인하세요.
• Response 200응답인 경우 : Body에서 action, pull_request.merged, pull_request.base.ref이 작성해둔 값이 closed, true, develop인지 확인하세요.

  저는 빈 문자열 하나 잘못 설정해서 1시간 동안 찾았습니다...

이제 GitHub Webhook과 Jenkins Generic Webhook Trigger를 연동해 특정 브랜치(develop)로의 PR merged 시에만 정확히 파이프라인을 트리거하는 설정이 완료되었습니다. 위 내용들은 트리거 분기의 기초 작업이라 보시면 됩니다. 여기서 이제 Git의 태그를 활용하는 방식이라던가, 모니터링, 보안이 들어가면 CI/CD 파이프라인이 더욱 정교해집니다. 또한 스크립트에서도 깃 태그 방식을 이용한 Docker 이미지 태그 설정 버전 관리, Docker 서버 용량 관리 등을 신경써야 하기 때문에 한 번 설계 시 전체 워크플로우를 고려해야 합니다.