[Cloud] Jenkins 빌드 실패 디버깅: 흔한 문제와 해결 전략 5가지

목차

• [Jenkins] 빌드 실패 디버깅: 흔한 문제와 해결 전략 5가지
• 1. 젠킨스 빌드 실패, 혹시 오늘도?
• 2. Jenkins 빌드 실패, 왜 늘 우리를 괴롭힐까요?
• 3. 흔한 Jenkins 빌드 실패 유형과 해결 전략 5가지
• 4. 💡 젠킨스 로그, 최고의 디버깅 친구 (트러블슈팅/검증)
• 5. 마무리: "삽질은 거름이 됩니다!"

[Jenkins] 빌드 실패 디버깅: 흔한 문제와 해결 전략 5가지

안녕하세요, 13년차 인프라 엔지니어 '13년차의 서버실'입니다. 오늘도 제 홈랩에서 밤늦게까지 삽질 좀 했네요. 😅

1. 젠킨스 빌드 실패, 혹시 오늘도?

인프라 엔지니어라면 누구나 한 번쯤은 젠킨스(Jenkins) 빌드 실패 화면 앞에서 한숨을 쉬어본 경험이 있으실 겁니다. 분명 로컬에서는 잘 되던 코드가 젠킨스만 올라가면 에러를 뿜어내고, 이유를 찾다 보면 어느새 퇴근 시간이 훌쩍 지나버리곤 하죠. 저도 13년차 베테랑이라고는 하지만, 가끔 젠킨스 빌드 실패 로그를 보면 머리를 쥐어뜯게 만듭니다.

하지만 너무 좌절하지 마세요! 수많은 삽질 끝에 얻은 저만의 노하우가 있거든요. 오늘은 젠킨스(Jenkins) 빌드 실패의 흔한 원인들을 파헤치고, 13년차 인프라 엔지니어인 제가 실제로 겪고 해결했던 젠킨스 문제 해결 전략 5가지를 여러분께 멘토처럼 자세히 알려드리려고 합니다. CI/CD 트러블슈팅 시간을 단축하고 더 견고한 빌드 자동화 시스템을 만드는 데 큰 도움이 되기를 바랍니다. 자, 그럼 시작해볼까요? 🎉

Jenkins CI/CD 파이프라인 개요 다이어그램

2. Jenkins 빌드 실패, 왜 늘 우리를 괴롭힐까요?

젠킨스(Jenkins)는 CI/CD(Continuous Integration/Continuous Delivery, 지속적인 통합/지속적인 배포) 파이프라인의 핵심 도구로, 개발자가 코드를 커밋(Commit)하면 자동으로 빌드(Build), 테스트(Test), 배포(Deploy)까지 해주는 참 고마운 친구입니다. 하지만 이 과정에서 수많은 외부 요인과 내부 설정들이 복합적으로 작용하기 때문에, 빌드 실패는 피할 수 없는 숙명처럼 느껴질 때가 많습니다.

쉽게 말해, 젠킨스 빌드는 여러 단계를 거치는데, 각 단계마다 환경 설정, 외부 라이브러리, 시스템 자원, 네트워크 등 고려해야 할 것이 한두 가지가 아닙니다. 그래서 로컬 환경과 젠킨스 서버 환경의 미묘한 차이 하나가 빌드 실패라는 거대한 벽으로 다가오곤 하죠. 결국, 젠킨스 에러를 해결하는 과정은 마치 탐정이 되어 단서를 찾아 범인을 잡는 과정과 비슷합니다. 그럼, 이제 실제 발생했던 흔한 문제들과 그 해결 전략들을 하나씩 살펴보겠습니다.

3. 흔한 Jenkins 빌드 실패 유형과 해결 전략 5가지

3.1. 🚨 환경 변수 (Environment Variable) 문제: "PATH가 왜 이래?"

가장 흔하고도 사람을 미치게 하는 문제 중 하나가 바로 환경 변수(Environment Variable) 문제입니다. 제가 직접 해보니, 쉘 스크립트(Shell Script)로 특정 명령어를 실행했는데 'command not found' 에러가 뜨는 경우가 부지기수였어요. 로컬에서는 분명 <code>JAVA_HOME이나 PATH가 잘 잡혀있는데 젠킨스에서는 딴판이더라고요. 삽질 좀 했습니다 ㅎㅎ.

