[Jenkins] Freestyle Project로 첫 자동화 빌드 만들기 (초보자 완벽 가이드)

젠킨스를 설치하고 Github Webhook 연동까지 마쳤다면, 드디어 젠킨스에게 "실제로 어떤 일을 해야 하는지" 작업 명세서를 쥐어줄 차례입니다. 젠킨스에서 작업을 정의하는 방식은 크게 'Freestyle Project(자유 스타일 프로젝트)'와 'Pipeline(파이프라인)' 두 가지로 나뉩니다. 코드로 모든 것을 제어하는 파이프라인이 최신 실무 표준이긴 하지만, 젠킨스의 동작 원리와 플러그인의 결합 방식을 시각적으로 이해하기 위해서는 가장 기본적이고 직관적인 Freestyle Project를 먼저 마스터하는 것이 필수적입니다. 이번 [Jenkins 실무 완벽 가이드]에서는 마우스 클릭 몇 번과 쉘 스크립트 작성만으로 완벽한 자동화 빌드를 구성하는 방법에 대해 3,000자 분량으로 아주 상세하게 딥다이브 해보겠습니다.

📌 1. Freestyle Project란 무엇이며, 언제 사용하는가?

Freestyle Project는 젠킨스의 탄생과 함께해 온 가장 오래되고 클래식한 형태의 Job(작업 단위)입니다. 복잡한 Jenkinsfile 문법을 배울 필요 없이, 웹 브라우저의 그래픽 UI(GUI) 환경에서 드롭다운 메뉴를 선택하고 빈칸을 채워 넣는 것만으로도 소스 코드 클론, 빌드, 테스트, 배포에 이르는 일련의 과정을 손쉽게 세팅할 수 있습니다.

실무 도입 시나리오: 모든 프로젝트를 무조건 파이프라인으로 짜야 하는 것은 아닙니다. 다음과 같은 경우 Freestyle Project가 오히려 유지보수에 훨씬 효율적입니다.

• 단순 배치(Batch) 작업: 매일 밤 12시에 DB 백업 스크립트(bash) 하나만 실행하면 되는 단발성 작업.
• 단순 웹사이트 배포: 프론트엔드 정적 파일(HTML/CSS)을 sftp 플러그인을 통해 특정 서버로 복사만 하면 되는 경우.
• 학습 및 빠른 PoC: 파이프라인 코드를 짜기 전, 플러그인 설정값(Credentials, Path 등)이 맞는지 UI에서 빠르게 테스트해 보고 싶을 때.

⚙️ 2. 소스 코드 관리 (Source Code Management) 설정하기

빌드의 첫 단계는 요리할 재료(소스 코드)를 가져오는 것입니다. 젠킨스 대시보드 좌측의 [새로운 Item]을 클릭하고, 이름을 `My-First-Freestyle`로 지어준 뒤 Freestyle project를 선택하여 생성합니다. 구성(Configure) 화면이 나타나면 아래 순서대로 세팅합니다.

