젠킨스 설치 및 사용법 총정리｜윈도우,리눅스,Docker 설정부터 CI/CD·Jenkinsfile·오류 해결

Jenkins는 소스코드 빌드·테스트·배포 과정을 자동화하는 대표적인 CI/CD 서버입니다.

개발이나 서버 관리를 하다 보면 젠킨스(Jenkins)라는 이름을 한 번쯤 보게 됩니다. 단순한 개발 프로그램이 아니라 GitHub·GitLab 등에 올라온 소스코드를 가져와 빌드 → 테스트 → 결과 확인 → 서버 배포까지 자동으로 처리할 수 있는 오픈소스 자동화 서버입니다.

처음 접하면 Java를 먼저 설치해야 하는지, 8080 포트는 무엇인지, 플러그인은 뭘 설치해야 하는지, Jenkinsfile과 Pipeline은 또 무엇인지 꽤 복잡해 보입니다. 하지만 구조를 한 번 이해하면 Windows PC 한 대에서 테스트하는 단계부터 Linux 서버·Docker·GitHub Webhook·여러 Agent를 사용하는 회사 CI/CD 환경까지 같은 원리로 확장됩니다.

젠킨스를 처음 접한다면 핵심 3줄

① Jenkins는 코드를 자동으로 빌드·테스트·배포하는 CI/CD 자동화 서버입니다.
② 2026년 현재 최신 Jenkins는 Java 21 이상이 필요하며 Windows 기본 포트는 8080입니다.
③ 처음에는 Windows + 추천 플러그인으로 연습하고, 실제 운영은 Jenkinsfile + Git + Agent + 백업 + 최소권한 구조로 가는 것이 좋습니다.

젠킨스란? CI/CD부터 쉽게 이해하기

Jenkins는 사람이 반복하던 개발 작업을 자동으로 대신 실행하는 서버입니다.

예를 들어 개발자가 GitHub에 코드를 올릴 때마다 아래 작업을 사람이 직접 한다고 생각해보겠습니다.

1. GitHub에서 최신 소스를 내려받습니다.
2. 프로그램을 빌드합니다.
3. 자동 테스트를 실행합니다.
4. 오류가 있는지 확인합니다.
5. 정상이라면 테스트 서버에 배포합니다.
6. 결과를 개발자에게 알려줍니다.

Jenkins를 사용하면 이 과정을 하나의 작업으로 만들어 자동 실행할 수 있습니다.

예를 들어

개발자 Git Push
↓
Jenkins가 변경 감지
↓
소스 다운로드
↓
Build
↓
Test
↓
성공 시 Deploy
↓
Slack·메일 등으로 결과 알림

CI와 CD 차이

구분	의미	예시
CI	지속적 통합	코드가 올라오면 자동 빌드·테스트
CD	지속적 전달·배포	테스트 성공 후 서버 자동 배포

Jenkins에서 알아둘 기본 용어

Job

Jenkins에서 실행하는 하나의 작업입니다. 소스를 내려받아 빌드하거나 서버에 파일을 복사하는 작업 등이 하나의 Job이 될 수 있습니다.

Build

Job을 실제로 실행한 결과입니다. 실행할 때마다 #1, #2, #3과 같이 번호가 생기며 로그와 성공·실패 결과가 저장됩니다.

Pipeline

Build → Test → Deploy처럼 여러 작업을 하나의 흐름으로 연결한 것입니다. 현재 Jenkins를 제대로 사용하려면 단순 Freestyle Job보다 Pipeline을 익혀두는 것이 좋습니다.

Jenkinsfile

Pipeline 내용을 파일로 작성한 것입니다. 보통 Git 저장소 최상위 폴더에 Jenkinsfile이라는 이름으로 저장합니다.

Controller와 Agent

Controller는 Jenkins 전체를 관리하고 작업을 배분하며, Agent는 실제 빌드 명령을 실행하는 별도의 PC·서버입니다.

예를 들어 Controller는 Linux 서버에 두고 Windows 프로그램 빌드는 Windows Agent, Android 빌드는 Linux Agent에서 실행하는 식으로 구성할 수 있습니다.

2026년 Jenkins 최신 버전과 Java 요구사항

