Jenkins 실무 가이드 · 체크리스트

Jenkins 운영 체크리스트

도입 전 확인, Pipeline 작성, 보안, 운영 단계에서 Jenkins를 안전하게 쓰기 위한 항목을 점검합니다.

작성 기준2026년 7월

01

도입 전 확인

Jenkins를 설치하기 전에 자동화할 대상과 운영 책임을 정합니다.

어떤 저장소와 브랜치를 빌드할지 정했다

빌드, 테스트, 패키징, 배포 중 자동화 범위를 정했다

controller와 agent를 같은 서버에 둘지 분리할지 판단했다

Credentials 관리 책임자와 접근 권한 기준을 정했다

백업 대상과 복구 절차를 정했다

02

Pipeline 작성 확인

Jenkinsfile이 리뷰 가능한 자동화 코드로 동작하는지 점검합니다.

Jenkinsfile을 저장소에 포함했다

stage를 Checkout, Install, Test, Build, Deploy처럼 의미 단위로 나눴다

테스트 실패와 빌드 실패가 로그에서 구분된다

산출물과 테스트 리포트를 Jenkins UI에서 확인할 수 있다

배포 stage는 브랜치 조건 또는 승인 조건을 갖고 있다

03

보안 확인

토큰과 배포 권한이 Jenkins를 통해 새지 않도록 확인합니다.

토큰과 비밀번호를 Jenkinsfile에 직접 쓰지 않았다

Credentials ID만 코드에 남기고 값은 Jenkins에 저장했다

빌드 로그에 비밀정보가 출력되지 않는다

Job 설정 변경 권한과 단순 빌드 실행 권한을 분리했다

배포 Job 실행 권한을 필요한 사람에게만 부여했다

04

운영 확인

오래 돌릴 수 있는 Jenkins인지 디스크, 플러그인, 장애 대응 기준을 확인합니다.

빌드 기록과 산출물 보관 개수를 제한했다

agent offline 시 확인할 담당자와 절차가 있다

플러그인 업데이트 전 검증 절차가 있다

Jenkins 설정과 Job 설정을 백업한다

배포 실패 시 재실행 또는 롤백 기준이 문서화되어 있다

05

프로젝트 팀원 사용 확인

일반 팀원이 Jenkins Job을 실행하거나 실패를 확인할 때 필요한 최소 기준입니다.

수동 실행 전 대상 브랜치, 커밋, 파라미터, 배포 환경을 확인한다

실패 시 Stage View에서 실패 단계부터 확인한다

Console Log에서는 첫 에러와 실패 직전 명령을 우선 확인한다

Test Result와 Artifacts가 있으면 로그보다 먼저 구조화된 결과를 확인한다

Agent offline, Credentials, 권한, 플러그인 문제는 운영 담당자에게 넘긴다

구문

자주 쓰는 Pipeline 구문

기본 Pipeline 구문

Jenkinsfile에서 자주 쓰는 최소 구문입니다. Freestyle UI 설정 대신 저장소에 남겨 리뷰할 수 있게 합니다.

pipeline { agent any }Declarative Pipeline 최상위 구조와 실행 agent 지정
checkout scm현재 Job에 연결된 저장소 소스 체크아웃
bat "npm.cmd ci"Windows agent에서 의존성 설치
sh "npm ci"Linux agent에서 의존성 설치
bat "npm.cmd run build"Windows agent에서 빌드 실행
sh "npm run build"Linux agent에서 빌드 실행
결과 수집과 보관

로그만 남기지 말고 테스트 리포트와 산출물을 Jenkins UI에서 구조화해 확인합니다.

junit allowEmptyResults: true, testResults: "reports/**/*.xml"JUnit XML 테스트 결과 수집
archiveArtifacts allowEmptyArchive: true, artifacts: "dist/**"빌드 산출물 보관
buildDiscarder(logRotator(numToKeepStr: "20"))오래된 빌드 기록 보관 개수 제한
timestamps()Console Log에 시간 정보를 남겨 장애 시점 추적
배포 제한과 비밀정보

배포 stage는 아무 브랜치에서나 실행하지 않고, 토큰은 Credentials를 통해 주입합니다.

when { branch "main" }main 브랜치에서만 stage 실행
input message: "Deploy production?"운영 배포 전 수동 승인 단계 추가
withCredentials([string(credentialsId: "deploy-token", variable: "DEPLOY_TOKEN")])Credentials 값을 환경변수로 바인딩
bat "deploy.cmd"Windows agent에서 배포 스크립트 실행
운영

장애·배포 확인 순서

빌드가 큐에서 멈춤

Build Queue에서 대기 사유와 필요한 agent label을 확인합니다.

다음 행동: Agent가 offline인지, executor가 모두 사용 중인지, label이 잘못 지정됐는지 순서대로 봅니다.
특정 stage 실패

Stage View에서 실패 stage를 확인하고 Console Log의 첫 에러 지점을 봅니다.

