🤵
Jenkins 치트시트

엔터프라이즈 CI/CD 자동화 서버 완벽 가이드: Docker 기반 설치 및 초기 설정, Declarative Pipeline 문법 구조, Controller-Agent 분산 아키텍처, 환경변수 및 Credentials 관리, Docker 컨테이너 에이전트 빌드, 파라미터 빌드, 수동 승인(Input) 배포, 슬랙 알림 및 프로덕션 운영 체크리스트
#jenkins#cicd#devops#pipeline#jenkinsfile#docker#automation#build#deployment최종 업데이트: 2026-10-08
Jenkins 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

Jenkins는 전 세계 엔터프라이즈 환경에서 가장 널리 사용되는 오픈소스 지속적 통합/지속적 배포(CI/CD) 자동화 서버입니다. Java 17 또는 21 LTS 런타임 환경에서 동작하며, Docker 컨테이너로 설치하는 방식이 가장 안전하고 빠릅니다.

### 🐳 1. Docker로 1분 만에 Jenkins 설치 및 실행 (강력 권장)
호스트 OS에 Java를 직접 설치하지 않고 격리된 컨테이너 환경으로 실행합니다:

```bash
# 1. 영구 데이터 저장을 위한 Docker 볼륨 생성
docker volume create jenkins_home

# 2. Jenkins LTS 컨테이너 실행
# 8080: 웹 대시보드 포트
# 50000: 인바운드 에이전트 연결 포트
# /var/run/docker.sock: 컨테이너 내부에서 호스트 Docker를 사용하기 위한 마운트
docker run -d \
  --name jenkins \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  jenkins/jenkins:lts-jdk17

# 3. 컨테이너 정상 구동 확인
docker ps | grep jenkins
```

### ☕ 2. OS 네이티브 설치 (Linux/Ubuntu 환경)
서버에 직접 설치해야 하는 경우 Java 17 LTS를 먼저 설치합니다:

```bash
# 1. OpenJDK 17 LTS 설치
sudo apt update
sudo apt install -y openjdk-17-jdk

# 2. Jenkins 공식 저장소 키 및 패키지 목록 추가
sudo wget -O /usr/share/keyrings/jenkins-keyring.asc https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

# 3. Jenkins 설치 및 서비스 시작
sudo apt update
sudo apt install -y jenkins
sudo systemctl enable --now jenkins
sudo systemctl status jenkins
```

### 🔑 3. 초기 관리자 비밀번호 확인 및 웹 UI 접속
웹 브라우저에서 `http://localhost:8080` (또는 서버 IP)로 접속한 뒤 초기 비밀번호를 입력합니다:

```bash
# Docker 컨테이너인 경우:
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

# Linux 네이티브 설치인 경우:
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
# 출력 예시: 4a2b9f8e1c3d4e5a6b7c8d9e0f1a2b3c
```

### 🧩 4. 플러그인 설치 & 관리자 계정 생성
1. 웹 UI에서 **"Install suggested plugins"** (권장 플러그인 설치)를 클릭하여 Git, Pipeline, Workspace Cleanup, SSH Build Agents 등을 자동 설치합니다.
2. 추가 필수 플러그인 검색 설치 (`Jenkins 관리` ➔ `Plugins` ➔ `Available plugins`):
   - **Docker Pipeline**: 파이프라인 내부에서 Docker 컨테이너를 빌드 에이전트로 활용
   - **Credentials Binding**: API 키, 토큰, 비밀번호를 안전하게 파이프라인에 바인딩
   - **Slack Notification**: 빌드 결과 및 승인 요청 슬랙 채널 알림

---

## 2. Jenkins 핵심 아키텍처 & 멘탈 모델 (Mental Model)

Jenkins는 대규모 엔터프라이즈 빌드를 감당할 수 있도록 **Controller-Agent 분산 아키텍처**와 **선언적 파이프라인(Declarative Pipeline)** 구조를 채택하고 있습니다.