예전 설치글과 가장 크게 달라진 부분입니다.

오래된 가이드에서는 Java 17을 설치하라고 되어 있는 경우가 많지만 2026년 현재 Jenkins 2.580 및 LTS 2.568.3을 실행하려면 Java 21 또는 Java 25를 사용하는 것이 공식 지원 기준입니다.

항목	2026년 9월 기준
Weekly	Jenkins 2.580
LTS	Jenkins 2.568.3
Java	Java 21 또는 Java 25
기본 웹 포트	TCP 8080

Weekly와 LTS 중 어떤 버전을 설치할까?

개인 테스트라면 Weekly도 사용할 수 있지만 회사 서버라면 LTS(Long-Term Support)를 추천합니다. 기능 변화보다 안정성과 장기 유지관리가 중요하기 때문입니다.

Jenkins 권장 PC·서버 사양

환경	권장
간단한 테스트	2Core / RAM 2GB 이상
소규모 팀	RAM 4GB 이상 / 저장공간 50GB 이상
여러 빌드 동시 실행	Controller와 Agent 분리 권장

Windows 11·10 Jenkins 설치방법

1. Jenkins 공식 홈페이지에서 다운로드

Jenkins 공식 홈페이지에서 LTS 또는 Weekly 버전을 다운로드합니다.

Jenkins 공식 홈페이지에서 Windows Installer를 다운로드합니다. 운영 서버라면 LTS 버전을 선택하는 것이 무난합니다.

▶ Jenkins 공식 다운로드 페이지

2. Java 21 설치 및 버전확인

명령 프롬프트를 실행한 뒤 아래 명령을 입력합니다.

java -version

Java 21 또는 Java 25가 표시되면 됩니다.

Java 자체가 설치되지 않거나 환경변수가 꼬였다면 아래 잡가이버 글을 먼저 참고하세요.

• 자바 설치오류 1603·환경변수 충돌 해결
• Java 환경변수 JAVA_HOME·Path 설정
• JRE와 JDK 차이 및 설치방법

3. Jenkins MSI 설치파일 실행

Windows용 Jenkins MSI 설치 마법사

설치 프로그램을 실행하고 Next를 눌러 진행합니다.

4. Jenkins 설치경로 지정

Jenkins 프로그램 설치경로를 지정합니다.

특별한 이유가 없다면 기본 경로를 그대로 사용해도 됩니다.

C:\Program Files\Jenkins

5. Jenkins Windows 서비스 계정 설정

Jenkins를 어떤 Windows 계정으로 서비스 실행할지 설정합니다.

운영 서버에서는 LocalSystem을 기본 선택하지 않는 것을 권장합니다.

LocalSystem은 Windows에서 매우 높은 권한을 가진 계정입니다. 개인 PC에서 잠깐 테스트할 때는 편하지만 회사 서버에서는 Jenkins 전용 로컬 또는 도메인 계정을 만들고 필요한 폴더·네트워크 권한만 주는 방식이 더 안전합니다.

전용 계정은 최소한 다음 권한이 필요합니다.

• Log on as a service
• JENKINS_HOME 읽기·쓰기
• 필요한 Git·공유폴더·배포 서버 접근권한

6. Jenkins 포트설정 - 기본 8080

Jenkins 기본 HTTP 포트는 8080입니다.

기본값은 8080입니다. Tomcat이나 다른 개발 프로그램이 8080을 이미 사용한다면 8030·8081·8888처럼 다른 포트로 바꿀 수 있습니다.

기본 : http://localhost:8080

예시 : http://localhost:8030

Test Port 버튼으로 해당 포트가 사용 가능한지 확인합니다.

Jenkins 설치 시 Test Port로 포트 충돌 여부를 확인합니다.

다른 PC에서 Jenkins에 접속할 경우

Windows 방화벽에 해당 TCP 포트의 인바운드 허용 규칙이 필요할 수 있습니다. 방화벽 전체를 끄지 말고 필요한 포트와 IP만 허용하는 것을 권장합니다.

▶ 윈도우 방화벽 포트 열기 인바운드·아웃바운드 설정

7. Jenkins Java Home 지정

