[Jenkins] 파이프라인 매개변수(Parameters) 설정의 정석 (휴먼 에러 완벽 차단)

앞선 11단계 포스팅에서 환경변수를 통해 파이프라인 내부의 하드코딩을 제거하는 방법을 배웠습니다. 하지만 실무에서는 코드를 수정하지 않고도, 빌드를 시작하는 그 순간(Runtime)에 개발자나 운영자가 원하는 값을 즉석에서 주입하여 파이프라인의 흐름을 바꾸고 싶을 때가 매우 많습니다. 예를 들어, 동일한 소스 코드를 가지고 DEV(개발) 서버에 배포할지, PROD(운영) 서버에 배포할지 선택해야 하는 상황 말입니다. 이것을 위해 똑같은 파이프라인을 2개 만드는 것은 끔찍한 비효율입니다.

이번 [Jenkins 실무 완벽 가이드] 시리즈에서는 하나의 Jenkinsfile로 다양한 배포 시나리오를 통제하고, 작업자의 오타로 인한 대형 사고를 원천 차단하는 파이프라인 매개변수(Parameters) 구성의 실무 정석을 3,000자에 걸쳐 아주 치밀하게 딥다이브 해보겠습니다.

🚨 1. String(문자열) 파라미터의 치명적 함정: 오타 한 번에 날아가는 서버

파라미터 빌드를 구성할 때 초보자들이 가장 많이 사용하는 것이 바로 string (문자열 입력칸) 매개변수입니다. 예를 들어 "배포할 환경을 적어주세요(dev/prod)"라고 안내 문구를 적어두고 빈칸을 뚫어두는 것입니다. 하지만 이는 실무 인프라 운영에서 절대 피해야 할 안티 패턴(Anti-Pattern)입니다.

금요일 저녁, 지친 개발자가 급하게 핫픽스(Hotfix)를 배포하려다가 dev라고 쳐야 할 것을 실수로 prod라고 쳐버렸다고 가정해봅시다. 혹은 PROD라고 대문자로 쳤는데 파이프라인에서는 소문자 prod만 인식하게 짜여있어서 엉뚱한 로직으로 흘러가 버립니다. 인프라 세계에서 자유 타이핑(Free Typing)은 곧 휴먼 에러(Human Error)의 근원입니다. 사용자가 고민할 필요 없이 정해진 선택지 안에서 고르도록 강제해야 합니다.

✅ 2. Choice(선택형)와 Boolean(체크박스) 파라미터 100% 활용하기

따라서 실무에서는 작업자의 실수를 원천 봉쇄하기 위해 choice와 booleanParam을 적극적으로 활용합니다.

1. Choice Parameter (드롭다운 선택형):
가장 많이 쓰이며, 가장 안전합니다. 작업자가 임의의 값을 칠 수 없으며, 인프라 관리자가 지정해둔 배열(Array) 중 무조건 하나만 선택하게 만듭니다. 주로 TARGET_ENV (배포 타겟 서버)나 AWS_REGION 등을 선택받을 때 씁니다.

2. Boolean Parameter (체크박스형):
스위치처럼 On/Off를 제어할 때 씁니다. 체크하면 true, 해제하면 false 값을 넘겨줍니다. 실무에서는 "DB 마이그레이션 스크립트를 이번 배포에 포함할 것인가?", "시간이 오래 걸리는 E2E 테스트를 스킵(Skip)할 것인가?" 등의 플래그(Flag) 옵션을 받을 때 아주 유용합니다.

3. String Parameter (제한적 사용):
어쩔 수 없이 자유 타이핑을 받아야 하는 경우에만 씁니다. 주로 새롭게 릴리즈할 도커 이미지의 특정 태그(예: v1.2.5)나 롤백할 특정 커밋 해시값을 넘겨받을 때 사용합니다.

💻 3. Declarative Pipeline 적용 코드 파헤치기

파이프라인 안에서 매개변수를 선언하려면 agent 지시어 아래에 parameters { ... } 블록을 열고 쏟아부어 주면 됩니다. 선언된 파라미터는 파이프라인의 steps 내부에서 params.변수명 형태로 안전하게 꺼내 쓸 수 있습니다.