### 🏢 Controller-Agent 분산 아키텍처
```text
┌────────────────────────────────────────────────────────────────┐
│                   Jenkins Controller (Master)                  │
│  - 웹 대시보드 UI 제공, 파이프라인 스케줄링 및 빌드 트리거 모니터링  │
│  - Credentials 저장소 관리, 플러그인 관리, 빌드 기록/로그 아카이빙   │
│  ※ [원칙] Controller 노드 자체에서는 무거운 빌드/컴파일 작업을 금지함 │
└──────────────┬──────────────────────────────┬──────────────────┘
               │ (SSH / Inbound JNLP 포트 50000)
               ▼                              ▼
┌───────────────────────────────┐  ┌───────────────────────────────┐
│     Build Agent #1 (Linux)    │  │     Build Agent #2 (Docker)   │
│  - Gradle / Maven 빌드 실행   │  │  - Node.js 프론트엔드 빌드    │
│  - 단위 테스트 & 정적 분석     │  │  - 컨테이너 이미지 빌드/푸시  │
└───────────────────────────────┘  └───────────────────────────────┘
```

### 🔄 Declarative Pipeline 생명주기 흐름
```text
[빌드 트리거: Git Webhook / Poll SCM / 수동 실행]
       │
       ▼
 1. pipeline
       │
       ▼
 2. agent (어느 노드 또는 도커 컨테이너에서 실행할 것인가?)
       │
       ▼
 3. stages (순차적으로 실행될 단계 묶음)
       ├─ Stage 1: Checkout (Git 저장소 소스코드 복제)
       ├─ Stage 2: Build & Test (컴파일, 단위 테스트)
       ├─ Stage 3: SonarQube Scan (코드 품질 정적 분석)
       ├─ Stage 4: Docker Image Build & Push (레지스트리 등록)
       └─ Stage 5: Deploy (서버 배포 / K8s 매니페스트 갱신)
       │
       ▼
 4. post (결과 후속 조치)
       ├─ always: 워크스페이스 정리(cleanWs)
       ├─ success: 성공 로그 및 알림 전송
       └─ failure: 오류 로그 덤프 및 개발팀 슬랙 긴급 알림
```

---

## 3. [초보자 1단계] 헬로월드: 최소 동작 선언적 파이프라인

복잡한 설정 없이 Jenkins 웹 대시보드에서 1분 만에 생성하고 실행할 수 있는 최소 Declarative Pipeline 예제입니다.

### 📝 파이프라인 생성 순서
1. Jenkins 대시보드 좌측 상단 **"새로운 Item" (New Item)** 클릭
2. Item 이름 입력: `hello-world-pipeline` ➔ **"Pipeline"** 선택 ➔ **"OK"** 클릭
3. 페이지 하단 **Pipeline** 섹션 ➔ Definition: `Pipeline script` 선택
4. 아래 스크립트를 입력란에 복사하여 붙여넣고 **"저장" (Save)** 클릭:

```groovy
// 최소 동작 Declarative Pipeline
pipeline {
    // 1. 빌드를 실행할 에이전트 지정 (any: 사용 가능한 아무 에이전트에서나 실행)
    agent any

    // 2. 실행 옵션 지정
    options {
        timeout(time: 10, unit: 'MINUTES') // 10분 초과 시 자동 중단
        timestamps()                        // 로그에 타임스탬프 기록
    }

    // 3. 순차적으로 실행될 단계 정의
    stages {
        stage('준비 & 환경 확인') {
            steps {
                echo '=== [Stage 1] 빌드 환경 정보 출력 ==='
                sh 'node -v || true'
                sh 'java -version || true'
                sh 'echo "현재 작업 디렉토리: $WORKSPACE"'
            }
        }

        stage('애플리케이션 테스트') {
            steps {
                echo '=== [Stage 2] 모의 테스트 수행 중 ==='
                sh 'echo "테스트 스위트 실행 완료: 성공 (0 실패)"'
            }
        }

        stage('배포 준비') {
            steps {
                echo '=== [Stage 3] 헬로월드 배포 완료 ==='
                echo "빌드 번호: ${BUILD_NUMBER}"
                echo "잡 이름: ${JOB_NAME}"
            }
        }
    }

    // 4. 모든 단계 종료 후 실행될 후속 조치
    post {
        always {
            echo '파이프라인 실행이 완료되었습니다 (성공/실패 여부 무관).'
        }
        success {
            echo '🎉 축하합니다! 모든 단계가 정상 통과되었습니다.'
        }
        failure {
            echo '🚨 파이프라인 실행 중 오류가 발생했습니다.'
        }
    }
}
```