• 문제 발생 원인: 젠킨스 에이전트(Agent)가 실행되는 환경과 개발자의 로컬 환경의 PATH, JAVA_HOME, M2_HOME 등 주요 환경 변수가 다르게 설정되어 있거나 아예 없는 경우입니다. 젠킨스 에이전트는 일반 사용자 계정으로 실행되는 경우가 많아서, 시스템 전역(Global) 환경 변수를 제대로 인식하지 못할 수 있거든요.
• 해결 전략:
  1. Jenkins Global Tool Configuration 활용: 젠킨스 관리(Manage Jenkins) > Global Tool Configuration 메뉴에서 JDK, Git, Maven, Gradle, Node.js 등 빌드에 필요한 도구들의 경로를 직접 설정하면 돼요. 젠킨스가 이 경로를 기준으로 환경 변수를 자동으로 설정해주니, 이 방법을 가장 먼저 고려해보세요.
  2. Jenkinsfile 내에서 환경 변수 설정: 파이프라인 스크립트(Pipeline Script)인 Jenkinsfile 내에서 withEnv 스텝을 사용해 특정 환경 변수를 명시적으로 설정할 수 있어요. 이는 해당 스텝 내에서만 유효한 환경 변수를 설정할 때 유용합니다.

예시: Jenkinsfile에서 환경 변수 설정

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    withEnv([
                        "JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64",
                        "PATH+JDK=${env.JAVA_HOME}/bin"
                    ]) {
                        sh 'java -version'
                        sh 'mvn clean install'
                    }
                }
            }
        }
    }
}

3.2. 📦 의존성 (Dependency) 누락 또는 버전 불일치: "라이브러리가 없다고?"

로컬에서는 잘 되는데 젠킨스에서만 안 된다고요? 십중팔구 이 녀석 때문입니다. 제가 처음엔 이게 뭔가 싶었는데, 빌드 실패 로그를 자세히 살펴보니 특정 라이브러리를 찾을 수 없다는 에러가 뜨더라고요. 개발 환경과 젠킨스 환경의 의존성이 달라서 생기는 문제였습니다.

• 문제 발생 원인: 프로젝트가 필요로 하는 라이브러리나 모듈(Module)이 젠킨스 에이전트 환경에 설치되어 있지 않거나, 로컬과 다른 버전이 설치되어 호환성 문제가 발생하는 경우입니다. 특히 Node.js 프로젝트의 node_modules나 Maven/Gradle 프로젝트의 로컬 리포지토리(Repository) 캐시 문제로 자주 발생합니다.
• 해결 전략:
  1. 의존성 설치 스텝 추가: 빌드 전 항상 필요한 의존성 설치 명령어를 실행하도록 Jenkinsfile이나 빌드 스크립트에 추가하면 좋아요. 예를 들어, Node.js 프로젝트는 npm install, Maven 프로젝트는 mvn clean install, Gradle 프로젝트는 gradle build를 실행해야 합니다.
  2. 캐시(Cache) 관리: 젠킨스 워크스페이스(Workspace)를 매 빌드마다 클린(Clean)하게 유지하거나, 의존성 캐싱(Caching)을 위한 플러그인(Plugin)을 활용하여 다운로드 시간을 줄이고 일관성을 유지할 수 있어요.
  3. 버전 명시: package.json(Node.js), pom.xml(Maven), build.gradle(Gradle) 등 의존성 관리 파일에 라이브러리 버전을 명시하면 환경 간의 불일치를 최소화할 수 있습니다.

예시: Maven 프로젝트 의존성 설치 스텝

pipeline {
    agent any
    stages {
        stage('Dependencies & Build') {
            steps {
                sh 'mvn clean install -DskipTests'
            }
        }
    }
}

Jenkins 빌드 설정 화면 (의존성 관리)

3.3. 🔐 권한 (Permission) 문제: "파일 접근이 안 된다고?"

빌드 스크립트가 특정 파일에 쓰려고 하는데 'Permission denied' 에러를 뿜어낼 때의 그 허탈함이란... 저도 처음엔 젠킨스 실행 계정이 어떤 권한을 가지고 있는지 제대로 파악하지 못해서 꽤나 삽질했습니다. 특히 파일 시스템에 직접 접근하거나 특정 도구를 실행할 때 많이 발생하더라고요.

