어떤 저장소와 브랜치를 빌드할지 정했다
도입 전 확인
Jenkins를 설치하기 전에 자동화할 대상과 운영 책임을 정합니다.
빌드, 테스트, 패키징, 배포 중 자동화 범위를 정했다
controller와 agent를 같은 서버에 둘지 분리할지 판단했다
Credentials 관리 책임자와 접근 권한 기준을 정했다
백업 대상과 복구 절차를 정했다
Pipeline 작성 확인
Jenkinsfile이 리뷰 가능한 자동화 코드로 동작하는지 점검합니다.
Jenkinsfile을 저장소에 포함했다
stage를 Checkout, Install, Test, Build, Deploy처럼 의미 단위로 나눴다
테스트 실패와 빌드 실패가 로그에서 구분된다
산출물과 테스트 리포트를 Jenkins UI에서 확인할 수 있다
배포 stage는 브랜치 조건 또는 승인 조건을 갖고 있다
보안 확인
토큰과 배포 권한이 Jenkins를 통해 새지 않도록 확인합니다.
토큰과 비밀번호를 Jenkinsfile에 직접 쓰지 않았다
Credentials ID만 코드에 남기고 값은 Jenkins에 저장했다
빌드 로그에 비밀정보가 출력되지 않는다
Job 설정 변경 권한과 단순 빌드 실행 권한을 분리했다
배포 Job 실행 권한을 필요한 사람에게만 부여했다
운영 확인
오래 돌릴 수 있는 Jenkins인지 디스크, 플러그인, 장애 대응 기준을 확인합니다.
빌드 기록과 산출물 보관 개수를 제한했다
agent offline 시 확인할 담당자와 절차가 있다
플러그인 업데이트 전 검증 절차가 있다
Jenkins 설정과 Job 설정을 백업한다
배포 실패 시 재실행 또는 롤백 기준이 문서화되어 있다
프로젝트 팀원 사용 확인
일반 팀원이 Jenkins Job을 실행하거나 실패를 확인할 때 필요한 최소 기준입니다.
수동 실행 전 대상 브랜치, 커밋, 파라미터, 배포 환경을 확인한다
실패 시 Stage View에서 실패 단계부터 확인한다
Console Log에서는 첫 에러와 실패 직전 명령을 우선 확인한다
Test Result와 Artifacts가 있으면 로그보다 먼저 구조화된 결과를 확인한다
Agent offline, Credentials, 권한, 플러그인 문제는 운영 담당자에게 넘긴다
자주 쓰는 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을 확인합니다.
Stage View에서 실패 stage를 확인하고 Console Log의 첫 에러 지점을 봅니다.
브랜치, 파라미터, 대상 환경, 승인자를 확인합니다.
Jenkinsfile에는 credential ID만 남기고 실제 값은 Jenkins Credentials에서 교체합니다.
오래된 workspace, artifacts, build record, dependency cache 중 어디가 증가했는지 확인합니다.
Stage View, Console Log 첫 에러, Test Result, 대상 커밋을 순서대로 확인합니다.
브랜치, 커밋, 파라미터, 배포 환경, 이전 실패 원인을 확인합니다.
Jenkinsfile 보강 스니펫
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}"
}
}
}
}운영 배포는 브랜치 제한과 승인 단계를 함께 둡니다.
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에서 수집합니다.
pipeline {
agent any
stages {
stage("Deploy") {
when {
branch "main"
}
steps {
withCredentials([string(credentialsId: "deploy-token", variable: "DEPLOY_TOKEN")]) {
bat "deploy.cmd"
}
}
}
}
}토큰 값은 Jenkinsfile과 로그에 직접 출력하지 않습니다.
실무에서 사고가 나는 지점
설정 변경 이력이 코드 리뷰에 남지 않습니다. 운영 Pipeline은 Jenkinsfile로 저장소에 두는 것이 기본입니다.
토큰을 Jenkinsfile, 배포 스크립트, console log에 남기면 저장소나 로그를 통해 유출될 수 있습니다.
플러그인은 기능을 늘리지만 보안과 호환성 리스크도 늘립니다. 필요한 플러그인만 설치하고 업데이트 기준을 둡니다.
검증 없이 모든 push가 운영 배포로 이어지면 작은 실수도 장애가 됩니다. 브랜치 제한과 승인 절차를 둡니다.
Jenkins가 빌드와 배포 권한을 갖는 순간 단순 개발 도구가 아니라 운영 시스템이 됩니다. 권한, Credentials, 백업, 플러그인 업데이트 기준 없이 운영 배포에 연결하지 않는 것이 원칙입니다.
Jenkinsfile 변경 PR에 남길 내용
Test stage에 JUnit report 수집 추가main 브랜치에서만 Deploy stage 실행deploy-token credential ID 사용- 빌드 재실행 가능 여부
- 비밀정보 로그 노출 여부
- 테스트 리포트와 산출물 보관 여부
- 배포 브랜치 제한과 승인 조건 여부