Jenkins가 사용할 Java Home 경로를 지정합니다. 현재 버전은 Java 21 이상을 사용하세요.

위 화면은 설치 방식 이해를 위한 예시이며 2026년 최신 Jenkins에서는 Java 21 또는 Java 25를 선택하는 것이 맞습니다.

8. 설치 완료

설정을 확인한 뒤 Jenkins 설치를 시작합니다.

설치가 끝나면 Jenkins가 Windows 서비스로 등록됩니다.

Win + R → services.msc를 실행해 Jenkins 서비스 상태를 확인할 수 있습니다.

Jenkins 최초 접속과 initialAdminPassword

Jenkins 최초 실행 시 initialAdminPassword를 입력해야 합니다.

브라우저에서 설정한 포트로 접속합니다.

http://localhost:8080

Unlock Jenkins 화면이 나타나면 설치경로의 initialAdminPassword 파일을 열어 값을 복사합니다.

C:\Program Files\Jenkins\secrets\initialAdminPassword

설치경로를 변경했다면 해당 Jenkins 폴더 아래의 secrets\initialAdminPassword를 확인합니다.

Jenkins 추천 플러그인 설치

초보자는 Install suggested plugins를 선택하는 것이 편합니다.

처음이라면 Install suggested plugins를 선택하는 편이 좋습니다.

필요한 플러그인은 나중에 Jenkins 관리 → Plugins에서 추가하거나 삭제할 수 있습니다.

자주 사용하는 Jenkins 플러그인

플러그인	용도
Git	Git 저장소 연동
Pipeline	Jenkinsfile Pipeline 실행
Credentials	Git·서버 인증정보 관리
Docker Pipeline	Docker 기반 빌드
GitHub	GitHub Webhook 연동

Jenkins 관리자 계정 생성

Jenkins 최초 관리자 사용자 이름·암호·이메일을 설정합니다.

관리자 계정 이름과 암호, 이메일을 입력합니다. 운영환경에서는 admin / 1234처럼 단순한 계정명·암호를 사용하지 않는 것이 좋습니다.

Jenkins URL 설정

Jenkins가 외부 링크와 Webhook에 사용할 기본 URL을 지정합니다.

개인 PC라면 localhost 주소로 사용할 수 있지만 회사 서버에서는 실제 도메인을 사용하는 편이 좋습니다.

https://jenkins.example.com/

GitHub Webhook, 이메일 링크, Pipeline 결과 링크에서도 이 주소가 사용되므로 실제 접속 가능한 주소를 넣어야 합니다.

Jenkins 대시보드 설치완료

Jenkins 메인 대시보드가 표시되면 기본 설치가 완료된 것입니다.

첫 번째 Jenkins 프로젝트 만들어보기

Freestyle 프로젝트

1. Jenkins 대시보드에서 New Item을 선택합니다.
2. 프로젝트 이름을 입력합니다.
3. Freestyle project를 선택합니다.
4. Source Code Management에서 Git을 선택합니다.
5. GitHub 저장소 주소를 입력합니다.
6. Build Steps에서 실행할 명령을 입력합니다.

Linux 테스트 예시

echo "Jenkins Build Start"
pwd
ls -al
echo "Build Complete"

Windows 테스트 예시

echo Jenkins Build Start
whoami
dir
echo Build Complete

저장한 뒤 Build Now를 선택하고 Build History → Console Output에서 결과를 확인합니다.

GitHub와 Jenkins 연결방법

Git 저장소를 처음 접한다면 먼저 Git 사용법을 이해해두는 것이 좋습니다.

▶ 윈도우 Git Bash 설치와 GitHub 업로드 방법

Git 저장소 주소 예시

https://github.com/example/my-project.git

Git 인증정보는 Credentials에 저장

GitHub Token이나 SSH Private Key를 Pipeline 코드에 직접 적지 말고 Jenkins 관리 → Credentials에 등록해 사용합니다.

잘못된 예

Jenkinsfile 안에 GitHub Token이나 서버 비밀번호를 평문으로 직접 입력하는 것은 피하세요.

Jenkinsfile Pipeline 만드는 방법