• 문제 발생 원인: 젠킨스 에이전트가 실행되는 사용자 계정(보통 jenkins 사용자)이 빌드 과정에서 필요한 파일이나 디렉토리(Directory)에 대한 읽기/쓰기/실행 권한이 없는 경우입니다. 특정 서비스 계정으로만 접근 가능한 리소스(Resource)에 접근하려 할 때도 문제가 생깁니다.
• 해결 전략:
  1. 젠킨스 사용자 권한 확인: 젠킨스 에이전트가 어떤 사용자로 실행되는지 확인하고, 해당 사용자가 빌드에 필요한 모든 리소스에 접근할 수 있도록 권한을 부여하면 돼요. ls -al 명령어로 파일/디렉토리의 소유자(Owner)와 권한을 확인해보세요.
  2. sudoers 설정: 젠킨스 사용자가 특정 명령어를 sudo로 실행해야 할 경우, /etc/sudoers 파일에 해당 명령어를 NOPASSWD 옵션으로 추가하면 비밀번호 없이 실행할 수 있어요. (⚠️ 보안에 유의하여 최소한의 권한만 부여해야 합니다.)
  3. 쓰기 권한 부여: 빌드 과정에서 파일을 생성하거나 수정하는 디렉토리에 젠킨스 사용자가 쓰기(Write) 권한을 가지고 있는지 chmod 명령어로 확인하고 조정하면 됩니다.

예시: 권한 확인 및 변경

# 젠킨스 워크스페이스 디렉토리 권한 확인
ls -ld /var/lib/jenkins/workspace/MyProject

# 필요한 경우 젠킨스 사용자에게 소유권 부여
sudo chown -R jenkins:jenkins /var/lib/jenkins/workspace/MyProject

# 특정 스크립트에 실행 권한 부여
chmod +x myscript.sh

3.4. 💾 메모리/디스크 공간 부족: "아니, 또 공간 부족이야?"

어느 날 갑자기 빌드가 죽더니 'OutOfMemoryError'를 뱉는 겁니다. 슬레이브 서버에 가보니 디스크가 꽉 차 있었죠. 이런 상황은 처음엔 정말 당황스러운데, 13년차인 저도 겪어보니 꽤 흔한 문제더라고요. 특히 대규모 프로젝트나 많은 빌드 아티팩트(Artifact)가 쌓일 때 자주 발생합니다.

• 문제 발생 원인: 젠킨스 에이전트 서버의 물리적 메모리(RAM)나 디스크 공간이 부족하여 빌드 프로세스가 중단되는 경우입니다. Java 기반 애플리케이션의 경우 JVM 힙(Heap) 메모리 부족으로 OutOfMemoryError가 발생할 수 있고, 빌드 아티팩트나 임시 파일이 과도하게 쌓여 디스크 공간이 고갈되기도 합니다.
• 해결 전략:
  1. 디스크 사용량 확인 및 정리: df -h 명령어로 디스크 사용량을 확인하고, du -sh * 명령어로 어느 디렉토리가 공간을 많이 차지하는지 파악하면 돼요. 젠킨스 워크스페이스 클린업 플러그인(Workspace Cleanup Plugin)을 활용하여 오래된 빌드 파일들을 주기적으로 삭제하는 것도 효과적입니다.
  2. 메모리 증설 또는 JVM 설정 조정: 서버의 물리적 메모리를 증설하거나, 빌드 스크립트에서 JVM 옵션(예: -Xmx)을 조정하면 애플리케이션에 할당되는 최대 힙 메모리 크기를 늘릴 수 있어요.
  3. Swap 공간 활성화/증설: 물리적 메모리가 부족할 경우, 스왑(Swap) 공간을 활성화하거나 증설하면 시스템 안정성을 확보할 수 있습니다.

예시: 디스크 사용량 확인

