[참고] Jenkins를 활용한 CI/CD 파이프라인 구축 (GitHub → Docker → ECR 업로드)

🚀 Mac에서 Jenkins를 Docker로 실행하기

이 가이드는 MacOS 환경에서 Docker를 이용해 Jenkins를 실행하는 방법을 설명합니다.

Jenkins를 빠르게 설치하고 CI/CD 파이프라인을 구축해봅시다.!!

1️⃣ 사전 준비

필수 도구 설치

Docker Desktop 다운로드
- Mac에서 Docker가 실행되는지 확인 (docker --version)
Jenkins 실행을 위한 디렉토리 생성
mkdir -p ~/jenkins_home chmod 777 ~/jenkins_home

2️⃣ Docker로 Jenkins 실행

Jenkins 컨테이너 실행

docker run -d \
  --name jenkins \
  -p 8080:8080 -p 50000:50000 \
  -v ~/jenkins_home:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  jenkins/jenkins:lts

✅ 실행 옵션 설명

d : 백그라운드 실행
-name jenkins : 컨테이너 이름
p 8080:8080 : 웹 UI 포트 매핑
p 50000:50000 : 에이전트 통신 포트
v ~/jenkins_home:/var/jenkins_home : Jenkins 데이터 유지
v /var/run/docker.sock:/var/run/docker.sock : Docker 내부에서 Docker 실행 지원

컨테이너 실행 확인

docker ps

Jenkins 컨테이너가 정상적으로 실행 중인지 확인하세요.

3️⃣ 초기 패스워드 확인 및 Jenkins 접속

초기 관리자 패스워드 찾기

docker logs jenkins | grep -A 5 "Administrator password"

출력 예시:

Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:

123asdkjalskdjqlkweasd1234125

This may also be found at: /var/jenkins_home/secrets/initialAdminPassword

installation: 바로 아래 있는 문자열을 복사한 후 브라우저에서 Jenkins에 로그인하세요.

Jenkins 웹 UI 접속

브라우저에서 http://localhost:8080 접속
초기 패스워드 입력 후 로그인
"Install suggested plugins" 선택
관리자 계정 생성 후 Jenkins 설정 완료
Main 화면 입장

4️⃣ Jenkins 설정 및 플러그인 설치 (GitHub 연동 및 ECR 배포 준비)

🔹 1. Jenkins 필수 플러그인 설치

Jenkins에서 GitHub와 Docker 빌드, AWS ECR 업로드를 원활하게 수행하기 위해 다음 플러그인을 설치해야 합니다.

📌 필요한 플러그인

Git Plugin (GitHub 연동)
Pipeline Plugin (Pipeline 작성)
Docker Pipeline (Docker 빌드 및 푸시)
Amazon ECR Plugin (AWS ECR 업로드)

📌 설치 방법

Jenkins 관리자 페이지 → Manage Jenkins → Plugin Manager 이동
Available 탭에서 위 플러그인 검색 및 설치
설치 후 Jenkins 재시작

5️⃣ GitHub 인증 설정 (SSH 키 또는 PAT 방식)

Jenkins가 GitHub에서 코드를 가져오려면 인증이 필요합니다.

GitHub에 접근하는 방식은 SSH 키 인증과 Personal Access Token (PAT) 인증 두 가지 방법이 있습니다.

🔹 1. SSH 키 방식

Jenkins 서버에서 SSH 키 생성
- 기본 경로: /var/jenkins_home/.ssh/id_rsa
- id_rsa.pub 키를 복사
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
GitHub에 SSH 키 등록
- GitHub → Settings → SSH and GPG keys → New SSH Key
- id_rsa.pub 내용 붙여넣기
Jenkins에서 SSH 키 등록
- Manage Jenkins → Manage Credentials → System → Global credentials
- "Add Credentials" 클릭
  - Kind: SSH Username with Private Key
  - Username: git
  - Private Key: id_rsa 내용 붙여넣기

✅ GitHub SSH 인증 확인

ssh -T git@github.com

출력 예시

Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.

🔹 2. GitHub Personal Access Token (PAT) 방식

✔️ GitHub 계정의 비밀번호를 대체하는 토큰을 발급받아 사용할 수도 있습니다.

