catsridingCATSRIDING|OCEANWAVES
Ops

Jenkins CI/CD Pipeline 구축하기 02. Jenkins와 GitHub Webhooks 연동하기

jynn@catsriding.com
Mar 15, 2024
Published byJynn
999
Jenkins CI/CD Pipeline 구축하기 02. Jenkins와 GitHub Webhooks 연동하기

Integrate Jenkins with GitHub Webhooks

GitHub의 웹훅을 Jenkins에 연동하면, GitHub 리포지토리의 특정 브랜치에서 발생한 변화를 감지하여 Jenkins에서 특정 작업을 자동으로 실행할 수 있게 됩니다.

예를 들어, release 브랜치에 새로운 커밋이 푸시되면 GitHub의 웹훅을 통해 Jenkins가 이를 감지하고, 애플리케이션을 빌드한 다음 프로덕션 서버에 배포하는 작업을 자동화 할 수 있습니다.

AWS EC2에 Jenkins 서버 구축하는 과정에 이어서, 이번 글에서는 GitHub Webhooks과 Jenkins 프로젝트를 연동하는 방법에 대해 알아보겠습니다.

Prerequisite

  • Jenkins
  • Spring Boot with Maven
  • GitHub Repository

Setting Up Jenkins Project

젠킨스와 GitHub 웹훅을 통한 CI/CD 환경을 구축하려면 먼저 젠킨스의 초기 환경을 구성해야 합니다.

Getting Started

브라우저를 열고 Jenkins UI에 접속합니다. 최초 접속시에는 서버 로그에서 제공된 초기 패스워드를 입력하여 로그인합니다.

로그인 후에는 본격적으로 젠킨스 환경을 구성하는 Getting Started 페이지로 이동하게 됩니다. 여기에서 Install suggested plugins을 선택하여 젠킨스가 정상적으로 작동하는데 필요한 플러그인들을 설치합니다.

integrate-jenkins-with-github-webhooks_00.png

플러그인 설치는 전체적으로 약 10분 정도 소요됩니다.

integrate-jenkins-with-github-webhooks_01.png

플러그인 설치가 모두 완료되면, 첫 번째 관리자 계정을 생성하는 단계로 이동하게 됩니다. 이 계정은 앞으로 젠킨스에 접속할 때 사용하게 됩니다.

integrate-jenkins-with-github-webhooks_02.png

젠킨스 초기 환경 설정이 모두 완료되었습니다.

integrate-jenkins-with-github-webhooks_03.png

Configuring GitHub Webhooks

다음은, Jenkins에서 GitHub 저장소의 변경사항을 감지할 수 있도록 GitHub Webhooks을 활성화하고 소스 코드에 접근하기 위한 자격 증명을 발급합니다.

Generating GitHub Access Token

Personal Access Token은 GitHub의 API에 접근하기 위한 권한을 부여받는 방법 중 하나입니다. 이 토큰을 통해 Jenkins는 GitHub와 상호작용할 수 있게 됩니다. 토큰 생성을 위해 먼저 GitHub에 로그인 한 다음 상단 오른쪽에 위치한 Settings 메뉴로 이동합니다.

integrate-jenkins-with-github-webhooks_04.png

계정 설정 화면에서 왼쪽 메뉴 하단에 위치한 Developer settings로 이동합니다. 여기에서 권한을 부여받은 액세스 토큰을 생성할 수 있습니다.

integrate-jenkins-with-github-webhooks_05.png

Personal access tokens 중 Fine-grained tokens은 아직 Beta이기 때문에 클래식 토큰으로 진행합니다.

integrate-jenkins-with-github-webhooks_06.png

액세스 토큰에는 Jenkins가 GitHub Repository와 웹훅에 접근하는데 필요한 repo 및 admin:repo_hook 권한을 부여합니다.

integrate-jenkins-with-github-webhooks_07.png

모든 설정이 완료되면, Generate token 버튼을 클릭하여 토큰을 생성합니다. 화면 상단에 토큰 값이 표시되는데, 이 정보는 페이지를 벗어나면 볼 수 없으므로 복사하여 안전한 곳에 보관합니다.

integrate-jenkins-with-github-webhooks_08.png

Creating Jenkins Credentials

Jenkins에서는 특정 서비스에 접근할 때 필요한 자격 증명을 Credentials로 관리할 수 있습니다. 이전 단계에서 생성한 GitHub Personal Access Token을 활용하여 GitHub 저장소 연동에 필요한 새로운 Credential을 생성합니다.

Jenkins UI로 돌아와서 Manage Jenkins ▸ Manage Credentials 메뉴를 선택하여 Credentials 페이지로 이동합니다.

integrate-jenkins-with-github-webhooks_09.png

Jenkins 내에서 이 Credential은 전역적으로 사용되므로 System scope에 저장합니다.

integrate-jenkins-with-github-webhooks_10.png

System Credentials 화면으로 이동하여 Add Credentials을 클릭합니다.

integrate-jenkins-with-github-webhooks_11.png

GitHub 자격 증명을 위한 새로운 Credential을 생성할 때 아래와 같은 정보를 입력하게 됩니다:

integrate-jenkins-with-github-webhooks_12.png

  • Scope: 이 자격증명이 적용되는 범위를 선택합니다. 여기서는 전역(Globally)으로 설정합니다.
  • Username: GitHub 계정의 사용자 이름을 입력합니다.
  • Password: GitHub에서 생성한 Personal Access Token을 입력합니다. 이 토큰을 통해 Jenkins에 GitHub 액세스 권한이 부여됩니다.
  • ID: 이 자격증명을 Jenkins 내에서 구분하기 위한 고유한 ID를 입력합니다.
  • Description: 자격증명에 대한 설명을 입력합니다. 이는 나중에 관리를 위해 사용됩니다.

