초보자도 쉽게 아는 Jenkins

들어가며

현대 소프트웨어 개발에서 CI/CD(Continuous Integration/Continuous Deployment)는 필수 요소가 되었습니다.
코드 변경사항을 자동으로 빌드하고 테스트하며 배포하는 과정을 통해 개발 효율성을 극대화할 수 있습니다. 이번 글에서는 가장 널리 사용되는 CI/CD 도구인 Jenkins의 개념부터 설치, 설정, 그리고 GitLab과의 연동까지 알아보겠습니다.

Jenkins란?

Jenkins는 Sun Microsystems에서 개발되기 시작한 오픈소스 자동화 서버로, 현재 가장 널리 사용되는 CI/CD 도구 중 하나입니다. 2011년 Hudson에서 분기되어 독립적인 프로젝트로 발전했으며, 현재는 CloudBees가 주도하여 개발하고 있습니다.

Jenkins의 핵심 개념

지속적 통합 (Continuous Integration, CI)
개발자들이 코드를 자주 메인 브랜치에 통합하고, 각 통합마다 자동화된 빌드와 테스트를 수행하여 통합 오류를 빠르게 감지하는 개발 방식입니다.

지속적 배포 (Continuous Deployment, CD)
코드 변경사항이 테스트를 통과하면 자동으로 프로덕션 환경에 배포하는 방식입니다. 수동 개입 없이 전체 파이프라인이 자동화됩니다.

지속적 전달 (Continuous Delivery, CD)
코드 변경사항을 언제든지 배포할 수 있는 상태로 유지하되, 실제 배포는 수동으로 결정하는 방식입니다.

Jenkins의 주요 특징

플러그인 생태계
3,000개 이상의 플러그인을 통해 거의 모든 도구와 서비스를 연동할 수 있습니다. Git, Docker, AWS, Kubernetes, Slack 등 다양한 도구들과 쉽게 통합됩니다.

분산 빌드
마스터-슬레이브 아키텍처를 통해 여러 서버에서 병렬로 빌드 작업을 수행할 수 있어 대규모 프로젝트에도 적합합니다.

파이프라인 as 코드
Jenkinsfile을 통해 빌드 파이프라인을 코드로 정의하고 버전 관리할 수 있어 Infrastructure as Code(IaC) 방식을 지원합니다.

웹 기반 관리
모든 설정과 모니터링을 웹 인터페이스를 통해 수행할 수 있어 사용이 편리합니다.

오픈소스
무료로 사용할 수 있으며, 활발한 커뮤니티 지원을 받고 있습니다.

CI/CD의 장점

빠른 피드백
코드 변경사항에 대한 빌드와 테스트 결과를 즉시 확인할 수 있어 문제를 빠르게 발견하고 수정할 수 있습니다.

품질 향상
자동화된 테스트를 통해 코드 품질을 지속적으로 검증하고 버그를 조기에 발견할 수 있습니다.

배포 위험 감소
작은 단위의 변경사항을 자주 배포함으로써 각 배포의 위험도를 낮출 수 있습니다.

개발 효율성 증대
반복적인 빌드, 테스트, 배포 작업을 자동화하여 개발자가 핵심 개발 업무에 집중할 수 있습니다.

일관된 환경
동일한 파이프라인을 통해 개발, 테스트, 프로덕션 환경에 일관되게 배포할 수 있습니다.

Jenkins의 주요 구성 요소

Job/Project
빌드, 테스트, 배포 등의 작업을 정의하는 단위입니다. Freestyle Project, Pipeline Project 등 다양한 타입이 있습니다.

Build
Job의 실행 인스턴스입니다. 각 빌드는 고유한 번호를 가지며 실행 결과와 로그를 저장합니다.

Workspace
Job이 실행되는 작업 공간으로, 소스 코드가 체크아웃되고 빌드 과정이 수행되는 디렉토리입니다.

Node/Agent
빌드 작업을 실행하는 서버입니다. 마스터 노드와 여러 개의 슬레이브 노드로 구성할 수 있습니다.

Plugin
Jenkins의 기능을 확장하는 모듈입니다. 다양한 도구와의 연동, 알림, 보고서 생성 등의 기능을 제공합니다.

Jenkins 설치하기

1단계: Jenkins GPG 키 가져오기

Jenkins 패키지의 무결성과 인증을 위해 GPG 키를 시스템에 추가합니다.

# Jenkins GPG 키 가져오기
curl -fsSL https://pkg.jenkins.io/debian/jenkins.io-2023.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc > /dev/null

명령어 분석