### 💻 실행 및 콘솔 출력 결과 확인
좌측 메뉴의 **"지금 빌드" (Build Now)** 를 클릭하면 빌드가 시작됩니다. 생성된 `#1` 빌드를 클릭하고 **"Console Output"** 을 확인합니다:

```text
[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /var/jenkins_home/workspace/hello-world-pipeline
[Pipeline] {
[Pipeline] stage
[Pipeline] { (준비 & 환경 확인)
[Pipeline] echo
=== [Stage 1] 빌드 환경 정보 출력 ===
[Pipeline] sh
+ echo "현재 작업 디렉토리: /var/jenkins_home/workspace/hello-world-pipeline"
현재 작업 디렉토리: /var/jenkins_home/workspace/hello-world-pipeline
[Pipeline] }
[Pipeline] stage
[Pipeline] { (애플리케이션 테스트)
[Pipeline] echo
=== [Stage 2] 모의 테스트 수행 중 ===
[Pipeline] sh
+ echo "테스트 스위트 실행 완료: 성공 (0 실패)"
테스트 스위트 실행 완료: 성공 (0 실패)
[Pipeline] }
[Pipeline] stage
[Pipeline] { (배포 준비)
[Pipeline] echo
=== [Stage 3] 헬로월드 배포 완료 ===
[Pipeline] echo
빌드 번호: 1
[Pipeline] echo
잡 이름: hello-world-pipeline
[Pipeline] }
[Pipeline] { (Declarative: Post Actions)
[Pipeline] echo
파이프라인 실행이 완료되었습니다 (성공/실패 여부 무관).
[Pipeline] echo
🎉 축하합니다! 모든 단계가 정상 통과되었습니다.
[Pipeline] }
Finished: SUCCESS
```

---

## 4. [초보자 2단계] 핵심 기능 & 파이프라인 문법 (Jenkinsfile)

실무 표준 방식은 저장소 루트에 `Jenkinsfile`을 작성하여 Git으로 버전 관리하는 방식(Pipeline-as-Code)입니다.

### 🧱 1. Declarative Pipeline 5대 핵심 블록
| 지시어 (Directive) | 역할 및 설명 |
| :--- | :--- |
| **`pipeline { ... }`** | 선언적 파이프라인의 시작과 끝을 감싸는 필수 최상위 블록 |
| **`agent`** | 파이프라인 또는 개별 Stage를 실행할 노드 지정 (`any`, `none`, `label`, `docker`) |
| **`stages`** | 실제 빌드 로직을 담는 하나 이상의 `stage`들을 포함하는 컨테이너 |
| **`steps`** | 각 stage 내부에서 실제로 수행되는 명령 단위 (`sh`, `bat`, `echo`, `checkout` 등) |
| **`post`** | 파이프라인 또는 Stage 종료 시점의 조건부 후속 조치 (`always`, `success`, `failure`, `changed`) |

### 🔑 2. 환경변수(Environment) & Credentials 안전 바인딩
비밀번호, API 토큰, SSH Key는 절대 코드에 하드코딩하지 않고 Jenkins Credentials Store에 등록 후 바인딩합니다.