실무에서는 GUI로 일일이 Build Step을 만드는 것보다 Jenkinsfile을 Git 저장소에 같이 보관하는 방식을 권장합니다. 설정 변경 이력이 Git에 남고 다른 개발자와 리뷰하기도 편하기 때문입니다.

가장 기본적인 Jenkinsfile 예시

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            steps {
                echo '빌드를 시작합니다.'
            }
        }

        stage('Test') {
            steps {
                echo '테스트를 실행합니다.'
            }
        }

        stage('Deploy') {
            steps {
                echo '배포를 진행합니다.'
            }
        }
    }

    post {
        success {
            echo '빌드 성공'
        }

        failure {
            echo '빌드 실패'
        }
    }
}

실제 Java 프로젝트 예시

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh './gradlew clean build'
            }
        }

        stage('Test') {
            steps {
                sh './gradlew test'
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'build/libs/*.jar',
                             fingerprint: true
        }
    }
}

Jenkins Agent 연결방법

Jenkins Controller에서 직접 모든 빌드를 실행하면 CPU·RAM 사용량이 늘고 Controller가 공격에 노출될 가능성도 커집니다.

실제 운영환경에서는 빌드 전용 Agent를 분리하는 것이 좋습니다.

예시

Jenkins Controller : Ubuntu Server
Windows Agent : Visual Studio 빌드
Linux Agent : Docker Image 빌드
Mac Agent : iOS·macOS 빌드

Agent 등록 위치

Jenkins 관리 → Nodes → New Node에서 추가합니다.

Linux에 Jenkins 설치하는 방법

Linux 서버는 패키지 관리자를 이용하는 방식이 편합니다. 현재 버전에서는 Java 21 이상을 먼저 준비합니다.

Ubuntu·Debian 예시

sudo apt update

sudo apt install fontconfig openjdk-21-jre

java -version

sudo systemctl enable jenkins
sudo systemctl start jenkins

systemctl status jenkins

저장소 등록 명령은 Jenkins 공식 Linux 설치문서에서 최신 값을 확인한 뒤 사용하는 것이 좋습니다.

초기 관리자 암호 확인

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Jenkins 로그 확인

journalctl -u jenkins -n 200 --no-pager

Docker로 Jenkins 설치

테스트·개발환경에서는 Docker가 Jenkins를 빠르게 만들고 없애기 편합니다.

docker volume create jenkins_home

docker run -d \
  --name jenkins \
  -p 8080:8080 \
  -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  jenkins/jenkins:lts-jdk21

Docker Desktop과 WSL2 환경 자체가 안 된다면 아래 글도 참고할 수 있습니다.

▶ 윈도우11 WSL2·Docker Desktop 연동방법

Jenkins 백업 - 가장 중요한 JENKINS_HOME

Jenkins 서버에서 프로그램 파일보다 중요한 것은 JENKINS_HOME입니다.

이 안에는 Job 설정, 사용자 정보, 플러그인, Credentials 관련 데이터, Build History 등이 저장됩니다.

업데이트 전에 백업할 것

• JENKINS_HOME 전체
• 현재 Jenkins 버전
• 설치 플러그인과 버전 목록
• Java 버전
• Reverse Proxy 설정
• Agent 구성
• Webhook URL

스냅샷이나 같은 디스크의 백업 하나만 두기보다 NAS·백업 서버 등 Jenkins 서버와 다른 저장장치에 추가 백업을 두는 것을 권장합니다.

2026년 9월 Jenkins 긴급 보안 업데이트

2026년 9월 2일 Jenkins 프로젝트는 Core와 다수 플러그인에 대한 보안 공지를 발표했습니다.

특히 CVE-2026-84645는 특정 설정 객체 처리 과정에서 Script Console 접근을 통해 원격 코드 실행으로 이어질 수 있는 고위험 취약점입니다.

구분	취약 버전	수정 버전
Weekly	2.579 이하	2.580
LTS	2.568.2 이하	2.568.3

플러그인도 같이 확인

이번 보안 공지에는 GitLab, LDAP, Microsoft Entra ID, SAML, Script Security, ThinBackup, SonarQube Scanner 등 여러 플러그인이 포함됐습니다.