GitHub에서 PAT 발급
- GitHub 로그인 → Settings → Developer settings → Personal access tokens
- Generate new token 클릭
- repo 및 workflow 권한 선택 후 Generate token 클릭
- 발급된 토큰 복사 (한 번만 확인 가능)
Jenkins에서 PAT 등록
- Manage Jenkins → Manage Credentials → System → Global credentials
- "Add Credentials" 클릭
  - Kind: Username with password
  - Username: GitHub 사용자명
  - Password: 발급받은 GitHub 토큰
  - ID: github-token

6️⃣ Jenkins에서 GitHub 저장소 연결

Jenkins에서 GitHub 저장소를 연동하여 코드를 가져와 빌드할 수 있도록 설정합니다.

🔹 1. GitHub 저장소 연결

Jenkins → New Item → Pipeline 선택
Pipeline Name 입력 후 OK 클릭
General → GitHub Project 체크 후 Repository URL 입력
https://github.com/your-repo/your-project.git
Build Triggers → GitHub hook trigger for GITScm polling 체크
- GitHub에서 변경 사항이 감지될 때 자동 빌드 트리거

7️⃣ Jenkins Pipeline Script 설정 (Jenkinsfile 활용)

Jenkins에서는 GitHub의 Jenkinsfile을 사용해 빌드 파이프라인을 정의합니다.

프로젝트 루트에 Jenkinsfile을 추가하여 Jenkins가 자동으로 파이프라인을 실행할 수 있도록 설정합니다.

pipeline {
    agent any

    environment {
        AWS_REGION = "ap-northeast-2"  // AWS 리전 설정
        AWS_ACCOUNT_ID = "123456789012"  // AWS 계정 ID (ECR 저장소 소유자)
        ECR_REPO = "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/my-jenkins-image" // AWS ECR 저장소 URL
        IMAGE_TAG = "latest"  // 기본 태그 설정
    }

    stages {
        stage('Ensure ECR Exists') {
            steps {
                script {
                    // ECR 저장소가 존재하는지 확인하고 없으면 생성
                    sh """
                    aws ecr describe-repositories --repository-names my-jenkins-image --region ${AWS_REGION} || \
                    aws ecr create-repository --repository-name my-jenkins-image --region ${AWS_REGION}
                    """
                }
            }
        }

        stage('Checkout') {
            steps {
                // GitHub 저장소에서 코드 가져오기
                git branch: 'main', credentialsId: 'your-credentials-id', url: 'git@github.com:your-repo/your-project.git'
            }
        }

        stage('Build Docker Image') {
            steps {
                script {
                    // Docker 이미지 빌드 (태그 포함)
                    sh "docker build -t ${ECR_REPO}:${IMAGE_TAG} ."
                }
            }
        }

        stage('AWS ECR Login') {
            steps {
                script {
                    // AWS ECR 로그인 수행
                    sh "aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${ECR_REPO}"
                }
            }
        }

        stage('Push Docker Image to ECR') {
            steps {
                script {
                    // Docker 이미지를 ECR에 Push
                    sh "docker push ${ECR_REPO}:${IMAGE_TAG}"
                }
            }
        }
    }
}

📌 Jenkinsfile 코드 상세 설명

이 Jenkinsfile은 GitHub에서 코드를 가져와 Docker 이미지를 빌드하고, AWS ECR에 업로드하는 전체 CI/CD 과정을 수행합니다.

🔹 1. pipeline { agent any }

Jenkins 파이프라인의 실행 환경을 설정합니다.
agent any는 어떤 Jenkins 노드에서든 실행할 수 있도록 허용하는 설정입니다.

🔹 2. environment {} (환경 변수 설정)

AWS 관련 환경 변수를 설정합니다.

AWS_REGION = "ap-northeast-2"
AWS_ACCOUNT_ID = "123456789012"
ECR_REPO = "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/my-jenkins-image"
IMAGE_TAG = "latest"

AWS_REGION → AWS에서 사용할 리전 (서울 리전 "ap-northeast-2")
AWS_ACCOUNT_ID → AWS 계정 ID, ECR 리포지토리 소유자의 ID
ECR_REPO → ECR 저장소 URL
IMAGE_TAG → Docker 이미지 태그 (latest 기본 설정)

