[Jenkins] 환경변수(Environment Variables) 완벽 활용 가이드

개발을 하다 보면 코드 내부에 하드코딩(Hardcoding)된 값들은 언젠가 유지보수의 발목을 잡는 '기술 부채'가 된다는 것을 깨닫게 됩니다. 젠킨스 파이프라인(Jenkinsfile)도 마찬가지입니다. 특정 서버의 IP 주소, 배포할 애플리케이션의 버전 명, 혹은 알림을 보낼 슬랙 채널 이름 등을 파이프라인 곳곳에 하드코딩해둔다면, 해당 값이 변경될 때마다 수백 줄의 코드를 일일이 뒤져서 수정해야 하는 지옥을 맛보게 됩니다. 이번 [Jenkins 실무 완벽 가이드]에서는 이러한 비효율을 없애고 코드를 동적(Dynamic)이고 재사용 가능하게 만들어주는 환경변수(Environment Variables)의 모든 것을 3,000자 분량으로 아주 치밀하게 딥다이브 해보겠습니다.

🌐 1. Global vs Stage 스코프(Scope): 변수의 수명 통제하기

Declarative Pipeline에서 환경변수를 선언하는 방법은 아주 간단합니다. environment { ... } 블록 안에 키-값(Key-Value) 형태로 묶어주기만 하면 됩니다. 하지만 어느 위치에 선언하느냐에 따라 그 변수의 수명(Scope)이 완벽하게 달라집니다. 실무에서는 이 두 가지를 명확히 구분해서 사용해야 합니다.

1. 전역 환경변수 (Global Environment Variables)

파이프라인 최상단, 즉 agent 지시어 바로 아래에 선언하는 방식입니다. 여기서 정의된 변수는 파이프라인의 시작부터 끝까지 모든 스테이지(Stage)에서 공통으로 재사용될 수 있습니다. (예: APP_NAME, DOCKER_REGISTRY_URL 등)

2. 지역 환경변수 (Stage-level Environment Variables)

특정 stage 블록 내부에 선언하는 방식입니다. 이 변수는 오직 해당 스테이지가 실행되는 동안에만 존재하며, 스테이지가 끝나면 즉시 메모리에서 소멸됩니다. 특정 테스트 스테이지에서만 NODE_ENV = 'test'로 세팅하거나, 컴파일 스테이지에서만 특정 플래그를 넘겨줄 때 사용하여 다른 스테이지에 영향을 주지 않도록 격리(Isolation)하는 것이 베스트 프랙티스입니다.

pipeline {
    agent any
    environment {
        // 전역 변수: 모든 스테이지에서 'my-app'으로 접근 가능
        APP_NAME = 'my-app'
    }
    stages {
        stage('Test') {
            environment {
                // 지역 변수: Test 스테이지 밖을 벗어나면 증발함
                DB_ENDPOINT = 'localhost:3306' 
            }
            steps {
                echo "Testing ${APP_NAME} with DB: ${DB_ENDPOINT}"
            }
        }
        stage('Deploy') {
            steps {
                // 여기서는 DB_ENDPOINT 변수를 부르면 에러가 납니다!
                echo "Deploying ${APP_NAME}"
            }
        }
    }
}

⚙️ 2. Jenkins 내장(Built-in) 환경변수 100% 활용하기

우리가 직접 변수를 선언하지 않아도, 젠킨스는 파이프라인이 구동되는 순간 이미 수십 개의 유용한 메타데이터(Metadata)들을 env라는 내장 객체에 담아서 제공해 줍니다. 이를 활용하면 코드가 런타임에 동적으로 움직이게 만들 수 있습니다.

🔥 실무에서 가장 많이 쓰는 내장 환경변수 TOP 4:

• env.BUILD_NUMBER: 젠킨스에서 실행된 현재 빌드의 고유 번호입니다. (예: 1, 2, 3...) 도커 이미지의 고유한 태그(Tag)를 발급할 때 my-image:1.0.${env.BUILD_NUMBER} 처럼 사용하면 겹치지 않는 완벽한 버전 관리가 가능해집니다.
• env.BRANCH_NAME: (Multibranch Pipeline 사용 시) 코드를 푸시한 브랜치의 이름입니다. if (env.BRANCH_NAME == 'main') 같은 분기문을 짜서 운영 배포와 개발 배포를 나눌 때 핵심 기준이 됩니다.
• env.WORKSPACE: 현재 빌드가 실행되고 있는 젠킨스 서버 혹은 컨테이너 내부의 물리적 절대 경로입니다. 파일의 경로를 하드코딩하지 말고 ${env.WORKSPACE}/dist/index.html 처럼 참조해야 안전합니다.
• env.BUILD_URL: 현재 돌고 있는 빌드의 결과 웹페이지 주소입니다. 빌드가 실패했을 때 슬랙으로 실패 알림을 보내면서 "상세 로그 확인하기: ${env.BUILD_URL}" 처럼 링크를 쏴주는 용도로 강력하게 쓰입니다.

