[Jenkins] Pipeline의 시작 Scripted vs Declarative 문법 완벽 가이드

과거의 젠킨스는 '마우스 클릭'으로 모든 것을 설정하는 Freestyle Project가 주류였습니다. 하지만 마이크로서비스 아키텍처(MSA)가 도입되고 배포 파이프라인이 수십 개의 스테이지로 복잡해지면서, 더 이상 GUI 화면만으로는 분기 처리나 예외 처리 같은 고도화된 로직을 감당할 수 없게 되었습니다. 그래서 등장한 것이 바로 '코드로 파이프라인을 작성(Pipeline as Code)'하는 방식입니다.

본 가이드에서는 젠킨스 파이프라인 구축의 기초부터 실무 핵심 요소인
1) Scripted vs Declarative 문법 비교,
2) Jenkinsfile을 활용한 형상 관리(IaC),
3) Docker 기반 격리 에이전트(Agent) 설정,
4) 보안 자격 증명(Credentials)과 환경변수(Environment Variables),
5) 휴먼 에러를 차단하는 매개변수(Parameters) 설정까지 단 하나의 포스트로 완벽하게 정리합니다.

---

1. Scripted vs Declarative 문법 비교

파이프라인 플러그인이 처음 세상에 나왔을 때 도입된 1세대 문법이 바로 Scripted Pipeline입니다. 이는 순수한 Groovy(그루비) 프로그래밍 언어의 문법을 그대로 차용했습니다.

Scripted Pipeline: if-else 분기문, for 반복문, try-catch-finally를 통한 정교한 예외 처리가 가능하여 자유도가 무한대입니다. 그러나 정해진 규격이 없어 작성자마다 코드가 다르고 '스파게티 코드'가 되기 쉽습니다.