df -h
# /var/lib/jenkins/workspace 디렉토리의 용량 확인
du -sh /var/lib/jenkins/workspace/*

Jenkins 빌드 로그 (메모리 부족 에러)

3.5. ⏳ 타임아웃 (Timeout) 및 네트워크 문제: "왜 이렇게 오래 걸려?"

빌드가 아무런 에러 메시지 없이 그냥 '실패(Failure)'로 뜨는 경우가 있습니다. 처음엔 이게 뭔가 싶었는데, 로그를 자세히 보니 특정 작업이 너무 오래 걸려서 타임아웃(Timeout)으로 종료된 거였더라고요. 특히 Git Fetch가 너무 오래 걸려서 빌드가 실패하는 걸 보고, 네트워크 문제일 거라곤 상상도 못 했습니다.

• 문제 발생 원인: 빌드 스텝(Step) 중 특정 작업(예: Git Clone/Fetch, 외부 API 호출, 대규모 컴파일)이 설정된 시간 안에 완료되지 못하고 타임아웃되어 빌드가 중단되는 경우입니다. 또한, 젠킨스 에이전트에서 외부 리소스(예: Git 리포지토리, 의존성 미러 서버)에 대한 네트워크 연결이 불안정하거나 프록시(Proxy) 설정이 잘못되어 통신에 실패하는 경우도 흔합니다.
• 해결 전략:
  1. 타임아웃 설정 조정: 젠킨스 파이프라인(Pipeline) 스크립트 내에서 timeout 스텝을 사용해 개별 스텝 또는 전체 스테이지(Stage)의 실행 시간을 충분히 늘려주면 돼요. SCM(Source Code Management) 설정에서도 타임아웃을 조정할 수 있습니다.
  2. 네트워크 연결성 확인: 젠킨스 에이전트 서버에서 ping, curl, traceroute 등의 명령어를 사용해 외부 리소스에 대한 네트워크 연결성을 확인하면 돼요. 방화벽(Firewall)이나 보안 그룹(Security Group) 설정도 점검해보세요.
  3. 프록시 설정: 회사 네트워크 환경에서 프록시 서버를 통해 외부 네트워크에 접속해야 한다면, 젠킨스 시스템 설정(Manage Jenkins > System)이나 빌드 스크립트 내에서 http_proxy, https_proxy 환경 변수를 올바르게 설정해야 합니다.

예시: Jenkinsfile에서 타임아웃 설정

pipeline {
    agent any
    stages {
        stage('Long Running Task') {
            options {
                timeout(time: 30, unit: 'MINUTES') // 30분 타임아웃 설정
            }
            steps {
                sh 'your_long_running_command_here'
            }
        }
    }
}

4. 💡 젠킨스 로그, 최고의 디버깅 친구 (트러블슈팅/검증)

제가 13년 동안 수많은 젠킨스 빌드 실패를 겪으면서 얻은 가장 큰 교훈은 바로 '로그를 꼼꼼히 읽는 습관'이 삽질 시간을 줄이는 가장 확실한 방법이라는 겁니다. 젠킨스 콘솔 출력(Console Output)은 단순히 빌드 진행 상황만 보여주는 것이 아니라, 실패의 원인을 알려주는 가장 중요한 단서들이 담겨 있거든요.

• 로그 확인 방법: 실패한 빌드 번호를 클릭한 후, 좌측 메뉴에서 'Console Output'을 선택하면 빌드 전체 로그를 볼 수 있어요.
• 핵심 에러 메시지 찾기: 로그가 너무 길어서 어디부터 봐야 할지 모르겠다면, 'ERROR', 'FAILED', 'Exception', 'Permission denied', 'OutOfMemoryError', 'timeout' 같은 키워드로 검색해보세요. 보통 에러 발생 지점 주변에 원인을 파악할 수 있는 중요한 정보들이 있습니다.
• 스택 트레이스(Stack Trace) 분석: Java 기반 프로젝트의 경우, 스택 트레이스를 통해 어떤 코드 라인에서 예외(Exception)가 발생했는지 정확히 파악할 수 있어요.

로그를 읽는 것은 마치 개발자와 젠킨스가 대화하는 내용을 엿듣는 것과 같습니다. 이 대화 속에서 우리는 문제의 핵심을 찾을 수 있어요. 처음엔 어렵겠지만, 꾸준히 하다 보면 어느새 여러분도 젠킨스 로그 전문가가 되어 있을 겁니다! 🎉

Jenkins 빌드 실패 해결 전략 5가지 요약 인포그래픽

5. 마무리: "삽질은 거름이 됩니다!"

오늘은 젠킨스(Jenkins) 빌드 실패의 흔한 원인 5가지와 그 해결 전략에 대해 이야기해봤습니다. 환경 변수, 의존성, 권한, 자원 부족, 타임아웃 및 네트워크 문제까지, 젠킨스 빌드를 괴롭히는 다양한 요소들을 짚어봤는데요.

CI/CD 파이프라인은 복잡하지만, 각 실패 원인을 체계적으로 파악하고 해결해나가는 과정은 여러분의 문제 해결 능력을 한층 더 성장시킬 겁니다. 저도 수많은 삽질을 통해 이 자리까지 올 수 있었거든요. 여러분의 삽질은 결코 헛되지 않을 겁니다! 오히려 더 견고한 시스템을 만드는 데 필요한 귀한 거름이 될 거예요.

다음번에는 젠킨스 파이프라인(Jenkins Pipeline)을 더욱 효율적으로 관리하는 방법에 대해 다뤄볼까 합니다. 혹시 다루고 싶은 주제가 있다면 언제든지 댓글로 남겨주세요! 여러분의 성공적인 빌드 자동화를 응원하며, '13년차의 서버실'은 다음 글에서 또 찾아뵙겠습니다. 감사합니다! 😊

📚 함께 읽으면 좋은 글

• Cloudflare Workers & R2 비용 최적화: 숨겨진 과금 피하는 실전 전략
• GitHub Actions 비용 폭탄 방지: 불필요한 과금 줄이는 실전 전략
• Cloudflare Zero Trust 구축: VPN 대체 및 보안 강화 실전 가이드