[Jenkins] Github Webhook과 Jenkins 연동 (완전 자동화의 꽃)

개발자가 로컬에서 기능 개발을 마치고 Github에 코드를 푸시(Push)했을 때, 사람이 젠킨스 웹 화면에 일일이 로그인해서 "Build Now(지금 빌드)" 버튼을 누른다면 그것은 진정한 의미의 자동화가 아닙니다. 반쪽짜리 CI(Continuous Integration)일 뿐이죠. 이번 [Jenkins 실무 완벽 가이드] 시리즈의 5번째 포스팅에서는 사용자의 개입을 0%로 줄이고, 코드가 커밋되는 그 즉시 자동으로 파이프라인이 굴러가게 만드는 핵심 기술, Github Webhook과 Jenkins의 완벽 연동 메커니즘에 대하여 3,000자 분량으로 아주 상세하게 딥다이브 해보겠습니다. 실무에서 가장 빈번하게 발생하는 방화벽 및 네트워크 트러블슈팅 사례까지 낱낱이 파헤쳐 드립니다.

📡 1. Webhook(웹훅)의 동작 원리 완벽 이해하기

웹훅(Webhook)은 두 개의 시스템이 비동기적으로 실시간 통신을 하기 위해 고안된 아키텍처입니다. 기존의 폴링(Polling) 방식은 젠킨스가 1분마다 Github에 "혹시 새로운 코드 올라온 거 있니?"라고 묻는 방식(Pull)이었다면, 웹훅은 Github가 능동적으로 "새로운 코드가 푸시되었으니, 지정된 젠킨스 주소로 알려줄게!"라며 HTTP POST 요청을 쏘는 방식(Push)입니다.

폴링 방식은 서버 자원을 계속 갉아먹고 변경 사항을 인지하는 데 딜레이가 생기지만, 웹훅을 사용하면 서버 자원의 낭비 없이 1초의 오차도 없이 즉각적인 이벤트(Trigger) 발생이 가능해집니다. 따라서 현대 CI/CD 파이프라인 아키텍처에서는 웹훅 방식이 절대적인 실무 표준으로 자리 잡았습니다.

⚙️ 2. Jenkins 서버 설정 (받을 준비하기)

Github가 공을 던지기(Push) 전에, 젠킨스는 그 공을 받을 글러브를 준비해야 합니다. 이를 위해 연동할 잡(Job/Pipeline)에 트리거를 개방해주어야 합니다.

1. Jenkins 대시보드에서 연동하려는 Freestyle Project 혹은 Pipeline Job을 클릭하고 좌측의 [구성(Configure)] 메뉴로 들어갑니다.
2. 스크롤을 내려 [빌드 유발(Build Triggers)] 섹션을 찾습니다.
3. 여러 체크박스 중 `GitHub hook trigger for GITScm polling` 항목에 체크합니다.
4. 만약 이 항목이 보이지 않는다면, 젠킨스 시스템 관리에 가서 GitHub Integration Plugin이 제대로 설치되어 있는지 확인해야 합니다.
5. 상단의 [소스 코드 관리(Source Code Management)] 탭에서 Git을 선택하고, 대상 Github Repository 주소(예: `https://github.com/my-org/my-repo.git`)와 접근 권한(Credentials), 타겟 브랜치(`*/main`)가 정확히 매핑되어 있는지 재확인한 뒤 저장합니다.

이제 젠킨스는 외부에서 들어오는 특정 HTTP POST 요청을 받아들여 파이프라인을 구동시킬 완벽한 준비가 끝났습니다.

🐙 3. Github Repository 설정 (공 던지기)

이제 Github 측에 젠킨스의 주소를 알려줄 차례입니다.