Enabling GitHub Webhooks

다음은 새로운 커밋이 발생할 때마다 GitHub 리포지토리에서 Webhooks이 작동하도록 설정합니다. 웹훅을 활성화하려는 GitHub 리포지토리로 이동하고 우측 상단에 있는 Settings를 클릭합니다.

integrate-jenkins-with-github-webhooks_15.png

왼쪽 메뉴에서 Webhooks을 선택하면, 현재 활성화된 웹훅의 목록을 볼 수 있습니다. Add webhook을 클릭하여 새로운 웹훅을 추가합니다.

integrate-jenkins-with-github-webhooks_16.png

Payload URL 입력창에 Jenkins 서버의 주소를 입력합니다. GitHub 플러그인의 디폴트 설정에 의해 이 URL은 다음과 같은 패턴을 따르게 됩니다:

{JENKINS_BASE_URL}/github-webhook/
# for example: https://ci.example.com/jenkins/github-webhook/
  • {JENKINS_BASE_URL}은 Jenkins 서버의 기본 URL입니다.
  • 주의할 점은 URL 끝에 반드시 슬래시(/)를 포함해야 한다는 것입니다. 이를 누락하면 웹훅 연결이 실패할 수 있습니다.

integrate-jenkins-with-github-webhooks_17.png

웹훅 정보를 다 입력했다면, 하단의 Add webhook 버튼을 클릭하여 웹훅을 추가합니다.

이후 GitHub에서 입력한 Payload URL에 접근하여 연동이 정확하게 이루어졌는지 자동으로 검증합니다. 이 과정이 성공적으로 완료되면, 웹훅 목록에 ✓ 마크가 나타납니다.

integrate-jenkins-with-github-webhooks_18.png

이제 Jenkins에서 해당 GitHub 리포지토리에서 발생하는 이벤트를 수신할 수 있게 되었습니다.

Setting Push Trigger in Jenkins

이제 마지막 단계로, GitHub 웹훅 이벤트를 수신하여 자동으로 작업이 수행되는 Jenkins 프로젝트를 구성합니다.

Installing Maven Plugin

Maven 기반의 Spring Boot 프로젝트라면 Maven Integration 플러그인을 설치하는 것이 편리합니다. Jenkins UI의 대시보드에서 Manage Plugins 화면으로 이동합니다.

integrate-jenkins-with-github-webhooks_13.png

Maven Integration을 검색하고 설치합니다. 설치는 대략 5분 정도 소요됩니다.

integrate-jenkins-with-github-webhooks_14.png

Creating a new Jenkins Projects

플러그인 설치가 완료되면 Jenkins 대시보드로 돌아와 New Item을 클릭하여 새 프로젝트를 생성합니다.

integrate-jenkins-with-github-webhooks_25.png

Maven Integration Plugin에서 제공한 Maven project 생성 템플릿을 선택한 후, 고유한 프로젝트명을 입력합니다.

integrate-jenkins-with-github-webhooks_19.png

프로젝트 설정에서는 GitHub 저장소 연동, 웹훅 이벤트 트리거 설정, 그리고 Jenkins에서 수행할 작업 등의 조정이 이루어집니다.

General 탭에서는 GitHub 리포지토리를 연동합니다.

integrate-jenkins-with-github-webhooks_20.png

  • GitHub project: 연동하려는 GitHub 리포지토리의 URL을 여기에 입력합니다.

그리고 Source Code Management에서는 Jenkins가 소스 코드를 어떻게 관리할지 구성합니다 integrate-jenkins-with-github-webhooks_21.png

  • 소스 코드 관리 툴: Git을 선택하고, Repository URL은 이전에 입력한 GitHub Repository의 URL을 그대로 사용합니다.
  • Credentials: 위에서 추가했던 GitHub 자격증명을 선택하여 저장소에 접근할 수 있게 합니다
  • Branches to build: 어떤 브랜치를 빌드할지 지정할 수 있습니다. 이 경우, main 브랜치에 새로운 커밋이 푸시될 때마다 빌드를 트리거하도록 설정합니다.

Build Triggers 탭에서는 어떤 이벤트가 발생했을 때 빌드가 시작될지 설정할 수 있습니다.

integrate-jenkins-with-github-webhooks_22.png

  • GitHub hook trigger for GITScm polling: 이 설정은 GitHub 저장소에서 푸시 이벤트가 발생할 때마다, Jenkins가 해당 저장소를 폴링하고 변동사항이 있다면 해당 빌드를 수행하도록 합니다. 즉, Source Code Management 섹션에서 설정한 GitHub 저장소의 지정된 브랜치에 새로운 커밋이 푸시되면 해당 커밋에 따른 빌드가 자동으로 트리거됩니다.

Verifying the Setup

이제 실제로 코드를 변경하고 새롭게 커밋을 만들어서 푸시해봅니다. 이 변경이 제대로 Jenkins에 감지되고 빌드가 수행되는지 확인하는 과정을 통해 지금까지의 세팅이 정상적으로 작동하는지 검증할 수 있을 것입니다.

README.md 파일에 간단한 수정을 한 다음 이를 main 브랜치에 커밋하고 푸시해봅니다. 설정이 올바르게 이루어졌다면, Jenkins 대시보드나 프로젝트의 Build Executor Status 탭에서 새로운 작업이 자동적으로 시작되는 모습을 확인할 수 있을 것입니다. 🥳

integrate-jenkins-with-github-webhooks_23.png

작업 번호를 클릭하면, 그 작업의 상세 상태와 콘솔 로그 등도 확인할 수 있습니다.

integrate-jenkins-with-github-webhooks_24.png

  • AWS
  • CI / CD