Jenkins 관리 → Plugins → Updates에서 설치 플러그인 버전을 함께 확인하세요.

Jenkins 자주 발생하는 오류와 해결방법

localhost:8080 접속 안됨

먼저 Jenkins 서비스가 실행 중인지 확인합니다.

services.msc

Linux라면 다음과 같이 확인합니다.

systemctl status jenkins

8080 포트가 이미 사용 중

netstat -ano | findstr :8080

PID를 확인한 뒤 기존 서비스와 Jenkins 중 어느 쪽 포트를 바꿀지 결정합니다.

Jenkins Java 오류로 시작 안됨

java -version
where java
echo %JAVA_HOME%

Java 17만 설치되어 있다면 최신 Jenkins에서는 시작되지 않을 수 있으므로 Java 21 또는 Java 25로 변경합니다.

Invalid Service Logon Credentials

Windows 서비스 계정에 Log on as a service 권한이 없는 경우 발생할 수 있습니다.

Win + R → secpol.msc → 로컬 정책 → 사용자 권한 할당 → 서비스로 로그온에서 Jenkins 서비스 계정을 추가합니다.

Jenkins 설치파일이 SmartScreen에서 차단될 때

2026년 Jenkins Windows MSI 서명 방식이 변경되면서 Microsoft Defender SmartScreen에서 자주 다운로드되지 않는 파일 경고가 나타날 수 있습니다.

반드시 Jenkins 공식 사이트에서 받은 파일인지 확인한 후 진행하세요. 검색 광고나 외부 다운로드 사이트의 MSI는 사용하지 않는 것을 권장합니다.

플러그인 설치 실패

• Jenkins 서버 인터넷 연결 확인
• DNS 확인
• Proxy 설정 확인
• Jenkins Core 최소버전 확인
• Java 버전 확인
• Update Center 접속 여부 확인

Agent Offline

• Agent Java 버전 확인
• 방화벽 확인
• Agent Secret 확인
• Agent 작업폴더 권한 확인
• Controller와 Agent 시간 차이 확인

Git Clone 인증 오류

GitHub 암호인증 대신 Personal Access Token 또는 SSH Key를 Jenkins Credentials에 저장해 사용합니다.

GitHub Webhook이 실행되지 않을 때

Jenkins가 localhost나 내부 IP로만 설정되어 있으면 GitHub에서 Jenkins 서버로 접근할 수 없습니다.

외부에서 접근 가능한 HTTPS 주소 또는 VPN·Reverse Proxy 구조가 필요합니다.

Jenkins 운영서버 보안설정

최소한 이 정도는 확인하는 것이 좋습니다.

✔ Jenkins 최신 LTS 유지
✔ 플러그인 정기 업데이트
✔ 관리자 페이지 인터넷 직접 노출 최소화
✔ HTTPS 사용
✔ LocalSystem 대신 최소권한 서비스 계정
✔ Script Console 관리자만 허용
✔ Git·서버 암호를 Jenkinsfile에 직접 입력하지 않기
✔ Credentials 사용
✔ Controller에서 무거운 빌드 직접 실행하지 않기
✔ JENKINS_HOME 외부 백업

초보자는 Freestyle, 실무는 Jenkinsfile 추천

방식	추천
Freestyle Job	처음 Jenkins 구조를 배우는 사용자
Pipeline UI	Pipeline 개념 테스트
Jenkinsfile	실제 프로젝트·회사 CI/CD

Jenkins FAQ

Jenkins는 무료인가요?

네. Jenkins는 오픈소스 자동화 서버로 무료로 사용할 수 있습니다. 다만 AWS·Azure 같은 서버 비용이나 일부 외부 서비스 비용은 별도입니다.

Jenkins를 사용하려면 Java가 꼭 필요한가요?

네. Jenkins Controller와 Agent는 Java 기반이며 2026년 최신 버전은 Java 21 또는 Java 25 사용을 권장합니다.

Java 17로 Jenkins가 실행되지 않습니다.

최신 Jenkins라면 정상적인 현상일 수 있습니다. Java 21 이상으로 업데이트하고 JAVA_HOME도 함께 확인하세요.

