Jenkins 설치와 초기 설정 핵심 정리 (Windows + GitHub Webhook + ngrok)

1. Jenkins 설치

1-1. 서비스 계정/포트 설정

• Logon Type: Run service as LocalSystem 선택
• 기본 포트 8080 대신 18080 사용

1-2. JDK 경로 지정

• Jenkins는 Java 기반이라 JDK 위에서 구동됨
• 설치된 JDK 경로를 찾아 선택

1-3. 초기 Unlock + 플러그인 설치 + Admin 생성

• 브라우저에서 http://localhost:18080 접속

• 안내된 경로의 파일에서 초기 관리자 비밀번호 확인 후 입력

• 추천 플러그인 설치 모드로 진행

• Admin User 생성

  • 계정명: swcamp
  • 암호: swcamp
  • 이름/이메일 입력

• Jenkins URL 확인 후 종료

---

2. Jenkins 설치 이후 (Dashboard → Jenkins 관리)

2-1. 플러그인 설치

2-1-1. Locale 플러그인

• 경로: Jenkins 관리 > Plugins > Available plugins
• locale 검색 후 설치
• 설치 후 재시작: http://localhost:18080/restart
• Appearance에서 Default Language 확인

2-1-2. Pipeline: Stage View / Publish Over SSH

• Pipeline: Stage View 설치
• Publish Over SSH 설치

---

2-2. Tools 설정

2-2-1. JDK installations

• 경로: Jenkins 관리 > Tools > JDK installations

• Add JDK

  • Name: openJDK21
  • JAVA_HOME: JDK 설치 경로

2-2-2. Gradle installations

• 경로: Jenkins 관리 > Tools > Gradle installations
• Add Gradle
• Install automatically 선택

---

2-3. Security: GitHub SSH Host Key 등록 (Known Hosts)

2-3-1. Git Bash로 RSA 키 생성

# 디렉토리 생성/이동
mkdir ./ssh-jenkins
cd ./ssh-jenkins

# .ssh 디렉토리 생성
mkdir ./.ssh

# SSH 인증키 생성 (비밀번호 10자 이상 권장)
ssh-keygen -t rsa -f .ssh/ssh-jenkins-github--key

# 키 확인
cd ./.ssh
cat ssh-jenkins-github--key       # private key
cat ssh-jenkins-github--key.pub   # public key

• SSH: 원격 접속/명령 실행/파일 전송을 위한 암호화 프로토콜

• RSA 키 쌍

  • private key: 외부 유출 금지
  • public key: 등록/공유용

2-3-2. Jenkins에 GitHub Host Key 추가

• Jenkins 관리에서 Git Host Key Verification 설정에 GitHub 공개 호스트키 등록(Manually provided)
• 예시(YAML 형태로 노출된 설정)

security:
  gitHostKeyVerificationConfiguration:
    sshHostKeyVerificationStrategy:
      manuallyProvidedKeyVerificationStrategy:
        approvedHostKeys: |-
          github.com ssh-rsa A0000AAAB3NzaC1yc2EAAAADAQABAAABgQ...

---

2-4. Credentials 설정

2-4-1. GitHub 접근용 SSH private key 등록

• 경로: Jenkins 관리 > Credentials

• Domains 하단 화살표 → Add credentials

• Kind: SSH Username with private key

• ID: SSH 키 식별자(파이프라인에서 참조할 값)

• Username: 예) my-github-key

• Private Key: Enter directly 선택 후 private key 붙여넣기

• Passphrase: 키 생성 시 입력한 비밀번호

2-4-2. Docker Hub 로그인용 Credentials 등록

• Kind: Username with password
• Username / Password: Docker Hub 계정
• ID: DOCKERHUB_PASSWORD
• Description: Docker Hub login 용도
• 비밀번호가 불확실하면 Docker Hub에서 reset 후 입력

---

3. GitHub Webhook + ngrok로 자동 빌드 트리거 구성

3-1. 준비: GitHub 레포 생성 + 프로젝트 푸시

1. GitHub 새 repo 생성
2. 새 경로에 Spring Boot 프로젝트 생성 후 기존 코드 이동
3. Jenkins에서 Gradle build를 수행할 예정이라 Dockerfile은 빌드 과정 제외하고 jar만 실행하도록 구성

Dockerfile 예시

FROM eclipse-temurin:21-jdk-alpine

