파이프라인 문법: 선언적과 스크립트, 어떻게 다를까

파이프라인 문법: 선언적과 스크립트, 어떻게 다를까

젠킨스 파이프라인은 Pipeline 플러그인 2.5 버전부터 **선언적(Declarative)**과 스크립트(Scripted) 두 가지 문법을 지원해요. 둘 다 '파이프라인을 코드로' 구현하는 지속적 전달 방식이고, 내장 스텝이나 플러그인이 제공하는 스텝을 함께 쓸 수 있으며 공유 라이브러리(Shared Libraries)도 활용할 수 있어요. 차이는 문법의 형태와 유연성에서 갈라져요. 이 페이지에서는 각 문법의 핵심 요소를 하나씩 짚어볼게요.

출처: Pipeline Syntax - Jenkins Handbook

선언적 파이프라인의 기본 규칙

선언적 파이프라인은 파이프라인 하위 시스템 위에 더 단순하고 정제된(simplified and opinionated) 문법을 얹은 형태예요. 이걸 쓰려면 Pipeline: Declarative Plugin이 설치돼 있어야 해요.

모든 유효한 선언적 파이프라인은 pipeline 블록 안에 감싸져야 해요.

pipeline {
    // 여기에 선언적 파이프라인 작성
}

기본 문법은 Groovy 문법 규칙을 따르지만 두 가지 예외가 있어요. 첫째, 파이프라인 최상위는 반드시 pipeline { } 블록이어야 해요. 둘째, 문장 구분자로 세미콜론을 쓰지 않고 각 문장을 한 줄에 하나씩 둡니다. 그리고 블록은 섹션(Section), 지시어(Directive), 스텝(Step), 할당문으로만 구성돼요.

agent 섹션 — 어디에서 실행할까

agent 섹션은 파이프라인 전체 또는 특정 단계가 어느 환경에서 실행될지 정해요. pipeline 블록 최상위에는 필수로 정의하고, 단계(stage) 수준에서는 선택적으로 둘 수 있어요.

예를 들어 Docker 이미지에서 실행하고 싶다면 이렇게 지정할 수 있어요.

agent {
    docker {
        image 'maven:3.9.3-eclipse-temurin-17'
        label 'my-defined-label'
        args '-v /tmp:/tmp'
    }
}

agent any를 쓰면 사용 가능한 아무 에이전트에서 실행되고, 특정 라벨을 붙여 원하는 에이전트만 골라 쓸 수도 있어요.

environment — 환경변수 설정

environment 지시어는 파이프라인에 필요한 환경변수를 정의해요. pipeline 블록 최상위에 두면 파이프라인 내 모든 스텝에 적용되고, stage 안에 두면 그 단계의 스텝에만 적용돼요.

pipeline {
    agent any
    environment {
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment {
                AN_ACCESS_KEY = credentials('my-predefined-secret-text')
            }
            steps {
                sh 'printenv'
            }
        }
    }
}

credentials() 헬퍼를 쓰면 시크릿 텍스트·시크릿 파일·사용자명/비밀번호 크레덴셜을 환경변수로 안전하게 넣을 수 있어요.

options — 파이프라인 옵션

options 지시어는 파이프라인 자체에서 파이프라인 전용 옵션을 구성하게 해줘요. buildDiscarder 같은 내장 옵션도 있고, timestamps처럼 플러그인이 제공하는 옵션도 쓸 수 있어요. 아래는 실행에 시간 제한을 두는 예시예요.

pipeline {
    agent any
    options {
        timeout(time: 1, unit: 'HOURS')
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

options 다음에 인자로 전달한 값은 params 객체를 통해 파이프라인 스텝에서 접근할 수 있어요. 파라미터는 이름(Name)과 값(Value)을 가지죠.

tools — 도구 설치

tools 지시어는 잠시 빌드를 위해 도구(Maven, JDK, Gradle 등)를 설치하고 PATH에 추가해서 사용할 수 있게 해줘요. 도구 이름은 젠킨스의 전역 도구 설정(Manage Jenkins → Tools)에 등록된 이름이어야 해요.

pipeline {
    agent any
    tools {
        maven 'apache-maven-3.0.1'
    }
    stages {
        stage('Example') {
            steps {
                sh 'mvn --version'
            }
        }
    }
}

steps와 script — 스텝 조합하기

선언적 파이프라인은 Pipeline Steps 레퍼런스에 문서화된 모든 스텝을 사용할 수 있어요. 그중 script 스텝은 선언적 파이프라인에서 특별히 지원되는 스텝으로, 블록 안에서 스크립트 로직(조건문·반복문 등)을 직접 실행할 수 있게 해줘요. 선언적 문법이 감당하기 어려운 복잡한 로직이 필요할 때 그 부분만 스크립트 스타일로 풀어내는 식이에요.

stage('Example') {
    steps {
        script {
            def browsers = ['chrome', 'firefox']
            for (int i = 0; i < browsers.size(); ++i) {
                echo "Testing the ${browsers[i]} browser"
            }
        }
    }
}

스크립트 파이프라인 — 더 유연한 Groovy DSL

스크립트 파이프라인은 선언적 파이프라인처럼 파이프라인 하위 시스템 위에 있지만, Groovy로 만든 범용 DSL이에요. 그래서 대부분의 Groovy 문법을 그대로 사용할 수 있어요. 병렬 실행, try/catch/finally, 함수 정의 같은 실제 프로그래밍 로직을 문법 제약 없이 쓸 수 있죠. 유연한 만큼 문법이 덜 강제되므로, '어떻게 구성할지'를 직접 설계해야 해요.

node {
    stage('Example') {
        if (env.BRANCH_NAME == 'main') {
            echo ' main 브랜치 배포 '
        } else {
            echo ' 그 외 브랜치 '
        }
    }
}

선언적이 구조를 잡아주는 대신 유연성이 줄고, 스크립트는 유연하지만 구조를 직접 짜야 한다는 트레이드오프를 기억하면 두 문법을 상황에 맞게 고를 수 있어요.

더 알아보기