💡 3. 문자열 보간법 (String Interpolation)의 함정 피하기

환경변수를 사용할 때 초보자들이 하루 종일 삽질하는 부분이 바로 따옴표(Quote)의 차이입니다. Jenkinsfile은 Groovy 문법을 따르며, 홑따옴표와 쌍따옴표는 완전히 다른 동작을 합니다.

쌍따옴표(Double Quote, " "): 변수 치환(Interpolation)을 지원합니다. 문자열 내부에 ${변수명}을 적으면 그 안의 값이 쏙 빠져나와 문자열에 결합됩니다. 환경변수를 부를 때는 무조건 쌍따옴표를 써야 합니다.

홑따옴표(Single Quote, ' '): 순수한 문자열(Literal)로만 취급합니다. '${env.BUILD_NUMBER}'라고 적으면 숫자 5가 찍히는 게 아니라 진짜 저 글자 그대로가 출력되어 빌드가 박살 나게 됩니다.

steps {
    // ❌ 최악의 실수 (홑따옴표 사용): Hello ${env.BUILD_NUMBER} 라고 그대로 출력됨
    echo 'Hello ${env.BUILD_NUMBER}'
    
    // ✅ 올바른 사용 (쌍따옴표 사용): Hello 42 라고 치환되어 출력됨
    echo "Hello ${env.BUILD_NUMBER}"
}

🔐 4. 자격 증명(Credentials)과의 환상적인 콜라보

이전 포스팅에서 배웠던 credentials() 함수 역시 바로 이 environment 블록 안에서 맹활약합니다. 비밀번호나 토큰을 일반 환경변수처럼 변수에 담아두고, steps 내부에서 쌍따옴표를 이용해 우아하게 호출할 수 있습니다.

pipeline {
    agent any
    environment {
        // 내장 변수를 조합하여 새로운 커스텀 전역 변수 창조
        IMAGE_TAG = "${env.BRANCH_NAME}-${env.BUILD_NUMBER}"
        
        // 민감한 보안 키를 환경변수로 안전하게 바인딩 (로그 마스킹 적용)
        SLACK_TOKEN = credentials('slack-token-id')
    }
    stages {
        stage('Notify & Build') {
            steps {
                echo "현재 태그명은 ${IMAGE_TAG} 입니다."
                // 쉘 스크립트(sh) 안에서도 젠킨스 환경변수를 그대로 끌어다 쓸 수 있습니다.
                sh "curl -X POST -d 'text=빌드시작' -H 'Authorization: Bearer ${SLACK_TOKEN}' https://slack.com/api/chat.postMessage"
            }
        }
    }
}

🎯 5. 마무리 및 다음 단계

지금까지 하드코딩을 없애고 파이프라인을 유연하고 똑똑하게 만들어주는 환경변수의 스코프, 내장 변수 활용법, 그리고 따옴표 문법의 중요성에 대해 3,000자 분량으로 심도 있게 다루어 보았습니다. 이제 여러분의 파이프라인 코드는 훨씬 우아해졌으며, 프로젝트 스펙이 바뀌더라도 environment 블록 상단의 값 몇 개만 톡톡 수정해주면 전체 파이프라인이 알아서 돌아가는 매직을 경험하시게 될 것입니다.

하지만 여전히 해결되지 않은 갈증이 있습니다. "내가 코드를 직접 수정(Commit)하지 않고, 빌드 버튼을 누르는 순간 개발자가 직접 드롭다운 메뉴에서 운영(PROD)에 배포할지, 테스트(DEV)에 배포할지 선택하게 만들 순 없을까?" 하는 니즈입니다. 이어지는 12단계 포스팅에서는 바로 이 문제를 완벽하게 해결해주는 '파이프라인 매개변수(Parameters)와 동적 배포 라우팅 설정법'에 대해 아주 치밀하게 파헤쳐 보겠습니다!