```groovy
pipeline {
    agent any

    environment {
        // 일반 환경변수 정의
        APP_NAME = 'lucky-backend'
        PROFILE = 'production'

        // Jenkins Credentials Store의 비밀값을 환경변수로 주입
        // (ID가 'dockerhub-creds'인 Username/Password 자격증명)
        DOCKER_CREDS = credentials('dockerhub-creds')
        // DOCKER_CREDS_USR (아이디), DOCKER_CREDS_PSW (비밀번호) 자동 생성 및 콘솔 마스킹(****)

        // Secret Text(비밀 텍스트) 주입
        SLACK_TOKEN = credentials('slack-webhook-token')
    }

    stages {
        stage('자격증명 활용') {
            steps {
                sh '''
                    echo "애플리케이션: ${APP_NAME} (${PROFILE})"
                    # Jenkins 콘솔 출력 시 비밀번호는 자동으로 **** 로 마스킹됩니다.
                    echo "Docker Hub 사용자: ${DOCKER_CREDS_USR}"
                '''
            }
        }
    }
}
```

### 🎛️ 3. 파라미터 빌드 (Parameters)
빌드 실행 시 사용자로부터 브랜치명, 배포 환경, 롤백 여부 등을 입력받습니다.

```groovy
pipeline {
    agent any

    parameters {
        choice(name: 'ENVIRONMENT', choices: ['dev', 'staging', 'prod'], description: '배포할 대상 환경')
        string(name: 'GIT_BRANCH', defaultValue: 'main', description: '체크아웃할 Git 브랜치 또는 태그')
        booleanParam(name: 'RUN_MIGRATION', defaultValue: false, description: 'DB 마이그레이션 실행 여부')
    }

    stages {
        stage('파라미터 확인') {
            steps {
                echo "선택한 대상 환경: ${params.ENVIRONMENT}"
                echo "빌드 대상 브랜치: ${params.GIT_BRANCH}"
                echo "DB 마이그레이션 적용: ${params.RUN_MIGRATION}"
            }
        }
    }
}
```

### 🚦 4. 실행 조건문 (When)
특정 브랜치일 때만 배포하거나, 파라미터 조건에 따라 Stage를 건너뜁니다.

```groovy
stage('운영 서버 배포') {
    // main 브랜치이고 ENVIRONMENT 파라미터가 'prod'일 때만 이 단계를 실행
    when {
        allOf {
            branch 'main'
            environment name: 'ENVIRONMENT', value: 'prod'
        }
    }
    steps {
        echo '운영 서버(Production) 배포 스크립트를 실행합니다.'
        sh './scripts/deploy-prod.sh'
    }
}
```

### ⚡ 5. 병렬 실행 (Parallel)
독립적인 작업(단위 테스트, 정적 코드 분석, E2E 테스트)을 동시에 병렬로 실행하여 빌드 시간을 획기적으로 단축합니다.

```groovy
stage('품질 검증 (병렬 실행)') {
    parallel {
        stage('단위 테스트') {
            steps {
                echo 'JUnit 단위 테스트 실행...'
                sh './gradlew test'
            }
        }
        stage('정적 코드 분석') {
            steps {
                echo 'SonarQube 품질 게이트 검증...'
                sh './gradlew sonar'
            }
        }
        stage('보안 취약점 점검') {
            steps {
                echo 'Trivy 컨테이너 취약점 스캔...'
                sh 'trivy fs --severity HIGH,CRITICAL .'
            }
        }
    }
}
```

---

## 5. [초보자 3단계] 실무 응용 패턴 & 프로덕션 파이프라인

실무 서비스에서 사용하는 Docker 컨테이너 에이전트 기반 빌드, 승인 후 배포, 슬랙 알림을 포함한 완전한 `Jenkinsfile` 예제입니다.

