Jenkins GitHub Webhook 트리거 완벽 가이드 — push 후 즉시 빌드를 시작하는 방법

실시간 빌드를 위한 Jenkins GitHub Webhook 트리거의 유용성

코드 변경이 메인 브랜치에 반영되는 즉시 배포 파이프라인이 즉각 가동되도록 보장하는 것은 모던 프론트엔드/백엔드 배포 라이프사이클에서 가장 기분 좋은 사용자 경험입니다. GitHub Webhook 트리거는 개발자가 원격 리포지토리에 푸시(Push)나 풀 리퀘스트(Pull Request) 머지를 쏠 때, 깃허브 서버 측에서 지정된 젠킨스 URL을 향해 '새로운 코드가 투입되었으니 즉시 배포를 실행하라'는 HTTP POST 알림 신호를 쏴주는 기술입니다. 이를 연동해 두면 개발자는 배포 프로세스를 신경 쓰지 않고 오직 깃허브 창에서 머지 버튼을 누르는 코딩 흐름만 집중해도 시스템이 뒤에서 정교하게 배포를 물밑 진행해 줍니다.

폴링 부하를 예방하는 Jenkins Webhook 및 pollSCM 방식 비교

깃의 변화를 체크하는 전통적인 대안인 pollSCM 방식은 젠킨스가 정기 시간표에 맞춰 깃허브 저장소를 강제로 찔러보는 형태입니다. 이 방식은 변경 사항이 없는 평온한 상태에서도 1분 간격 등으로 저장소를 향해 무의미한 커넥션을 던지기 때문에 깃허브 API 레이트 리밋 제한에 걸려 서버가 차단당하는 위험이 있죠. 반면 Webhook은 깃허브 측에서 이벤트가 생길 때만 젠킨스를 노크하므로 양측 서버 리소스에 불기피하게 과부하가 걸리지 않고 즉각 반응합니다. 다만 젠킨스 서버 장비가 사내 폐쇄망 방화벽 뒤에 은둔하고 있다면 외부 깃허브의 웹훅 신호가 게이트웨이를 통과하지 못하므로, 퍼블릭 도메인을 열거나 ngrok 터널로 임시 매핑을 해야 통신이 트인다는 제약 조건이 존재합니다.

통합 플러그인을 활용한 Jenkins 내 Webhook 수신 허용 옵션

웹훅 신호를 맞이할 젠킨스 설정을 위해 먼저 플러그인 관리자 메뉴에서 GitHub Integration Plugin이 잘 탑재되어 있는지 검사해야 합니다. 젠킨스 기본 번들에 엮여 있어 대개 내장되어 있으나, 혹시 꺼져 있다면 설치 후 시스템을 가동합니다. 이후 Jenkins 관리 정보 내의 'Jenkins URL' 설정 주소가 외부망에서 브라우저를 띄워 접속할 수 있는 실 주소 도메인이나 공인 IP로 빈틈없이 기입되어 있는지 살핍니다. 마지막으로 타겟 Job 설정 페이지 중간의 Build Triggers 섹션으로 다이렉트 이동하여 'GitHub hook trigger for GITScm polling' 옵션을 마우스로 체크해 활성화해 두는 것이 수신부를 다지는 핵심 요령입니다.

슬래시 누락을 막는 GitHub 저장소 Webhooks 설정 요령

수신 기지를 지었다면 발신처인 깃허브 저장소 설정을 할 단계입니다. 관리 권한이 있는 저장소 Settings 탭의 Webhooks 메뉴로 진입해 'Add webhook'을 누르고 정보를 입력합니다. 이때 가장 중요하게 체크할 항목은 Payload URL 주소인데, http://내아이피:포트/github-webhook/와 같이 젠킨스 베이스 주소 뒤에 고유 수신 패스를 정확히 기입해야 합니다. 많은 주니어 개발자들이 끝부분의 슬래시 하나('/')를 빠뜨려 http://.../github-webhook으로 적는 사소한 오타를 저지릅니다. 슬래시가 빠지면 깃허브가 보낸 신호가 젠킨스 프록시 단에서 302 Moved Temporarily 리다이렉트 응답을 유발하며 튕겨 나가 빌드가 죽어버리니 반드시 끝자리 슬래시 유무를 눈으로 꼭 확인하셔야 합니다.

파이프라인 스크립트에 Jenkins GitHub Webhook 트리거 명시하기

선언적 파이프라인 형식의 Jenkinsfile 코드에서도 이 웹훅 작동 설정을 코드 한 줄로 고착화할 수 있습니다. pipeline 블록 상단에 triggers { githubPush() } 코드를 기술해 주면 됩니다. 이 명세서가 저장소 메인 브랜치에 박히면, 굳이 젠킨스 관리자 콘솔을 켜고 설정 창에서 훅 트리거 박스를 마우스로 누르는 세팅 노가다를 단행할 필요 없이, 젠킨스가 파일 정의를 흡수해 트리거 작동 환경을 프로그래밍 방식으로 자동으로 기동시켜 배포 파이프라인의 완성도를 비약적으로 높여 줍니다.

pipeline {
  agent any
  tools {
    nodejs 'NodeJS 18'
  }
  triggers {
    githubPush() // GitHub Webhook push 이벤트 감지 시 자동 빌드를 트리거하는 구문
  }
  stages {
    stage('Webhook Build Target') {
      steps {
        checkout scm
        sh 'npm ci'
        sh 'npm run build'
      }
    }
  }
}

연동 상태를 진단하고 Jenkins Webhook 빌드 검증하기

세팅이 완료되면 깃허브 웹훅 설정 하단의 Recent Deliveries 히스토리를 띄워 깃허브가 젠킨스를 향해 보낸 테스트 신호의 HTTP Response 결과 코드가 200 OK로 녹색 체크 표시를 반환하는지 육안 체크합니다. 성공 신호가 확인됐다면 실제 아무 마이너 코드나 한 줄 수정해 원격 저장소에 푸시를 감행해 봅니다. 푸시 완료 즉시 젠킨스 대시보드로 건너가서 마우스 조작을 일절 하지 않았음에도 스스로 로딩 바를 채워나가며 새로운 컴파일을 기동하는 경이로운 광경이 포착되면 실시간 자동 배포를 위한 모든 셋업 여정이 무사히 끝난 것입니다.