[Jenkins] Pipeline 프로젝트 생성하기

이준영·2025년 12월 30일

Jenkins Pipeline

단순한 빌드 도구를 넘어, 전체 소프트웨어 인도 과정(Delivery Pipeline)을 코드로 관리(Pipeline as Code)할 수 있게 해주는 강력한 프레임워크.

대충 예시

이런식으로 진행 상황을 파악 가능.

장점

코드로서의 파이프라인 (Pipeline as Code)

가장 큰 장점은 빌드 설정을 Jenkinsfile이라는 텍스트 파일에 작성하여 소스 코드와 함께 버전 관리(Git 등)를 할 수 있다는 점입니다.

이력 관리: 누가, 언제, 어떤 빌드 단계를 수정했는지 추적할 수 있습니다.
복제 및 재사용: 동일한 설정을 다른 프로젝트에 쉽게 복사하거나 공유할 수 있습니다.
코드 리뷰: CI/CD 파이프라인의 변경 사항도 코드 리뷰를 통해 검증할 수 있습니다.

강력한 시각화와 피드백 (Stage View)

파이프라인을 사용하면 전체 프로세스를 여러 단계(Stage)로 나눌 수 있으며, 이를 시각적으로 한눈에 파악할 수 있습니다.

단계별 모니터링: 빌드, 테스트, 배포 중 어느 단계에서 시간이 오래 걸리는지, 어디서 실패했는지 즉시 확인 가능합니다.
병렬 실행: 여러 작업을 동시에 실행(Parallel)하여 전체 빌드 시간을 획기적으로 단축할 수 있습니다.

복잡한 워크플로우 지원 및 유연성

단순한 순차적 실행을 넘어 실무의 복잡한 요구사항을 반영할 수 있습니다.

조건부 실행: 특정 브랜치일 때만 배포하거나, 테스트 결과에 따라 다음 단계를 결정할 수 있습니다.
사용자 승인(Input): 운영 서버 배포 전 관리자의 '승인' 버튼 클릭을 기다리는 대기 단계를 넣을 수 있습니다.
에러 핸들링: try-catch-finally 구문을 통해 빌드 실패 시 알림(Slack, Email)을 보내는 등 예외 처리가 유연합니다.

내구성과 연속성 (Durability)

Jenkins Pipeline은 서버가 예기치 않게 재시작되더라도 현재 실행 중인 파이프라인의 상태를 보존할 수 있도록 설계되었습니다.
서버 장애 후 복구되었을 때, 처음부터 다시 시작할 필요 없이 중단된 시점부터 이어서 실행이 가능합니다.

요약

FreeStyle 프로젝트와 비교

특징	Freestyle 프로젝트	Pipeline 프로젝트
관리 방식	UI 설정 (GUI 중심)	코드 (Jenkinsfile)
복잡성 지원	제한적임	매우 높음 (Groovy 기반)
버전 관리	불가능 (백업 필요)	가능 (Git 연동)
시각화	개별 빌드 결과만 확인	단계별 흐름(Stage View) 제공

설정 분석

Pipeline 프로젝트를 설정하기 전에 이전 프로젝트의 설정을 정리해보기로 했다.

General

설명
Github 프로젝트 주소
오래된 빌드 삭제, 최대 3개 보관.

소스 코드 관리

Github로 관리할 프로젝트 연결.
권한 설정.
빌드할 브랜치 : main

Triggers

GitHub Pull Requests가 있을 때 빌드 시작.
Webhook 방식

Environment

빌드가 시작되기 전, 작업 디렉토리(Workspace)를 깨끗하게 비우기
Github 계정 연결
Jenkins 빌드 로그(Console Output)의 각 라인 앞에 해당 작업이 수행된 정확한 시간을 기록

Build Steps

Unity로 빌드.
빌드 후, Github에 Release.

빌드 후 조치는 Build Steps 부분에 Github Release를 만들어 두어서 생략.

Pipeline 설정

FreeStyle 설정 : General, 소스 코드 관리, Triggers, Environment, Build Steps, 빌드 후 조치
Pipeline 설정 : General, Triggers, Pipeline, Advanced

Pipeline 프로젝트는 소스 코드 관리, Environment, Build Steps, 빌드 후 조치를 전부 pipeline에서 Groovy 문법으로 설정할 수 있다.

일단 General과 Triggers는 똑같이 설정 하였다.

기본 설정

Pipeline

이제 Pipeline을 작성하면 되는데, 두 가지 옵션이 있다.

Pipeline Script : 웹 콘솔 직접 입력
Pipeline Script from SCM : 외부 저장소 관리

Pipeline Script의 경우, 수정이 필요할 때 마다 Jenkins 프로젝트 구성에 들어와서 일일히 수정해야 하지만,
Pipeline Script from SCM에 경우, Github에 Groovy 문법으로 된 파일을 넣어둠으로 써 수정이 용의하고 팀 단위 프로젝트일 때, 다른 인원도 접근이 쉽다.