🔹 3. stage('Ensure ECR Exists') (ECR 저장소 확인 및 생성)

stage('Ensure ECR Exists') {
    steps {
        script {
            sh """
            aws ecr describe-repositories --repository-names my-jenkins-image --region ${AWS_REGION} || \
            aws ecr create-repository --repository-name my-jenkins-image --region ${AWS_REGION}
            """
        }
    }
}

ECR 저장소가 존재하는지 확인하고 없다면 자동 생성합니다.
aws ecr describe-repositories 명령어로 존재 여부 확인
만약 저장소가 없으면 aws ecr create-repository를 실행하여 생성

✅ 이 단계를 추가하면 최초 배포에서도 오류 없이 진행 가능합니다.

🔹 4. stage('Checkout') (GitHub에서 코드 가져오기)

stage('Checkout') {
    steps {
        git branch: 'main', credentialsId: 'your-credentials-id', url: 'git@github.com:your-repo/your-project.git'
    }
}

GitHub에서 main 브랜치의 코드를 Jenkins 작업 공간으로 가져옵니다.
credentialsId: 'your-credentials-id' → Jenkins에 저장된 GitHub SSH Key or Token을 사용하여 인증
url: 'git@github.com:your-repo/your-project.git'
- SSH 인증 방식 사용 (HTTPS 방식 사용 시 https://github.com/your-repo/your-project.git)

🔹 5. stage('Build Docker Image') (Docker 이미지 빌드)

stage('Build Docker Image') {
    steps {
        script {
            sh "docker build -t ${ECR_REPO}:${IMAGE_TAG} ."
        }
    }
}

docker build 명령어를 실행하여 Docker 이미지를 생성
${ECR_REPO}:${IMAGE_TAG} → ECR 저장소를 참조하여 태깅

✅ ECR 저장소에 맞게 이미지가 자동 태깅되므로 추가 설정 필요 없음

stage('AWS ECR Login') {
    steps {
        script {
            sh "aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${ECR_REPO}"
        }
    }
}

AWS CLI를 통해 ECR 로그인 수행
aws ecr get-login-password --region ${AWS_REGION} → AWS에서 ECR 로그인 비밀번호 가져오기
docker login --username AWS --password-stdin ${ECR_REPO} → 해당 패스워드를 사용하여 로그인

✅ 이 단계를 수행해야 ECR에 Docker 이미지를 푸시할 수 있음

🔹 7. stage('Push Docker Image to ECR') (Docker 이미지 푸시)

stage('Push Docker Image to ECR') {
    steps {
        script {
            sh "docker push ${ECR_REPO}:${IMAGE_TAG}"
        }
    }
}

docker push 명령어로 빌드된 이미지를 AWS ECR 저장소에 업로드

✅ 완료 후 AWS ECR에서 이미지를 확인할 수 있음

aws ecr list-images --repository-name my-jenkins-image --region ap-northeast-2

정리

이 Jenkinsfile은:

GitHub에서 최신 코드 가져오기 (Checkout)
Docker 이미지 빌드 (Build Docker Image)
AWS ECR에 로그인 (AWS ECR Login)
Docker 이미지를 AWS ECR에 푸시 (Push Docker Image to ECR)

을 수행하는 완전한 CI/CD 파이프라인을 구축합니다.

8️⃣ AWS ECR 연동 (IAM 및 권한 설정)

🔹 1. AWS CLI 설치

brew install awscli

🔹 2. AWS IAM 사용자 생성 (ECR 접근 가능하도록 설정)

AWS IAM → 사용자 추가 → 프로그램 방식 접근
권한 추가: AmazonEC2ContainerRegistryFullAccess
Access Key & Secret Key 저장

🔹 3. Jenkins에서 AWS Credentials 추가

Manage Jenkins → Manage Credentials → Global Credentials
"Add Credentials" 클릭
- Kind: AWS Credentials
- Access Key ID & Secret Key 입력
- ID: aws-credentials

9️⃣ GitHub Webhook 설정 (자동 빌드 트리거)

Jenkins에서 GitHub의 변경 사항을 자동으로 감지하고 빌드를 트리거하려면 Webhook을 설정해야 합니다.

🔹 1. GitHub Webhook 설정

GitHub Repository → Settings → Webhooks 이동
Webhook 추가 (Add webhook) 클릭
Webhook 정보 입력
- Payload URL:
```
http://your-jenkins-url/github-webhook/
```
  - your-jenkins-url은 Jenkins 서버의 실제 URL로 변경해야 합니다.
  - Jenkins가 외부에서 접근 가능해야 합니다 (예: http://jenkins.yourdomain.com/github-webhook/).
- Content type: application/json
- Secret: Jenkins에서 Webhook 인증을 강화하려면, 임의의 Secret을 입력하고 Jenkins에서도 같은 값을 설정해야 합니다.
- Which events would you like to trigger this webhook?
  - Just the push event 체크 (기본적으로 코드 변경 시 자동 트리거)
  - Pull requests를 포함하려면 별도로 체크 가능
Webhook 저장 (Add webhook) 클릭

🔹 2. Jenkins에서 Webhook 수신 설정

Jenkins가 Webhook 요청을 정상적으로 처리하려면 GitHub Plugin을 활성화해야 합니다.

Jenkins → Manage Jenkins → Configure System 이동
GitHub 섹션에서 GitHub Webhook 설정 확인
"Manage Hooks" 권한을 부여한 GitHub Credentials 추가
- Manage Jenkins → Manage Credentials → Add Credentials
- Kind: Username with password
- Username: GitHub 사용자명
- Password: Personal Access Token (PAT)
- Scope: Global
해당 Credentials를 GitHub 설정에서 연결

🔹 3. GitHub Hook Trigger 활성화 (Jenkins Job 설정)

Jenkins에서 Webhook을 사용하려면 Job에서 해당 옵션을 활성화해야 합니다.

Jenkins → 해당 Pipeline Job → Configure 이동
"Build Triggers" 섹션에서 아래 옵션 활성화
- ✅ GitHub hook trigger for GITScm polling 체크

✅ 이제 GitHub에서 코드가 푸시될 때마다 Jenkins가 자동으로 빌드를 수행합니다. 🚀

🔟 Jenkins 실행 및 배포 테스트

1. Jenkins Job 실행

Jenkins → New Item → Pipeline 생성
SCM을 Git으로 설정 (GitHub 레포지토리 설정)
"Build Now" 실행
Pipeline 실행 로그 확인

✅ 성공 시 AWS ECR 확인

aws ecr list-images --repository-name my-jenkins-image --region ap-northeast-2

🎯 마무리

이제 Jenkins를 통해 GitHub에서 코드를 가져와 Docker 이미지를 빌드하고, AWS ECR에 업로드하는 자동화 CI/CD 파이프라인이 구축되었습니다! 🚀

다음으로 배포 환경 (ECS, Kubernetes)까지 확장하는 과정을 진행하면 완전한 DevOps 워크플로우를 구축할 수 있습니다.

출처 : https://velog.io/@maasj/Jenkins%EB%A5%BC-%ED%99%9C%EC%9A%A9%ED%95%9C-CICD-%ED%8C%8C%EC%9D%B4%ED%94%84%EB%9D%BC%EC%9D%B8-%EA%B5%AC%EC%B6%95-GitHub-Docker-ECR-%EC%97%85%EB%A1%9C%EB%93%9C

저작자표시 비영리 변경금지 (새창열림)

'[AWS-FRF] > CICD' 카테고리의 다른 글

RUN npm install 이란? (0)	2025.11.04
clean package -DskipTests 정의 !! (1)	2025.11.04
[참고][Docker] 스프링부트 프로젝트 도커 이미지(Image) 만들고 실행하기 !! (0)	2025.11.03
[참고][Docker] Dockerfile 작성법 !! (Jar파일 실행 이미지 만들기) (1)	2025.11.03
[docker builder prune] Docker 빌드 캐시(build cache) 및 중간 이미지 정리!! (1)	2025.10.29
[참고][Jenkins] Docker build 후 Amazon ECR로 이미지 업로드하기 !! (0)	2025.10.29
[참고][AWS][Jenkins] 변경된 설정을 이력으로 남기기 (config history)!! (8)	2025.01.21
[중요][AWS] 젠킨스 war 파일 업데이트 방법!! (4)	2025.01.08