WORKDIR /app
COPY build/libs/*.jar app.jar

ENTRYPOINT ["java", "-jar", "app.jar"]

push 예시

git init
git remote add origin <github remote repo 주소>
git add *
git commit -m "commit message"
git push origin main

---

3-2. ngrok 설정 (포트포워딩 대체)

• 공유기 포트포워딩이 어려운 환경에서 로컬 Jenkins를 외부에 노출하기 위한 터널링 도구
• 무료 계정은 실행할 때마다 URL이 바뀜

다운로드(Windows 64bit): https://ngrok.com/download

초기 인증

ngrok config add-authtoken $YOUR_AUTHTOKEN

Jenkins(18080) 터널 열기

ngrok http 18080

• ngrok의 forwarding 주소로 Jenkins 접속 가능

---

3-3. Deploy keys에 public key 등록

• 경로: GitHub repository > Settings > Deploy keys > Add deploy key
• public key(ssh-jenkins-github--key.pub) 등록

---

3-4. Webhook 설정

• 경로: GitHub repository > Settings > Webhooks > Add webhook
• Payload URL: ngrok 주소 뒤에 반드시 /github-webhook/ 추가

예시

• https://<ngrok-domain>/github-webhook/

---

4. Jenkins Pipeline Job 생성 및 스크립트 작성

4-1. Pipeline Job 만들기

• 경로: Jenkins > 새로운 Item
• 아이템 이름 입력 → Pipeline 선택 → OK

4-2. GitHub Project 설정

• GitHub Project 체크
• GitHub repo URL 입력

4-3. Build Trigger 설정

• Build Triggers
• GitHub hook trigger for GITScm polling 체크

---

4-4. Jenkinsfile (Gradle Build → Docker Build/Push)

• 동작 흐름

  • GitHub에서 소스 checkout
  • Gradle로 빌드
  • Docker 이미지 생성
  • Docker Hub 로그인 후 push

• GITHUB_URL은 repo에 맞게 변경

• 이미지명 test-pipe도 필요하면 변경

pipeline {
    agent any

    tools {
        gradle 'gradle'
        jdk 'openJDK21'
    }

    environment {
        DOCKERHUB_CREDENTIALS = credentials('DOCKERHUB_PASSWORD')
        GITHUB_URL = 'https://github.com/{url}'
    }

    stages {
        stage('Preparation') {
            steps {
                script {
                    if (isUnix()) {
                        sh 'docker --version'
                    } else {
                        bat 'docker --version'
                    }
                }
            }
        }

        stage('Source Build') {
            steps {
                git branch: 'main', url: "${env.GITHUB_URL}"
                script {
                    if (isUnix()) {
                        sh "chmod +x ./gradlew"
                        sh "./gradlew clean build"
                    } else {
                        bat "gradlew.bat clean build"
                    }
                }
            }
        }

        stage('Container Build and Push') {
            steps {
                script {
                    withCredentials([usernamePassword(credentialsId: 'DOCKERHUB_PASSWORD', usernameVariable: 'DOCKER_USER', passwordVariable: 'DOCKER_PASS')]) {
                        if (isUnix()) {
                            sh "docker build -t ${DOCKER_USER}/test-pipe:latest ."
                            sh "docker login -u ${DOCKER_USER} -p ${DOCKER_PASS}"
                            sh "docker push ${DOCKER_USER}/test-pipe:latest"
                        } else {
                            bat "docker build -t ${DOCKER_USER}/test-pipe:latest ."
                            bat "docker login -u %DOCKER_USER% -p %DOCKER_PASS%"
                            bat "docker push ${DOCKER_USER}/test-pipe:latest"
                        }
                    }
                }
            }
        }
    }

    post {
        always {
            script {
                if (isUnix()) {
                    sh 'docker logout'
                } else {
                    bat 'docker logout'
                }
            }
        }
        success {
            echo 'Pipeline succeeded!'
        }
        failure {
            echo 'Pipeline failed!'
        }
    }
}

---

5. CI/CD 파이프라인 동작 확인

5-1. 최초 수동 빌드

• 처음에는 지금 빌드로 수동 실행 1회 필요
• 각 stage가 정상 수행되는지 확인
• 실패 시 Console Output 로그 보고 원인 수정

5-2. 커밋/푸시로 Webhook 트리거 확인

• 코드 수정 후 Commit & Push
• GitHub Webhook 이벤트로 Jenkins가 자동 실행되는지 확인

---

정리

• Jenkins 설치 시 포트는 18080으로 변경하고 JDK 경로를 지정
• 필수 플러그인(locale, stage view, publish over ssh)과 Tool(JDK/Gradle) 설정 필요
• GitHub 연동은 Deploy key(public key) + Jenkins Credentials(private key) 조합으로 구성
• 외부에서 Jenkins에 Webhook을 보내기 위해 ngrok으로 18080 터널링
• GitHub Webhook Payload URL은 .../github-webhook/로 설정
• Pipeline은 Gradle build 후 Docker build/push까지 자동화하고, 최초 1회는 수동 빌드로 검증