1. 연동을 원하는 Github Repository 페이지로 이동하여 상단의 [Settings] 탭을 클릭합니다.
2. 좌측 사이드 메뉴에서 [Webhooks]를 클릭하고 우측 상단의 [Add webhook] 버튼을 누릅니다.
3. Payload URL (가장 중요): 젠킨스 서버의 주소를 입력해야 합니다. 형식은 반드시 http://[젠킨스_IP_혹은_도메인]:[포트번호]/github-webhook/ 이어야 합니다. (예: http://ci.mycompany.com:8080/github-webhook/) 주의: 맨 마지막에 슬래시(/)를 빼먹으면 Github가 302 Redirection 에러를 뱉으며 연동에 실패하므로 각별히 주의해야 합니다!
4. Content type: application/x-www-form-urlencoded 대신 반드시 application/json을 선택합니다. 젠킨스 플러그인이 JSON 포맷의 페이로드를 해석하기 때문입니다.
5. Secret: (선택 사항) 통신의 보안을 위해 해시 키를 걸어두는 곳이나, 기본적인 토이 프로젝트에서는 비워두어도 무방합니다.
6. Which events would you like to trigger this webhook? (이벤트 지정): Just the push event를 선택하면 누군가 코드를 Push 할 때만 빌드가 돕니다. 만약 Pull Request(PR)가 생성될 때나 태그(Tag)가 생성될 때 빌드를 돌리고 싶다면 Let me select individual events.를 선택하여 커스텀 할 수 있습니다.
7. 하단의 [Add webhook]을 눌러 저장합니다.

⚠️ 4. 실무 트러블슈팅: 초록색 체크가 안 뜨고 빨간색(Red Cross)이 떠요!

저장을 누르는 순간 Github는 여러분의 Payload URL로 테스트 Ping(Ping Payload)을 전송합니다. 정상적이라면 Payload URL 옆에 영롱한 초록색 체크 아이콘(✅)이 떠야 하지만, 많은 초보자들이 빨간색 경고 아이콘(❌)을 마주하고 좌절합니다. 실무에서 겪는 99%의 원인은 다음과 같습니다.

원인 1. 사설 IP(Private IP) 혹은 Localhost를 입력한 경우:
Github는 미국의 거대한 클라우드 서버에 있습니다. 만약 Payload URL에 http://localhost:8080 이나 공유기 내부망 주소인 http://192.168.0.x를 입력했다면, 미국에 있는 Github 서버가 여러분의 방구석 컴퓨터를 찾아갈 방법이 전혀 없습니다. 반드시 공인 IP(Public IP)나 퍼블릭 도메인을 입력해야 합니다.

해결책 (Ngrok 활용):
만약 비싼 공인 IP나 도메인이 없는 개인 로컬 환경이라면 어떻게 해야 할까요? 개발자들의 구세주인 Ngrok(엔그록)을 사용하면 됩니다. Ngrok은 로컬 호스트를 외부에서 접속 가능한 임시 퍼블릭 URL로 터널링해주는 도구입니다. 로컬 터미널에 ngrok http 8080을 치면 https://ab12-cd34.ngrok.io 같은 임시 주소가 생성되며, 이를 Payload URL에 넣으면 완벽하게 연동됩니다.

원인 2. 사내망 방화벽(Inbound Rules)에 막힌 경우:
AWS EC2에 올렸는데도 안 된다면? EC2의 Security Group(보안 그룹) 인바운드 규칙에서 8080 포트가 Github의 IP 대역폭에 대해 개방되어 있는지 확인해야 합니다. 폐쇄적인 기업망의 경우 네트워크 보안팀에 "Github Webhook IP 대역에 대해 젠킨스 서버 포트 방화벽 오픈"을 요청해야만 해결됩니다.

🎯 5. 최종 연동 테스트 및 확인

방화벽 문제까지 모두 해결하고 초록색 체크를 확인했다면, 이제 로컬 IDE(VSCode, IntelliJ 등)를 열어 소스 코드의 README.md 파일에 점 하나를 찍고 git add . -> git commit -m "Webhook test" -> git push origin main 명령어를 날려보십시오.

여러분이 젠킨스 화면에 로그인하여 아무런 클릭을 하지 않았음에도 불구하고, 푸시 후 1~2초 뒤에 젠킨스의 Build History에 #1 빌드가 빙글빙글 돌며 스스로 시작되는 마법을 목격하실 수 있습니다. 빌드 원인(Cause)을 살펴보면 "Started by GitHub push by (작성자 계정명)" 이라는 문구가 명확하게 찍혀 있을 것입니다.

지금까지 CI/CD 자동화의 화룡점정이라 할 수 있는 Github Webhook 구성 및 연동, 그리고 트러블슈팅 방안에 대해 3,000자에 가까운 밀도 높은 내용으로 살펴보았습니다. 이제 코드를 짜고 푸시하기만 하면 인프라가 스스로 노동을 하는 진정한 DevOps 환경이 갖추어졌습니다. 이어지는 6단계 포스팅에서는 이렇게 연동된 환경에서 실제로 코드를 컴파일하고 스크립트를 실행하는 가장 기본 단위인 Freestyle Project의 세부 구축 방법에 대해 알아보겠습니다.