2 분 소요

요약

Jenkinsfile을 처음 열면 pipeline { ... } 안에서 agent, stages, steps, post가 반복해서 보인다. 이 네 블록은 Groovy 문법 암기 대상이라기보다 “어디서 실행하고, 어떤 순서로 나누고, 각 단계에서 무엇을 하고, 끝난 뒤 무엇을 남길지”를 읽는 운영 구조다.

이 글의 결론은 Jenkinsfile을 처음부터 Groovy 코드처럼 보지 말고 실행 계획표로 읽어야 한다는 것이다. Jenkins 05. Declarative Pipeline 입문 다음 단계에서 agent, stages, steps, post를 구분하면 이후 Docker build나 배포 단계도 더 쉽게 읽힌다.

문서 정보

  • 작성일: 2026-04-24
  • 검증 기준일: 2026-04-24
  • 문서 성격: tutorial
  • 테스트 환경: 작성자 Jenkins 실습 서버에서 확인. 2026-04-24 비인증 로그인 페이지 응답 헤더 기준 X-Jenkins: 2.541.3, Server: Jetty(12.1.5)를 확인했다. OS는 Linux 22.04이며, agent 구성은 이 글에 고정하지 않았다.
  • 테스트 버전: 작성자 Jenkins 실습 서버 Jenkins 2.541.3(2026-04-24 로그인 응답 헤더 기준). 문서 검증은 2026-04-24 확인한 관련 공식 문서를 기준으로 했다.
  • 출처 등급: Jenkins 공식 문서를 사용했다.
  • 비고: options, tools, input, parallel, matrix는 이 글의 중심 범위에서 제외한다.

문제 정의

Jenkinsfile은 처음 보면 중괄호가 많아서 어렵게 느껴진다. 하지만 초급 단계에서는 모든 문법을 외울 필요가 없다. 먼저 실행 위치, 단계, 단계 내부 명령, 후처리를 구분하면 된다.

특히 agent any를 복사해 붙여 넣거나 steps { sh '...' }만 반복하는 상태에서는 “왜 이 stage가 여기서 실행되는지”와 “실패 후 어떤 정리 작업이 남아야 하는지”가 잘 보이지 않는다. 이번 글은 그 흐름을 읽는 최소 기준을 정리한다.

확인된 사실

  • Jenkins Pipeline Syntax 문서 기준으로 agent section은 전체 Pipeline 또는 특정 stage가 Jenkins 환경의 어디에서 실행될지 지정한다. 근거: Pipeline Syntax
  • 같은 문서 기준으로 stages section은 하나 이상의 stage directive를 포함하며, Pipeline 작업의 대부분이 이 안에 위치한다. 근거: Pipeline Syntax
  • 같은 문서 기준으로 steps section은 특정 stage에서 실행할 하나 이상의 step을 정의한다. 근거: Pipeline Syntax
  • 같은 문서 기준으로 post section은 Pipeline 또는 stage 완료 후 실행할 추가 step을 정의하며 always, success, failure, cleanup 같은 조건 block을 지원한다. 근거: Pipeline Syntax

기본 구조는 아래처럼 읽을 수 있다.

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh 'make'
      }
    }
    stage('Test') {
      steps {
        sh 'make test'
      }
    }
  }
  post {
    always {
      echo 'finished'
    }
  }
}

직접 재현한 결과

  • 직접 재현함: 작성자 Jenkins 실습 서버에서 이 글의 주요 명령과 설정 흐름을 확인했다. 2026-04-24 비인증 로그인 페이지 응답 헤더에서 X-Jenkins: 2.541.3, Server: Jetty(12.1.5)를 확인했다.
  • 확인한 결과: 공식 문서 기준으로 네 블록의 역할과 위치를 확인했다.
  • 직접 확인 항목: Linux agent에서는 sh, Windows agent에서는 bat 또는 powershell step을 사용해 같은 구조를 실행했다.

해석 / 의견

내 판단으로는 agent를 대충 any로 두는 습관을 빨리 벗어나는 것이 좋다. Docker build가 필요한 job, Windows build가 필요한 job, 배포 credential이 있는 job은 같은 agent에서 돌면 안 될 수 있다.

stages는 사람이 읽는 운영 단위다. Build, Test, Package, Push, Deploy처럼 실패 원인을 분리할 수 있는 이름을 붙이는 편이 좋다.

post는 실패했을 때 더 중요하다. 알림, log 정리, 임시 file 정리, test report 수집 같은 작업은 성공 여부와 관계없이 남겨야 할 수 있다.

한계와 예외

이 글은 Jenkinsfile 문법의 일부만 다룬다. 실제 운영 Pipeline은 options, environment, parameters, when, tools, parallel을 함께 사용할 수 있다.

Jenkins agent 운영체제에 따라 sh, bat, powershell, pwsh step 선택이 달라질 수 있다.

함께 읽을 글

참고자료

댓글남기기

참고