Jenkins 기본 포트는 몇 번인가요?

기본 HTTP 포트는 TCP 8080입니다. 다른 프로그램과 충돌하면 다른 포트로 변경할 수 있습니다.

Jenkins를 Windows PC에 설치해도 되나요?

네. 개인 테스트나 Windows 프로그램 빌드에는 편합니다. 다만 대규모 운영환경은 Linux Controller와 별도 Agent 구조가 일반적으로 관리하기 편합니다.

Jenkins와 GitHub Actions 차이는 무엇인가요?

Jenkins는 직접 서버를 구축하고 거의 모든 환경을 자유롭게 구성할 수 있다는 장점이 있고, GitHub Actions는 GitHub 안에서 빠르게 CI/CD를 구축하기 편하다는 장점이 있습니다. 사내망·특수 빌드환경·다수 Agent가 필요하다면 Jenkins가 유리한 경우가 많습니다.

Jenkins Controller와 Agent 차이는 무엇인가요?

Controller는 Jenkins 설정·Job·스케줄을 관리하고 Agent는 실제 빌드 작업을 실행합니다.

Jenkinsfile은 꼭 필요한가요?

필수는 아니지만 실제 CI/CD 프로젝트에서는 권장합니다. Pipeline 설정을 Git으로 버전관리할 수 있기 때문입니다.

Jenkins 관리자 비밀번호를 잊어버렸습니다.

설치 직후라면 initialAdminPassword를 확인할 수 있지만 이미 관리자 계정을 생성했다면 Jenkins 사용자 DB·보안 설정에 맞는 복구절차가 필요합니다. 운영 서버에서는 설정파일을 임의로 수정하기 전에 반드시 JENKINS_HOME을 백업하세요.

Jenkins 업데이트 전에 반드시 백업해야 하나요?

네. Core 버전보다 플러그인 의존성 때문에 문제가 생기는 경우가 있어 JENKINS_HOME과 플러그인 목록을 백업한 뒤 업데이트하는 것이 좋습니다.

Jenkins를 처음 배운다면 추천하는 순서

1단계 Windows PC에 Jenkins 설치

2단계 Freestyle Job으로 echo 명령 실행

3단계 GitHub 저장소 연결

4단계 Jenkinsfile Pipeline 작성

5단계 GitHub Webhook 자동 빌드

6단계 Agent 분리

7단계 Docker·배포서버 연결

8단계 Credentials·HTTPS·백업·권한 보안 설정

Jenkins 설치 및 사용법 결론

Jenkins를 처음 설치할 때는 화면이 많아 복잡해 보이지만 실제 핵심은 생각보다 단순합니다.

Java 준비 → Jenkins 설치 → 8080 접속 → initialAdminPassword → 플러그인 → 관리자 계정 → Job 또는 Pipeline 생성 순서만 이해하면 기본 설치는 어렵지 않습니다.

그다음부터 중요한 부분은 설치가 아니라 관리입니다. GitHub와 연결하고 Jenkinsfile로 Pipeline을 만들고, Agent를 분리하면서 자동화 범위를 조금씩 넓히는 방식이 좋습니다.

특히 회사 서버라면 Jenkins를 단순한 개발도구가 아니라 소스코드와 서버 자격증명을 다루는 중요 인프라로 보는 편이 맞습니다. LocalSystem 같은 과도한 권한을 피하고 플러그인을 최소화하며, JENKINS_HOME 백업과 보안 업데이트를 꾸준히 관리하는 것이 훨씬 중요합니다.

함께 보면 좋은 잡가이버 글

• 자바 설치오류 1603·Java 환경변수 오류 해결
• Java JAVA_HOME·Path 환경변수 설정
• 윈도우 방화벽 포트열기 인바운드·아웃바운드
• Git Bash 설치부터 GitHub 업로드까지
• 윈도우11 WSL2·Docker Desktop 연동방법

Jenkins 공식 확인처

• Jenkins 공식 홈페이지
• Jenkins 최신 버전 다운로드
• Jenkins Windows 공식 설치방법
• Jenkins Linux 공식 설치방법
• Jenkins Pipeline 공식 가이드
• Jenkins 2026년 9월 보안 공지