### 📄 실전 프로덕션 `Jenkinsfile` (복사해서 바로 사용 가능)
```groovy
pipeline {
    // 모든 Stage를 Docker 컨테이너 격리 환경에서 빌드
    agent {
        docker {
            image 'gradle:8.5-jdk17-alpine'
            args '-v /root/.gradle:/root/.gradle' // Gradle 종속성 캐싱 마운트
        }
    }

    options {
        // 최근 10개 빌드만 보관하여 디스크 용량 고갈 방지 (매우 중요)
        buildDiscarder(logRotator(numToKeepStr: '10', artifactNumToKeepStr: '5'))
        disableConcurrentBuilds() // 동일 잡 동시 실행 방지
        timeout(time: 30, unit: 'MINUTES')
        timestamps()
    }

    environment {
        DOCKER_REGISTRY = 'registry.luckytech.world'
        IMAGE_NAME = 'lucky-service'
        IMAGE_TAG = "${env.BUILD_NUMBER}-${env.GIT_COMMIT.take(7)}"
        DOCKER_CRED_ID = 'harbor-registry-creds'
    }

    stages {
        stage('소프트웨어 빌드') {
            steps {
                echo "=== 1. Gradle 빌드 및 아티팩트 컴파일 ==="
                sh 'gradle clean build -x test --no-daemon'
            }
        }

        stage('단위 테스트 & 보고서 수집') {
            steps {
                echo "=== 2. 단위 테스트 실행 및 결과 리포팅 ==="
                sh 'gradle test --no-daemon'
            }
            post {
                always {
                    // JUnit 테스트 결과 XML을 수집하여 Jenkins 대시보드 그래프로 표현
                    junit allowEmptyResults: true, testResults: '**/build/test-results/**/*.xml'
                }
            }
        }

        stage('Docker 이미지 빌드 & 레지스트리 푸시') {
            // Docker 데몬 명령어를 실행하기 위해 호스트 노드 에이전트 전환
            agent any
            steps {
                echo "=== 3. 도커 이미지 빌드: ${DOCKER_REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} ==="
                script {
                    docker.withRegistry("https://${DOCKER_REGISTRY}", DOCKER_CRED_ID) {
                        def customImage = docker.build("${DOCKER_REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}", ".")
                        customImage.push()
                        customImage.push("latest")
                    }
                }
            }
        }

        stage('개발 환경(Dev) 자동 배포') {
            agent any
            steps {
                echo "=== 4. 개발 쿠버네티스 클러스터 롤아웃 ==="
                sh """
                    kubectl set image deployment/lucky-service lucky-service=${DOCKER_REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} -n dev
                    kubectl rollout status deployment/lucky-service -n dev --timeout=2m
                """
            }
        }

        stage('운영 배포 관리자 승인') {
            // main 브랜치일 때만 승인 단계 활성화
            when {
                branch 'main'
            }
            agent none
            steps {
                // 관리자가 웹 UI에서 [승인(Proceed)] 버튼을 클릭할 때까지 파이프라인 대기
                input message: "운영 서버(Prod)로 [${IMAGE_TAG}] 버전을 배포하시겠습니까?", ok: '승인 및 배포'
            }
        }

        stage('운영 환경(Prod) 배포') {
            when {
                branch 'main'
            }
            agent any
            steps {
                echo "=== 5. 운영 쿠버네티스 클러스터 무중단 배포 ==="
                sh """
                    kubectl set image deployment/lucky-service lucky-service=${DOCKER_REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} -n prod
                    kubectl rollout status deployment/lucky-service -n prod --timeout=5m
                """
            }
        }
    }

    post {
        always {
            // 워크스페이스 정리로 디스크 용량 확보
            cleanWs()
        }
        success {
            echo "🎉 [${JOB_NAME} #${BUILD_NUMBER}] 파이프라인이 성공적으로 완료되었습니다."
            // 슬랙 알림 연동 예시:
            // slackSend channel: '#deploy-alerts', color: 'good', message: "SUCCESS: ${JOB_NAME} #${BUILD_NUMBER} 배포 완료 (<${BUILD_URL}|로그 확인>)"
        }
        failure {
            echo "🚨 [${JOB_NAME} #${BUILD_NUMBER}] 빌드 또는 배포에 실패하였습니다!"
            // slackSend channel: '#deploy-alerts', color: 'danger', message: "FAILED: ${JOB_NAME} #${BUILD_NUMBER} 오류 발생 (<${BUILD_URL}|원인 확인>)"
        }
    }
}
```

---