node('master') { // 워커 노드 지정
    stage('Checkout') {
        git 'https://github.com/my-repo.git'
    }
    stage('Build') {
        try {
            if (env.BRANCH_NAME == 'main') {
                sh 'npm run build:prod'
            } else {
                sh 'npm run build:dev'
            
        } catch(Exception e) {
            echo "빌드 중 치명적 에러 발생: ${e.message}"
            currentBuild.result = 'FAILURE'
        }
    }
}

Declarative Pipeline: 현대 실무의 압도적 표준입니다. pipeline 블록으로 시작하여 stages -> stage -> steps의 정형화된 구조를 강제하므로 누구든 가독성과 유지보수성이 뛰어난 파이프라인을 작성할 수 있습니다.

pipeline {
    agent any // 빌드를 수행할 노드 지정
    
    environment {
        APP_VERSION = '1.0.0'
    }
    
    stages {
        stage('Checkout') {
            steps {
                git 'https://github.com/my-repo.git'
            }
        }
        stage('Build') {
            when { branch 'main' }
            steps {
                sh 'npm run build:prod'
            }
        }
    }
    
    post {
        always {
            cleanWs() // Workspace 비우기
        }
        success {
            echo " 빌드 성공! 슬랙 알림 발송"
        }
        failure {
            echo " 빌드 실패! 담당자에게 메일 발송"
        }
    }
}

---

2. Jenkinsfile 기반 파이프라인 형상 관리(IaC)

젠킨스 웹 UI 텍스트 박스에 코드를 작성하면 히스토리 관리 불가능, 협업 불가, 브랜치별 대응 불가라는 치명적인 단점이 있습니다.

이 모든 문제를 단번에 해결하는 것이 Jenkinsfile입니다. 파이프라인 로직을 소스코드의 최상단 디렉터리에 물리적 파일로 위치시키고 GIT으로 관리하는 것이 핵심입니다. 이를 IaC (Infrastructure as Code)라고 부릅니다.

프로젝트 디렉터리 구조 예시:

my-awesome-project/
 src/                # 실제 애플리케이션 소스 코드
 package.json        # 의존성 관리 파일
 Dockerfile          # 컨테이너화 명세서
 Jenkinsfile         # 빌드 및 배포 파이프라인 명세서

Jenkins 설정 (Pipeline from SCM):

1. Pipeline Job 설정의 [Pipeline] 섹션으로 이동합니다.
2. Definition을 Pipeline script from SCM으로 변경합니다.
3. SCM을 GIT으로 선택하고 Repository URL 및 Credentials를 입력합니다.
4. Script Path에 Jenkinsfile 경로를 지정합니다.

---

3. Agent 설정 노하우 및 Docker 기반 멸균 환경

에이전트(Agent)는 파이프라인의 빌드 작업을 실행할 머신과 환경을 지정합니다.

• agent any: 아무 유휴 노드에 배정하므로 워커 노드 간 패키지 버전이 달라 무작위 빌드 에러가 발생할 수 있습니다.
• agent { label 'linux-node18' }: 특정 라벨의 노드로 고정하지만, 서버 내 수많은 패키지가 꼬이는 서버 환경 오염 문제가 발생합니다.
• agent { docker { image 'node:18-alpine' } } (Best Practice): 도커 컨테이너를 1회용 빌드 머신으로 활용합니다. 빌드 시작 시 깨끗한 컨테이너가 뜬 후 빌드가 종료되면 자동 삭제되므로 완벽하게 격리된 1회용 멸균 빌드 환경을 제공합니다.

pipeline {
    agent {
        docker {
            image 'node:18-alpine'
            args '-v $HOME/.npm:/root/.npm'
        }
    }
    stages {
        stage('Build and Test') {
            steps {
                sh 'node -v'
                sh 'npm ci'
                sh 'npm run build'
            }
        }
    }
}

---

4. 보안 자격 증명(Credentials)과 콘솔 로그 마스킹

비밀번호, API 키, SSH 인증키 등을 파이프라인에 평문으로 적어두는 하드코딩은 절대 금물입니다. 젠킨스는 AES 기반의 강력한 암호화 금고 기능인 Credentials Plugin을 제공합니다.

Credentials 바인딩 예시:

pipeline {
    agent any
    environment {
        // credentials() 내장 함수를 사용한 안전한 환경변수 바인딩
        AWS_ACCESS_KEY = credentials('aws-access-key-id')
        DOCKER_CREDS = credentials('docker-login-id')
    }
    stages {
        stage('Docker Push') {
            steps {
                // 로그인 시 평문 비밀번호가 콘솔 로그에 **** 로 마스킹 처리됨
                sh 'docker login -u ${DOCKER_CREDS_USR} -p ${DOCKER_CREDS_PSW}'
                sh 'docker push my-app:latest'
            }
        }
    }
}

---

5. 환경변수(Environment Variables) 및 문자열 보간법

파이프라인 코드 내의 하드코딩을 제거하고 유연한 로직을 만들기 위해 환경변수를 활용합니다.

• 전역 변수: 파이프라인 최상단 environment 블록에 선언하여 모든 stage에서 공유합니다.
• 지역 변수: 특정 stage 내부에만 선언하여 해당 스테이지 실행 동안만 유지시킵니다.
• 내장 변수 (Built-in): env.BUILD_NUMBER, env.BRANCH_NAME, env.WORKSPACE, env.BUILD_URL 등을 적극 참조합니다.
• 따옴표 규칙: 변수 치환(Interpolation)을 위해서는 반드시 쌍따옴표(" ")를 사용해야 하며, 홑따옴표(' ') 사용 시 치환되지 않고 문자열 그대로 출력되니 주의해야 합니다.

---

6. 매개변수(Parameters) 설정 및 동적 배포

빌드 시점(Runtime)에 개발자나 운영자가 원하는 값을 선택하여 동적으로 파이프라인 흐름을 제어할 수 있습니다.

문자열 타이핑 방식(string)은 오타로 인한 휴먼 에러를 유발하므로, 실무에서는 choice(드롭다운)와 booleanParam(체크박스)을 권장합니다.

pipeline {
    agent any
    
    parameters {
        choice(name: 'TARGET_ENV', choices: ['DEV', 'STAGING', 'PROD'], description: '배포 대상 서버를 선택하세요.')
        booleanParam(name: 'RUN_UNIT_TESTS', defaultValue: true, description: '단위 테스트를 실행할까요?')
        string(name: 'RELEASE_VERSION', defaultValue: 'latest', description: '태깅할 앱 버전')
    }
    
    stages {
        stage('Unit Test') {
            when {
                expression { return params.RUN_UNIT_TESTS == true }
            }
            steps {
                sh 'npm run test'
            }
        }
        stage('Deploy') {
            steps {
                sh "echo '${params.TARGET_ENV} 서버로 배포 스크립트를 가동합니다.'"
            }
        }
    }
}

---

7. 마무리 및 핵심 요약

지금까지 Jenkins Pipeline의 문법 선택부터 Jenkinsfile 형상 관리, Docker Agent 멸균 환경, Credentials 보안, 환경변수 및 Parameters 활용법까지 파이프라인의 모든 전 과정을 체계적으로 정리해 보았습니다.
이 흐름을 이해하고 적용하면 대규모 엔터프라이즈 환경에서도 안전하고 유연한 무결점 CI/CD 파이프라인을 구축할 수 있습니다.