GitHub Webhook 자동 빌드 트리거링

코드를 push할 때마다 Jenkins에 들어가서 수동으로 빌드를 실행하고 있진 않으신가요?

GitHub Webhook 은 코드 변경(push, PR 등) 이벤트가 발생하면 Jenkins에 HTTP POST 요청을 보내 파이프라인을 자동으로 트리거하는 기능입니다. Multibranch Pipeline 과 결합하면 브랜치별로 파이프라인이 자동 생성/실행됩니다.

코드 Push → GitHub Webhook → Jenkins 빌드 트리거 → 빌드/테스트/배포

1. GitHub Webhook 설정

방화벽 허용

GitHub가 Webhook 요청을 Jenkins 서버로 보내려면, Jenkins 서버의 방화벽에서 GitHub의 Webhook IP 대역을 허용해야 합니다. 방화벽에서 차단되면 Webhook 요청 자체가 Jenkins에 도달하지 않습니다.

GitHub의 공식 Webhook IP 대역은 https://api.github.com/meta의 hooks 항목에서 확인할 수 있습니다.

# GitHub Webhook IP 대역 확인
curl -s https://api.github.com/meta | jq '.hooks'

리포지토리 Webhook 등록

Webhook은 리포지토리 단위 또는 Organization 단위로 설정할 수 있습니다. 아래는 리포지토리 단위 설정 방법입니다.

1. GitHub 리포지토리 > Settings > Webhooks > Add webhook
2. Webhook 설정값 입력:

3. 이벤트 선택:

2. Jenkins 필수 플러그인 설치

Generic Webhook Trigger

Jenkins가 GitHub Webhook 요청을 수신하여 자동으로 빌드를 실행하기 위해 필요합니다.

• ** 설치 경로:** Manage Jenkins > Plugins > Available Plugins > "Generic Webhook Trigger" 검색 및 설치

이 플러그인이 설치되어 있지 않으면 파이프라인에서 Webhook 관련 설정 옵션이 표시되지 않습니다. 반드시 먼저 설치해야 합니다.

GitHub Branch Source

Multibranch Pipeline에서 GitHub 리포지토리를 자동으로 스캔하고, 브랜치별 파이프라인을 자동 생성하기 위해 필요합니다.

• ** 설치 경로:** Manage Jenkins > Plugins > Available Plugins > "GitHub Branch Source" 검색 및 설치

단일 Pipeline Job에서 Webhook만 사용할 경우 Pipeline: GitHub 플러그인으로 충분합니다. PR 자동 감지, 브랜치별 자동 파이프라인 생성이 필요하면 GitHub Branch Source를 추가 설치합니다.

3. Multibranch Pipeline 설정

Pipeline 생성

1. Jenkins 메인 페이지 > New Item
2. Item 이름 입력 후 Multibranch Pipeline 선택 > OK

Branch Sources 설정

Pipeline > Configure 에서 다음 항목을 설정합니다.

Build Configuration 설정

설정 완료 후 Apply > Save 를 클릭합니다.

4. 자동 빌드 테스트

Jenkinsfile 작성 예시

리포지토리의 지정된 경로에 Jenkinsfile을 작성합니다.

pipeline {
    agent any

    tools {
        jdk 'OpenJDK17'
    }

    stages {
        stage('Checkout') {
            steps {
                echo "Branch: ${env.BRANCH_NAME}"
                echo "Building project..."
            }
        }

        stage('Build') {
            steps {
                sh 'mvn clean package -DskipTests'
                archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
            }
        }
    }
}

Jenkinsfile을 작성한 후 GitHub에 Commit, Push하면 Webhook이 Jenkins에 전달되어 자동으로 빌드가 시작됩니다.

트러블슈팅

Webhook 수신 후 스크립트가 실행되지 않는 경우

아래 항목을 순서대로 점검합니다.

주의: Groovy로 작성한 Declarative Pipeline 스크립트는 Pipeline: Declarative 플러그인이 설치되어 있어야 정상적으로 실행됩니다. 이 플러그인이 없으면 스크립트를 인식하지 못합니다.

GitHub Webhook Delivery 확인

GitHub 리포지토리 > Settings > Webhooks 에서 해당 Webhook을 클릭하면, Recent Deliveries 탭에서 각 Webhook 전송의 요청/응답 정보를 확인할 수 있습니다.

주의할 점

Payload URL 마지막 슬래시 누락

Webhook URL을 https://jenkins.example.com/github-webhook으로 입력하면 동작하지 않습니다. ** 반드시 마지막에 /를 붙여야 합니다 **: https://jenkins.example.com/github-webhook/. 이 한 글자 차이로 Webhook 수신이 실패합니다.

Declarative Pipeline 플러그인 미설치

Groovy로 작성한 Declarative Pipeline 스크립트는 Pipeline: Declarative 플러그인이 설치되어 있어야 동작합니다. 이 플러그인이 없으면 Jenkinsfile을 인식하지 못하고, Webhook은 정상 수신되지만 빌드가 실행되지 않는 증상이 나타납니다.

정리