## 6. 실무 주의사항 & 프로덕션 체크리스트

### ⚠️ 1. 초보자가 가장 흔히 겪는 실수 & 해결법

| 번호 | 흔한 에러 및 증상 | 근본 원인 | 해결 방법 |
| :---: | :--- | :--- | :--- |
| **1** | `No space left on device` (디스크 가득 참) | 이전 빌드 기록과 작업 공간(workspace) 파일이 무한정 누적됨 | 파이프라인 상단에 `options { buildDiscarder(logRotator(numToKeepStr: '10')) }` 설정 및 `post { always { cleanWs() } }` 필수 적용 |
| **2** | `Got permission denied while trying to connect to Docker daemon socket` | Jenkins 실행 사용자가 `/var/run/docker.sock` 접근 권한이 없음 | `sudo chmod 666 /var/run/docker.sock` 임시 해결 또는 `sudo usermod -aG docker jenkins` 후 Jenkins 재시작 |
| **3** | Controller 노드에서 직접 빌드 실행으로 Jenkins 웹 UI 멈춤 | 분산 에이전트 미구성 상태에서 Controller 노드의 CPU/메모리 고갈 | `Jenkins 관리` ➔ `Nodes`에서 `Built-In Node`의 실행자(Executors) 수를 `0`으로 지정하여 빌드 전용 에이전트로만 실행 유도 |
| **4** | Credentials 토큰이 콘솔 로그에 노출됨 | 평문 환경변수로 주입하거나 `sh` 명령에서 echo로 출력 | `withCredentials` 또는 `credentials('id')`를 사용하면 Jenkins가 콘솔 출력 시 `****`로 자동 마스킹함 |
| **5** | 플러그인 업데이트 후 Jenkins 먹통 현상 | 호환성 검증되지 않은 메이저 플러그인 일괄 업데이트 | Jenkins LTS 버전 업그레이드 전 `/var/jenkins_home` 전체 볼륨 스냅샷 백업 필수 |

### 🛡️ 2. 프로덕션 보안 & 운영 권장 체크리스트
1. **CSRF Protection & 사용자 인증 활성화**: 익명 사용자(Anonymous)의 읽기 권한을 기본 비활성화하고, Role-based Authorization Strategy 플러그인으로 RBAC 권한을 구성합니다.
2. **다중 브랜치 파이프라인(Multibranch Pipeline)**: 개별 잡 대신 Multibranch Pipeline을 사용하면, 신규 PR이나 브랜치가 생성될 때 자동으로 Jenkinsfile을 감지하여 빌드/테스트를 수행합니다.
3. **Jenkinsfile의 버전 관리**: UI 내부 스크립트(Pipeline script) 작성 방식을 지양하고, 반드시 Git 저장소 최상단 `Jenkinsfile`로 형상 관리(SCM)를 수행합니다.
4. **타임아웃(Timeout) 필수 지정**: 네트워크 지연이나 대기 상태로 인해 빌드가 영구 정체되는 현상을 방지하기 위해 전체 파이프라인 및 단계별 `timeout`을 명시합니다.

### 📋 3. Declarative Pipeline 핵심 지시어 빠른 요약

```groovy
pipeline {
    agent { label 'linux-node' }       // 빌드 실행 노드 라벨 지정
    environment { KEY = 'VALUE' }      // 전역 환경변수 지정
    options { timeout(30); timestamps() } // 타임아웃 및 타임스탬프
    triggers { cron('H 2 * * *') }      // 매일 새벽 2시 정기 자동 빌드
    parameters { string(name: 'TAG') }  // 수동 빌드 파라미터 수신
    stages {
        stage('Step 1') {
            when { branch 'release/*' } // 릴리즈 브랜치 조건부 실행
            steps { sh './deploy.sh' }  // 셸 스크립트 실행
        }
    }
    post {
        failure { echo '알림 전송' }   // 실패 시 실행 블록
    }
}
```
💬
Jenkins 치트시트

의견 및 질문

댓글 수정

댓글 삭제