1. [소스 코드 관리] 섹션으로 스크롤을 내립니다. 기본값인 None 대신 Git 라디오 버튼을 선택합니다.
2. Repository URL: 빌드할 프로젝트의 Github 주소를 입력합니다. (예: https://github.com/my-org/hello-world.git)
3. Credentials (매우 중요): 만약 Public 저장소라면 비워두어도 되지만, 실무는 100% Private 저장소를 사용하므로 Github 인증 정보가 필요합니다. [Add] 버튼을 눌러 Github의 Username과 발급받은 Personal Access Token(또는 SSH Key)을 등록하고 선택해 줍니다. 붉은색 에러 메시지가 사라져야 정상입니다.
4. Branches to build: 기본값으로 */master가 적혀 있을 텐데, 최근 Github의 기본 브랜치는 main이므로 반드시 */main으로 수정해 줍니다. (이걸 놓치면 코드를 못 찾아서 빌드 실패가 납니다.)

🛠️ 3. 핵심! Build Steps (빌드 실행 단계) 작성하기

소스 코드를 젠킨스 서버의 Workspace(작업 공간)로 다운로드받았다면, 이제 지지고 볶을 차례입니다. 스크롤을 내려 [Build Steps] 항목을 찾고 [Add build step] 드롭다운 버튼을 클릭합니다. 여기에는 Ant, Gradle, Maven 등 수많은 옵션이 있지만, 가장 원초적이고 강력한 `Execute shell (쉘 실행)`을 선택합니다.

나타난 커다란 텍스트 박스 안에는 리눅스 터미널에 칠 명령어를 그대로 적어주면 됩니다. 젠킨스는 이 스크립트를 Workspace 디렉토리 안에서 한 줄씩 순차적으로 실행합니다. 예를 들어, Node.js 기반의 프론트엔드 프로젝트라면 아래와 같이 작성합니다.

💻 실무 적용 쉘 스크립트 예제:

#!/bin/bash
# 1. 젠킨스 콘솔 로그에 출력을 남깁니다.
echo "✅ Github에서 코드를 성공적으로 가져왔습니다!"
echo "🛠 현재 작업 디렉토리(Workspace) 확인:"
pwd

# 2. 의존성 패키지를 설치합니다. (npm 모듈 다운로드)
echo "📦 npm 패키지 설치를 시작합니다..."
npm install

# 3. 개발자가 작성해둔 단위 테스트를 실행합니다.
echo "🧪 코드가 정상인지 테스트를 수행합니다..."
npm run test

# 4. 실 배포용 빌드(압축 및 난독화)를 진행합니다.
echo "🚀 프로덕션 빌드를 시작합니다..."
npm run build

# 5. 빌드 결과물(dist 폴더) 압축
tar -czvf build-result.tar.gz ./dist
echo "🎉 모든 빌드 과정이 성공적으로 완료되었습니다!"

📦 4. 빌드 후 조치 (Post-build Actions) 및 아티팩트 보관

빌드가 무사히 끝났다고 끝이 아닙니다. 만들어진 결과물(압축 파일이나 Docker 이미지 등)을 보관하거나 타 서버로 전송해야 합니다. 맨 밑의 [빌드 후 조치(Post-build Actions)]에서 `Archive the artifacts (아티팩트 보관)`를 추가합니다.

Files to archive 칸에 아까 쉘 스크립트 마지막에서 생성한 build-result.tar.gz 혹은 dist/**/*를 입력하고 저장(Save)합니다. 이렇게 하면 빌드가 끝난 후 해당 파일이 젠킨스 내부 스토리지에 영구적으로 백업되며, 관리자가 언제든지 웹 브라우저에서 버튼을 눌러 결과물을 다운로드받을 수 있게 됩니다. Slack Notification 플러그인을 설치했다면 이곳에서 '빌드 성공 시 Slack으로 알림 보내기'도 추가할 수 있습니다.

🔍 5. Build Now 실행 및 트러블슈팅 (Troubleshooting)

모든 설정 저장을 마쳤다면, 좌측 메뉴의 시계 모양 아이콘인 [Build Now(지금 빌드)]를 클릭합니다. 좌측 하단 Build History에 파란색 진행 바가 생기며 #1 빌드가 시작됩니다. 빌드 번호(#1)를 클릭하고 [Console Output(콘솔 출력)]으로 들어가면, 방금 우리가 작성했던 쉘 스크립트가 리눅스 터미널처럼 한 줄씩 주르륵 실행되는 쾌감을 맛보실 수 있습니다.

🔥 자주 발생하는 에러: "command not found: npm"

실무에서 가장 흔히 마주치는 에러입니다. 소스코드는 잘 가져왔는데 npm install을 치는 순간 빨간색으로 빌드가 실패(Failure)하는 경우입니다. 원인은 무엇일까요? 젠킨스가 설치된 서버(컨테이너) 자체에 Node.js나 npm이 안 깔려 있기 때문입니다. 젠킨스는 마법사가 아닙니다. 여러분의 컴퓨터 터미널에서 npm이 없으면 에러가 나듯 젠킨스도 똑같습니다.

해결책: [Jenkins 관리] -> [Global Tool Configuration] 메뉴에 가서 NodeJS 설치 항목을 등록해주거나, 젠킨스를 띄운 Docker 컨테이너 내부에 직접 접속하여 apt-get install nodejs 명령어로 필요한 환경을 사전 구성해주어야 합니다.

🎯 6. 요약 및 다음 단계로의 도약

지금까지 Freestyle Project를 활용하여 GUI 환경에서 빠르고 직관적으로 첫 번째 자동화 빌드 파이프라인을 구축하는 방법에 대해 무려 3,000자의 깊이 있는 분량으로 다루어 보았습니다. Git 설정부터 쉘 스크립트 작성, 빌드 후 조치, 그리고 가장 흔한 환경 변수 에러까지 실무에 필요한 기초 체력을 완벽히 다지셨을 것입니다.

하지만 Freestyle Project는 치명적인 단점이 있습니다. 설정 화면이 마우스 클릭 기반이라서 히스토리(누가 언제 어떤 설정을 바꿨는지) 추적이 어렵고, 분기문(if 실패하면 A, 성공하면 B)과 같은 복잡한 비즈니스 로직을 구현하기가 매우 까다롭습니다. 그래서 등장한 현대 CI/CD의 구세주가 바로 코드로 파이프라인을 짜는 'Jenkins Pipeline (Jenkinsfile)'입니다. 다음 포스팅에서는 실무 99%에서 사용되는 이 파이프라인의 기초이자, Scripted 방식과 Declarative 방식의 결정적 차이에 대해 아주 재미있고 명쾌하게 파헤쳐 보겠습니다. 기대하셔도 좋습니다!