다음 행동: 테스트 실패면 Test Result, 빌드 실패면 dependency/cache/runtime 차이를 분리해서 재현합니다.
배포 Job 실행 전

브랜치, 파라미터, 대상 환경, 승인자를 확인합니다.

다음 행동: main/release 브랜치 제한과 input 승인 단계가 없다면 운영 배포에 연결하지 않습니다.
Credentials 교체

Jenkinsfile에는 credential ID만 남기고 실제 값은 Jenkins Credentials에서 교체합니다.

다음 행동: 교체 후 dry-run 또는 staging Job으로 로그 노출 없이 정상 주입되는지 확인합니다.
디스크 용량 증가

오래된 workspace, artifacts, build record, dependency cache 중 어디가 증가했는지 확인합니다.

다음 행동: 빌드 보관 정책과 workspace 정리 기준을 먼저 적용하고, 무작정 Job 폴더를 삭제하지 않습니다.
팀원이 빌드 실패를 확인

Stage View, Console Log 첫 에러, Test Result, 대상 커밋을 순서대로 확인합니다.

다음 행동: 테스트 실패나 코드 오류면 PR에서 수정하고, agent offline이나 credentials 오류면 운영 담당자에게 증거와 함께 전달합니다.
수동 Job 재실행 전

브랜치, 커밋, 파라미터, 배포 환경, 이전 실패 원인을 확인합니다.

다음 행동: 원인이 해결되지 않은 상태의 반복 재실행은 피하고, 운영 배포 Job은 승인자와 대상 환경을 다시 확인합니다.
예시

Jenkinsfile 보강 스니펫

파라미터 있는 배포 Jobgroovy
pipeline {
  agent any

  parameters {
    choice(name: "DEPLOY_ENV", choices: ["dev", "staging", "prod"], description: "배포 대상 환경")
    booleanParam(name: "SKIP_TESTS", defaultValue: false, description: "긴급 상황에서만 사용")
  }

  stages {
    stage("Deploy") {
      when {
        branch "main"
      }
      steps {
        input message: "Deploy to ${params.DEPLOY_ENV}?"
        bat "deploy.cmd ${params.DEPLOY_ENV}"
      }
    }
  }
}

운영 배포는 브랜치 제한과 승인 단계를 함께 둡니다.

테스트 리포트와 산출물 수집groovy
pipeline {
  agent any

  options {
    timestamps()
    buildDiscarder(logRotator(numToKeepStr: "20"))
  }

  stages {
    stage("Test") {
      steps {
        bat "npm.cmd test"
      }
    }
    stage("Build") {
      steps {
        bat "npm.cmd run build"
      }
    }
  }

  post {
    always {
      junit allowEmptyResults: true, testResults: "reports/**/*.xml"
      archiveArtifacts allowEmptyArchive: true, artifacts: "dist/**"
    }
  }
}

실패해도 결과를 볼 수 있도록 post always에서 수집합니다.

Credentials 안전 사용groovy
pipeline {
  agent any

  stages {
    stage("Deploy") {
      when {
        branch "main"
      }
      steps {
        withCredentials([string(credentialsId: "deploy-token", variable: "DEPLOY_TOKEN")]) {
          bat "deploy.cmd"
        }
      }
    }
  }
}

토큰 값은 Jenkinsfile과 로그에 직접 출력하지 않습니다.

주의

실무에서 사고가 나는 지점

Jenkinsfile 없이 UI 설정만 사용

설정 변경 이력이 코드 리뷰에 남지 않습니다. 운영 Pipeline은 Jenkinsfile로 저장소에 두는 것이 기본입니다.

Credentials 값 직접 노출

토큰을 Jenkinsfile, 배포 스크립트, console log에 남기면 저장소나 로그를 통해 유출될 수 있습니다.

플러그인 무분별 설치

플러그인은 기능을 늘리지만 보안과 호환성 리스크도 늘립니다. 필요한 플러그인만 설치하고 업데이트 기준을 둡니다.

운영 배포 자동 실행

검증 없이 모든 push가 운영 배포로 이어지면 작은 실수도 장애가 됩니다. 브랜치 제한과 승인 절차를 둡니다.

운영 기준

Jenkins가 빌드와 배포 권한을 갖는 순간 단순 개발 도구가 아니라 운영 시스템이 됩니다. 권한, Credentials, 백업, 플러그인 업데이트 기준 없이 운영 배포에 연결하지 않는 것이 원칙입니다.

PR

Jenkinsfile 변경 PR에 남길 내용

변경 내용
Test stage에 JUnit report 수집 추가main 브랜치에서만 Deploy stage 실행deploy-token credential ID 사용
PR
검증 항목
  • 빌드 재실행 가능 여부
  • 비밀정보 로그 노출 여부
  • 테스트 리포트와 산출물 보관 여부
  • 배포 브랜치 제한과 승인 조건 여부