• curl -fsSL: 조용히(-s) 실패 시 오류 표시(-f) 리다이렉트 따라가기(-L)
• tee: 출력을 파일에 저장하면서 동시에 stdout으로도 전달
• > /dev/null: 터미널 출력 숨기기

2단계: Jenkins 저장소 추가

시스템의 패키지 저장소 목록에 Jenkins 저장소를 추가합니다.

# Jenkins 저장소 추가
echo deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

설정 내용 설명

• signed-by: 앞서 추가한 GPG 키로 패키지 서명 검증
• jenkins.list: Jenkins 전용 저장소 설정 파일

3단계: 패키지 목록 업데이트 및 Jenkins 설치

# 패키지 목록 업데이트
sudo apt update

# Jenkins 설치
sudo apt install jenkins -y

Jenkins 설치 시 함께 설치되는 구성요소:

• Java Runtime Environment (JRE)
• Jenkins 웹 서버
• 기본 플러그인 세트
• 시스템 서비스 등록

4단계: Jenkins 서비스 시작 및 활성화

# Jenkins 시작
sudo systemctl start jenkins

# 부팅 시 자동 시작 설정
sudo systemctl enable jenkins

# 서비스 상태 확인
sudo systemctl status jenkins

서비스 관리 명령어

• start: 서비스 즉시 시작
• enable: 시스템 부팅 시 자동 시작
• status: 현재 서비스 상태 확인

Jenkins 초기 설정

1단계: 방화벽 설정

Jenkins는 기본적으로 8080 포트를 사용하므로 해당 포트를 개방해야 합니다.

# Jenkins 방화벽 해제
sudo ufw allow 8080

# 방화벽 상태 확인
sudo ufw status

2단계: 초기 관리자 비밀번호 확인

Jenkins 설치 시 자동으로 생성되는 초기 관리자 비밀번호를 확인합니다.

# Jenkins 초기 비밀번호 확인 및 복사
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

보안상 주의사항

• 이 비밀번호는 초기 설정 후 삭제됩니다
• 반드시 안전한 곳에 임시 저장해두세요
• 초기 설정 완료 후 새로운 관리자 계정을 생성하게 됩니다

3단계: 공인 IP 주소 확인

EC2 인스턴스의 공인 IP 주소를 확인하여 Jenkins에 접속합니다.

# 할당된 공인 IP 조회
curl ifconfig.me

대안 명령어

# 다른 방법들
curl ipinfo.io/ip
curl ipecho.net/plain
wget -qO- ifconfig.co

4단계: Jenkins 웹 인터페이스 접속

웹 브라우저에서 다음 주소로 접속합니다:

http://<EC2_PUBLIC_IP>:8080

초기 설정 과정
1. Unlock Jenkins: 앞서 확인한 초기 비밀번호 입력
2. Customize Jenkins: 플러그인 설치 방식 선택

• Install suggested plugins (권장)
• Select plugins to install (수동 선택)

3. Create First Admin User: 관리자 계정 생성
4. Instance Configuration: Jenkins URL 설정
5. Jenkins is ready!: 설정 완료

GitLab 연동 설정

1단계: GitLab 플러그인 설치

Jenkins 웹 인터페이스에서 GitLab 플러그인을 설치합니다.

설치 경로
1. Jenkins Dashboard → Manage Jenkins → Manage Plugins
2. Available 탭에서 "gitlab" 검색
3. GitLab Plugin 선택 및 설치
4. Restart Jenkins when installation is complete 체크

주요 GitLab 관련 플러그인

• GitLab Plugin: GitLab과의 기본 연동
• GitLab API Plugin: GitLab API 호출 지원
• GitLab Branch Source Plugin: 멀티브랜치 파이프라인 지원

2단계: GitLab Access Token 발급

GitLab에서 Jenkins가 사용할 API 토큰을 생성합니다.

토큰 생성 과정
1. GitLab에 로그인 후 User Settings → Access Tokens
2. Token name 입력 (예: "Jenkins Integration")
3. Expiration date 설정 (선택사항)
4. Scopes 선택:

• api: 전체 API 접근
• read_user: 사용자 정보 읽기
• read_repository: 저장소 읽기
• write_repository: 저장소 쓰기 (webhook 등록용)

5. Create personal access token 클릭
6. 생성된 토큰을 안전한 곳에 저장 (재확인 불가)

토큰 보안 관리

• 토큰은 한 번만 표시되므로 즉시 안전한 곳에 저장
• 정기적으로 토큰 갱신 (보안 강화)
• 최소 필요 권한만 부여 (Principle of Least Privilege)

3단계: Jenkins Credential 추가