pipeline {
    agent any
    
    // 이 블록에 정의된 내용은 젠킨스 웹 UI의 "Build with Parameters" 화면에 자동으로 폼(Form)을 만들어줍니다.
    parameters {
        // 선택형: 작업자는 이 3가지 값 중 하나만 드롭다운으로 고를 수 있음
        choice(name: 'TARGET_ENV', choices: ['DEV', 'STAGING', 'PROD'], description: '🔥 배포할 대상 서버를 정확히 선택하세요.')
        
        // 체크박스형: 기본값은 true로 세팅
        booleanParam(name: 'RUN_UNIT_TESTS', defaultValue: true, description: '✅ 소요 시간이 긴 단위 테스트를 실행할까요?')
        
        // 문자열형: 빌드에 꼬리표를 달 때 사용
        string(name: 'RELEASE_VERSION', defaultValue: 'latest', description: '📌 태깅할 앱 버전 (예: v2.3.1)')
    }
    
    stages {
        stage('Init') {
            steps {
                // 사용자가 폼에서 입력한 값은 params 객체 안에 담깁니다.
                echo "선택된 배포 타겟: ${params.TARGET_ENV}"
                echo "릴리즈 버전 명: ${params.RELEASE_VERSION}"
            }
        }
        
        stage('Unit Test') {
            // when 지시어와 결합: 사용자가 체크박스를 해제(false)했다면 이 스테이지는 통째로 스킵(Skip)됩니다!
            when {
                expression { return params.RUN_UNIT_TESTS == true }
            }
            steps {
                sh 'npm run test'
            }
        }
        
        stage('Deploy') {
            steps {
                // 선택된 환경에 따라 분기 처리되는 동적 배포 스크립트
                sh "echo '${params.TARGET_ENV} 서버로 배포 스크립트를 가동합니다...'"
                // sh "./deploy.sh ${params.TARGET_ENV}"
            }
        }
    }
}

⚠️ 4. 주의사항: 첫 번째 빌드의 딜레마 (First Build Issue)

파라미터가 포함된 Jenkinsfile을 Git에 푸시하고 젠킨스에서 처음으로 빌드를 돌리려 하면, 버튼 이름이 "Build with Parameters"가 아니라 그냥 "Build Now"로 나타나며 파라미터 팝업창이 뜨지 않을 것입니다.

원인: 젠킨스는 코드를 클론(Clone)받아서 Jenkinsfile을 직접 읽어봐야만 내부에 parameters 블록이 있다는 것을 인지할 수 있습니다. 즉, 최초 1회는 코드를 읽기 위한 깡통 빌드가 돌게 되며, 이 첫 빌드가 끝나야 비로소 젠킨스 UI에 파라미터 폼이 구성됩니다. (이는 젠킨스 아키텍처 특유의 현상으로 에러가 아닙니다.) 최초 1회 빌드가 실패하거나 끝난 후 새로고침을 하면 버튼이 정상적으로 바뀝니다.

🤖 5. 응용: Webhook으로 파라미터 넘기기

만약 Github Webhook을 통해 자동 빌드가 될 때는 팝업창을 누를 사람이 없는데 어떻게 될까요? 이때는 우리가 선언해 둔 defaultValue (기본값)를 가지고 파이프라인이 자동으로 돌아가게 됩니다. 혹은 Github Actions 등의 외부 툴에서 젠킨스 Webhook URL을 찌를 때, POST Payload의 쿼리 스트링(Query String)으로 파라미터 값을 직접 주입(Inject)하여 넘길 수도 있습니다. (예: http://jenkins.com/job/myjob/buildWithParameters?TARGET_ENV=DEV)

🎯 6. 마무리 및 다음 단계

지금까지 단일 파이프라인 코드로 무한한 배포 시나리오를 창출해 내고, 작업자의 실수를 원천 차단하는 매개변수(Parameters) 설정 기법에 대해 3,000자 분량으로 밀도 높게 다루어 보았습니다. 이제 여러분은 환경별로 Job을 여러 개 복사/붙여넣기 하던 구시대적인 방식에서 벗어나, 가장 우아하고 실무적인 IaC(인프라 코드화)를 실현하게 되었습니다.

우리는 파라미터를 통해 특정 스테이지(Stage)를 스킵(Skip)하는 조건부 로직을 잠깐 맛보았습니다. 파이프라인이 고도화될수록 "A 브랜치일 때만 테스트해라", "특정 환경변수가 존재할 때만 배포해라" 같은 정교한 조건 제어가 파이프라인의 핵심 경쟁력이 됩니다. 이어지는 13단계 포스팅에서는 Declarative Pipeline의 꽃이자, 강력한 논리 분기를 책임지는 `when` 조건문의 완벽한 활용법에 대해 아주 치밀하게 파헤쳐 보겠습니다!