간단 비교

구분	Pipeline script	Pipeline script from SCM
관리 주체	Jenkins 서버 UI	Git 등 버전 관리 시스템
권장 용도	간단한 테스트, 프로토타입	실제 운영 및 팀 프로젝트
파일 이름	없음 (텍스트 박스 입력)	보통 Jenkinsfile
주요 장점	설정이 빠르고 간편함	이력 추적 및 협업 가능

난 Github를 이용하고 여러모로 Pipeline script from SCM의 장점이 많으므로 Pipeline script from SCM을 사용했다.

Pipeline

소스 코드 관리 부분과 비슷하다.
저장소 주소 입력
권한 설정
타겟 브랜치 설정
중요한건 Script Path 부분인데, Groovy 문법을 적어둘 파일 이름을 넣어두면 된다.
Jenkinsfile로 설정. (Github 저장소 파일에 넣으면 됨.)
나의 경우엔 Unity 프로젝트 파일에 바로 넣어줬다.

프로젝트 폴더

Groovy 문법을 그냥 적어서 사용해도 되지만, 나는 가독성을 위해서 Visual studio code를 설치하고 vs code에서 Groovy를 설치했다.

Groovy

이제 문제는 문법인데, 사실 완전 처음 사용해보기 때문에 여러모로 Gemini의 도움을 받았다.
그러다가 알게된 것은 Jenkins에 FreeStyle의 설정 옵션을 Groovy 문법으로 변경해주는 기능이 있다는 것이다.

Pipeline 프로젝트의 왼쪽 옵션을 보면 Pipeline Syntax 라는 옵션을 볼 수 있다.

Pipeline Syntax

Pipeline Syntax

Snippet Generator : 스니펫 생성기

예시

Declarative Directive Generator : 선언형 지시어 생성기

예시

예시 코드

pipeline {
    // [Directive Generator 활용] 실행 환경 설정
    agent any 

    // [Directive Generator 활용] 타임스탬프 및 빌드 보관 설정
    options {
        timestamps() 
        buildDiscarder(logRotator(numToKeepStr: '10')) // 빌드 기록 10개만 보관
    }

    // [Directive Generator 활용] 빌드에 필요한 환경 변수
    environment {
        APP_NAME = 'MyAwesomeApp'
    }

    stages {
        stage('Checkout') {
            steps {
                // [Snippet Generator 활용] Git 소스 가져오기
                checkout scm
            }
        }

        stage('Build') {
            steps {
                // [Snippet Generator 활용] 쉘 스크립트 실행
                echo "Building ${env.APP_NAME}..."
                sh './gradlew build' 
            }
        }

        stage('Test') {
            steps {
                sh './gradlew test'
            }
        }
    }

    // [Directive Generator 활용] 빌드 결과에 따른 후속 조치
    post {
        success {
            echo '빌드 성공! 보관된 파일을 확인하세요.'
            // [Snippet Generator 활용] 빌드 결과물 저장
            archiveArtifacts artifacts: 'build/libs/*.jar', fingerprint: true
        }
        failure {
            echo '빌드 실패! 담당자에게 알림을 보냅니다.'
            // 여기에 이메일이나 Slack 알림 스니펫을 붙여넣습니다.
        }
    }
}

이게 대략적인 Groovy를 사용한 pipeline 문법이다.
물론 저거로 찾기 더럽게 힘들다.

내가 작성한 Jenkinsfile

agent

agent any : 이 빌드를 실행할 수 있는 공간이라면 어디든 상관없으니, 현재 사용 가능한(Idle) 노드 중 하나를 골라 작업을 시작하라"**는 명령어

Options

Options : 전체 파이프라인의 실행 규칙을 정의

skipDefaultCheckout() : 빌드가 시작될 때 소스 코드를 자동으로 체크아웃(다운로드)하지 않도록 설정.
timeout(time: 1, unit: 'HOURS') : 전체 파이프라인의 실행 시간을 최대 1시간으로 제한합니다.
timestamps() : 콘솔 출력 로그의 모든 줄 앞에 실행 시간(타임스탬프)을 표시합니다.

environment

environment : 환경 변수(Environment Variables)**를 정의

UNITY_EXE = 'C:\\Program Files\\Unity 2022.3.17f1\\Editor\\Unity.exe' : Unity 에디터의 실행 파일 경로를 UNITY_EXE라는 이름의 변수에 할당.
GH_TOKEN = credentials('github-token') : Jenkins 관리 화면에 미리 저장해둔 비밀 정보(Credentials) 중 ID가 'github-token'인 값을 가져와 GH_TOKEN 변수에 저장.