Jenkins에서 GitLab API 토큰을 안전하게 저장하기 위해 Credential을 생성합니다.

Credential 생성 과정
1. Jenkins Dashboard → Manage Jenkins → Manage Credentials
2. Global credentials (unrestricted) → Add Credentials
3. Kind: "GitLab API token" 선택
4. API token: 앞서 생성한 GitLab Access Token 입력
5. ID: 식별하기 쉬운 이름 (예: "gitlab-api-token")
6. Description: 토큰 설명 (예: "GitLab API Token for CI/CD")
7. OK 클릭하여 저장

Credential 타입별 용도

• GitLab API token: GitLab API 호출용
• Username with password: 기본 인증용
• SSH Username with private key: SSH 키 기반 인증용
• Secret text: 단순 텍스트 시크릿용

4단계: GitLab Connection 설정

Jenkins에서 GitLab 서버와의 연결을 설정합니다.

연결 설정 과정
1. Jenkins Dashboard → Manage Jenkins → Configure System
2. GitLab 섹션으로 이동
3. Add GitLab Server 클릭
4. 다음 정보 입력:

• Name: 연결 이름 (예: "GitLab Server")
• GitLab host URL: GitLab 서버 URL (예: https://gitlab.com)
• Credentials: 앞서 생성한 GitLab API token credential 선택

5. Test Connection 클릭하여 연결 테스트
6. Save 클릭하여 설정 저장

연결 테스트 결과

• Success: 연결 성공, 정상적으로 GitLab API 호출 가능
• Failed: 연결 실패, 토큰이나 URL 확인 필요

Webhook 설정

1단계: Jenkins Job 생성

GitLab과 연동할 Jenkins Job을 생성합니다.

Job 생성 과정
1. Jenkins Dashboard → New Item
2. Item name 입력 (예: "MyProject-CI")
3. Freestyle project 또는 Pipeline 선택
4. OK 클릭

Job 타입별 특징

• Freestyle project: GUI 기반의 간단한 설정
• Pipeline: 코드 기반의 복잡한 워크플로우 정의 가능
• Multibranch Pipeline: 여러 브랜치를 자동으로 감지하여 파이프라인 실행

2단계: Job Configuration - Build Triggers 설정

설정 경로
1. 생성한 Job → Configure
2. Build Triggers 섹션으로 이동
3. Build when a change is pushed to GitLab 체크

고급 설정
1. Advanced 버튼 클릭
2. Secret token → Generate 클릭
3. 생성된 토큰을 안전한 곳에 저장 (GitLab Webhook 설정 시 사용)

추가 트리거 옵션

• Push Events: 코드 푸시 시 빌드 실행
• Merge Request Events: 머지 리퀘스트 생성/업데이트 시 빌드 실행
• Note Events: 코멘트 추가 시 빌드 실행
• Tag Push Events: 태그 푸시 시 빌드 실행

3단계: GitLab Webhook 설정

GitLab 저장소에서 Jenkins로 이벤트를 전송하는 Webhook을 설정합니다.

Webhook 설정 과정
1. GitLab 프로젝트 → Settings → Webhooks
2. URL 입력: http://<JENKINS_URL>/project/<JOB_NAME>

• 예: http://your-jenkins-server:8080/project/MyProject-CI

3. Secret token: Jenkins에서 생성한 Secret token 입력
4. Trigger 선택:
   • Push events: 코드 푸시 시
   • Tag push events: 태그 푸시 시
   • Merge request events: 머지 리퀘스트 시
5. SSL verification 설정 (HTTPS 사용 시)
6. Add webhook 클릭

Webhook URL 형식

• Freestyle Job: http://<jenkins-url>/project/<job-name>
• Pipeline Job: http://<jenkins-url>/project/<job-name>
• Multibranch Pipeline: http://<jenkins-url>/multibranch-webhook-trigger/invoke?token=<token>

4단계: Webhook 테스트

테스트 방법
1. GitLab Webhook 설정 페이지에서 Test → Push events 클릭
2. Jenkins Job 페이지에서 빌드가 자동으로 시작되는지 확인
3. 실제 코드를 푸시하여 자동 빌드 동작 확인

트러블슈팅

• 403 Forbidden: Jenkins CSRF 보호 설정 확인
• 404 Not Found: Webhook URL 확인
• Connection timeout: 네트워크 및 방화벽 설정 확인

마치며

Jenkins를 활용한 CI/CD 파이프라인 구축을 통해 개발 프로세스를 대폭 개선할 수 있습니다. 자동화된 빌드, 테스트, 배포 과정을 통해 개발 효율성을 높이고 코드 품질을 향상시킬 수 있습니다.