Jenkins로 도커 이미지 빌드 파이프라인 구성하기

들어가며

이 글에서는 Jenkins를 활용해 GitHub의 코드 변경을 자동으로 감지하고, Docker 이미지를 빌드해 Docker Hub에 푸시하는 파이프라인 구축 방법을 알아보겠습니다 👀

1. GitHub Personal Access Token 생성

Jenkins가 GitHub 저장소에 접근할 수 있도록 Personal Access Token(PAT)를 생성합니다.

설정 경로

GitHub → Settings → Developer Settings → Personal Access Tokens → Generate new token (classic)

권한 설정

• repo: 저장소 전체 접근 권한
• workflow: GitHub Actions 관련 권한
• admin:repo_hook: 웹훅 관련 권한

‼️ 토큰 생성 후 다시 확인할 수 없으니, 반드시 복사해 보관하세요.

2. 젠킨스에서 GitHub 인증 설정

Jenkins가 GitHub 저장소에 접근할 수 있도록 자격 증명을 등록합니다.

설정 경로

Jenkins 관리 들어간 후, 아래 이미지를 따라가세요 💫

입력 정보

• Kind: Username with password
• Username: GitHub 사용자명
• Password: 앞서 생성한 GitHub PAT
• ID: Jenkins 내부에서 사용할 고유 ID

3. 플러그인 설치

Jenkins에서 GitHub 및 Docker와의 연동을 위해 다음 플러그인을 설치합니다.

설정 경로

Jenkins 관리 → 플러그인 관리 → Available plugins

설치 플러그인 목록

• GitHub Integration: Jenkins와 GitHub 간 통합 기능 제공
• GitHub API Plugin: GitHub API와의 연동 기능 제공
• Generic Webhook Trigger: GitHub Webhook 이벤트 수신
• Docker Pipeline: Jenkins 파이프라인에서 Docker 작업 실행 가능

4. Docker Hub 인증 설정

Jenkins가 Docker Hub에 이미지를 푸시할 수 있도록 Personal Access Token을 발급받아 설정해야 합니다.

발급 방법

Docker Hub 로그인 → Settings → Personal access tokens → Generate new token

• 토큰 이름 입력
• 읽기/쓰기 권한 부여 (Read/Write)

‼️ 이것도 토큰 생성 후 다시 확인할 수 없으니, 반드시 복사해 보관하세요.

5. Jenkins에 Docker Hub 자격증명 등록

Docker 이미지 푸시를 위해 Jenkins에 Docker Hub 자격증명을 등록해야 합니다.

설정 경로

GitHub 인증 정보를 등록할 때와 동일한 경로를 따라 설정합니다.

입력값 설정

• Kind: Username with password
• Username: Docker Hub ID
• Password: 앞서 생성한 Docker Hub PAT
• ID: docker-registry-credentials

📌 ID는 젠킨스 파이프라인 스크립트에서 사용되니 기억해두세요!

6. Dockerfile 작성

웹 애플리케이션을 Nginx 기반으로 컨테이너화하는 Dockerfile 예시입니다 ☺️

# Nginx 기반 이미지 사용
FROM nginx:alpine

# 작업 디렉토리 설정
WORKDIR /usr/share/nginx/html

# HTML 파일들을 컨테이너로 복사
COPY *.html ./

# Nginx 설정 파일 복사 (기본 설정 사용)
# 필요시 커스텀 nginx.conf 파일을 추가할 수 있습니다

# 포트 80 노출
EXPOSE 80

# Nginx 시작
CMD ["nginx", "-g", "daemon off;"] 

7. Jenkinsfile (Pipeline 코드)

루트 디렉토리에 Jenkinsfile을 작성하여 파이프라인을 정의합니다. 아래는 GitHub 코드 변경 시 도커 이미지를 빌드하고 Docker Hub로 푸시하는 기본 파이프라인 예시입니다.

• environment: 파이프라인 전역에서 사용할 변수 정의
• stages: 단계별 작업 정의
• post: 파이프라인 종료 후 실행할 작업 정의

pipeline {
    agent any

    environment {
        // Docker Hub 레지스트리 정보
        REGISTRY = "yukyung0"
        IMAGE_NAME = "dtalks-design"

        // Jenkins 빌드 번호를 이미지 버전 태그로 사용
        IMAGE_TAG = "${env.BUILD_NUMBER}"

        // 전체 이미지 경로
        FULL_IMAGE = "${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}"
        LATEST_IMAGE = "${REGISTRY}/${IMAGE_NAME}:latest"
    }

    stages {
        stage('Checkout') {
            steps {
                // Git 저장소 코드 가져오기
                checkout scm
            }
        }

        stage('Build Docker Image') {
            steps {
                // 버전 태그와 latest 태그를 동시에 지정하여 빌드
                sh '''
                docker build -t $FULL_IMAGE -t $LATEST_IMAGE .
                '''
            }
        }

        stage('Push to Docker Registry') {
            steps {
                // Jenkins에 등록된 Docker Hub 자격 증명 사용
                withCredentials([usernamePassword(
                    credentialsId: 'docker-registry-credentials',
                    usernameVariable: 'REGISTRY_USER',
                    passwordVariable: 'REGISTRY_PASS'
                )]) {
                    // 버전 태그 및 latest 태그 모두 push
                    sh '''
                    echo "$REGISTRY_PASS" | docker login -u "$REGISTRY_USER" --password-stdin

                    docker push $FULL_IMAGE
                    docker push $LATEST_IMAGE

                    docker logout
                    '''
                }
            }
        }
    }

    post {
        always {
            // 워크스페이스 정리
            cleanWs()
        }
        success {
            echo "Pipeline completed successfully."
            echo "Image pushed: ${FULL_IMAGE}, ${LATEST_IMAGE}"
        }
        failure {
            echo "Pipeline failed. Check logs for details."
        }
    }
}

8. Jenkins Pipeline Job 생성

설정 경로

• Jenkins 대시보드 → New Item 클릭
• 원하는 이름 입력 및 Pipeline 선택
  

9. GitHub 연동 및 Webhook 설정

General

• GitHub project 체크 후 Repository URL 입력

Triggers

• GitHub hook trigger for GITScm polling 체크
  → GitHub Webhook 요청이 올 때 자동으로 빌드가 실행됩니다.

Pipeline

• Definition: Pipeline script from SCM
• SCM: Git
• Repository URL: GitHub 리포지토리 주소 입력
• Credentials: 앞서 등록한 GitHub 자격 증명 선택
• Branch Specifier: */main (브랜치에 맞게 입력)
• Script Path: Jenkinsfile (루트에 위치한 경우 기본값)

Webhook 설정 방법은 다음 글을 참고해주세요.
🔗 Jenkins에 GitHub Webhook 연동하기

10. 테스트

🥳 이제 커밋 한 줄만으로도 파이프라인이 자동으로 실행됩니다.

# 테스트 커밋 생성
echo "# Jenkins webhook trigger test" >> README.md
git add README.md
git commit -m "jenkins webhook trigger test"
git push origin main

아래와 같이 빌드부터 이미지 푸시까지 자동으로 실행되는 것을 확인할 수 있습니다!