GitHub 웹훅 기반 Jenkins CI/CD 파이프라인 설계

이 문서에서는 GitHub 웹훅을 활용하여 Jenkins 기반의 CI/CD 파이프라인을 설계하는 방법을 설명한다.
Jenkins는 다양한 자동화 작업을 처리할 수 있는 강력한 도구로, GitHub 웹훅을 통해 코드 변경을 자동으로 감지하고 빌드, 배포 등의 작업을 자동화할 수 있다.

---

✅ 기본 준비

1. 시스템 업데이트

sudo apt update

---

✅ 도커파일

• Jenkins Docker를 설정할 때 사용하는 기본 docker-compose.yml 파일:

version: '3.3'

services:
  jenkins:
    image: jenkins/jenkins:jdk17
    container_name: jenkins
    user: root
    ports:
      - "8085:8080"
      - "50000:50000"
    volumes:
      - jenkins-data:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock

volumes:
  jenkins-data: {}

---

✅ 설치 후 셋팅

• Jenkins 접속 후 초기 비밀번호 확인 방법:

docker exec -it jenkins bash
cat /var/jenkins_home/secrets/initialAdminPassword

---

✅ SSH 설정

CI/CD 배포 자동화를 위해 Jenkins가 원격 서버에 접근할 수 있도록 SSH 키를 설정해야 한다.

1. 로컬에서 SSH 키 생성

ssh-keygen -t rsa -b 4096

기본 경로는 ~/.ssh/id_rsa 및 ~/.ssh/id_rsa.pub

2. 원격 서버(GCP, EC2 등)에 공개키 등록

• GCP의 경우: 콘솔 → 메타데이터 → SSH 키 탭에 id_rsa.pub 내용 추가
• 일반 리눅스 서버의 경우: 대상 서버의 ~/.ssh/authorized_keys 파일에 붙여넣기

3. Jenkins 자격증명에 SSH 키 등록

• Jenkins > Credentials > Global > Add credentials
• Kind: SSH Username with private key
• Username: 서버 사용자 이름 (예: ubuntu)
• Private Key: id_rsa 파일 내용 붙여넣기

4. SSH 테스트

ssh -i ~/.ssh/id_rsa user@your.remote.server

---

✅ Jenkins 내 도커 설치

Jenkins 접속

docker exec -it jenkins /bin/bash

도커 설치

# 1. 기존 패키지 제거
apt-get remove docker docker-engine docker.io containerd runc

# 2. 올바른 Docker 저장소 추가
apt-get update
apt-get install -y ca-certificates curl gnupg lsb-release

# 2.2 Docker의 GPG 키 추가
mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 2.3 Docker 저장소 추가
echo   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian   $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

# 3. Docker 설치
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 4. Docker 설치 확인
docker --version

---

✅ Jenkins 파이프라인 설정

1. 파이프라인 아이템 생성

• Jenkins에서 파이프라인을 생성하여 GitHub 리포지토리 변경 시 자동으로 빌드가 트리거될 수 있도록 설정한다.

2. 빌드 트리거 설정

# GitHub 웹훅을 사용하여 Jenkins가 빌드를 트리거할 수 있도록 설정
Build when a change is pushed to GitHub. Webhook URL: http://<JENKINS_URL>:8080/project/<PROJECT_NAME>

3. 고급 설정에서 토큰 생성 후 GitHub에 연결

# Jenkins의 고급 설정에서 토큰을 생성하고, GitHub 웹훅 설정에서 URL과 토큰을 입력한다.

---

✅ Jenkins 플러그인 설치

필요한 플러그인들:

• Docker Pipeline
• SSH Agent
• Publish Over SSH
• Mattermost Notification
• Pipeline: Stage View
• GitLab API Plugin

---

✅ Jenkins 자격증명 (Credentials) 설정

자격증명 생성

• GitHub와 연동하기 위해 사용자 인증 정보를 추가한다.

Kind: Username with password
Scope: Global (Jenkins, nodes, items, etc.)
Username: GitHub 사용자 ID
Password: GitHub에서 발급받은 토큰 값

---

✅ Docker 파이프라인 연결

1. 파이프라인으로 아이템 생성
2. GitHub Webhook URL을 Jenkins에 설정
3. GitHub에서 웹훅 설정 후 테스트 실행

# GitHub 레포지토리에서 웹훅을 설정하고, Jenkins에 해당 URL과 토큰을 입력

---

✅ SSH 등록

1. GCP 콘솔에서 SSH 키 생성

ssh-keygen -t rsa -b 4096

2. GCP 메타데이터에 SSH 퍼블릭 등록

# 관리 -> 환경설정에서 SSH 등록

3. Jenkins에 SSH 연결 설정

• Jenkins에서 원격 서버에 배포할 때 사용할 SSH 키를 등록하고 연결한다.

---

✅ Docker Compose 파일 예시 (Spring Boot 애플리케이션)

version: '3'
services:
  app:
    image: stquokka/free:latest
    container_name: spring_app
    ports:
      - "8080:8080"
    environment:
      SPRING_PROFILES_ACTIVE: "dev"
    volumes:
      - ./logs:/app/logs

---

✅ 배포 디렉토리 미리 생성하기

# 파이프라인 deploy에서 필요
scp -o StrictHostKeyChecking=no $ENV_FILE ${REMOTE_USER}@${REMOTE_HOST}:${TARGET_DIRECTORY}/.env

mkdir -p /home/wwnirnr/BE/

---

✅ Mattermost 알림 연결

• Mattermost에 연결하여 Jenkins에서 빌드 및 배포 상태 알림을 받을 수 있도록 설정한다.

---

📘 결론

GitHub 웹훅과 Jenkins를 사용한 CI/CD 파이프라인 설정은 코드 변경 시 자동 빌드, 테스트, 배포까지 자동화하는 데 유용하다.
이 과정은 수동 작업을 최소화하고, 빠르고 안정적인 배포 환경을 제공한다.