Profile picture

[Jenkins] 젠킨스(Jenkins)와 깃랩(Gitlab)으로 자동 배포 파이프라인 구축해보기

JaehyoJJAng2025년 12월 26일

개요

팀 프로젝트를 진행하다 보면 누군가는 코드를 수정하고,

누군가는 서버에 접속하여 수동으로 배포하는 비효율적인 상황이 발생하고는 합니다.


특히 제가 운영하고 웹 프로젝트 Vue3와 Flask 구조처럼,

컨테이너가 분리된 환경에서는 매번 수동으로 이미지를 빌드하고 교체하는 작업이 매우 번거롭습니다.


이번 게시글에서는 팀원 중 누구나 코드를 Push 하기만 하면,

Jenkins가 이를 감지하여 Gitlab Registry에 이미지를 업로드하고,

운영 서버에 접속해 안전하게 컨테이너를 재배포하는 Full-Pipeline 구축법에 대해서 정리해보고자 합니다.


배포 구조

  1. Code push: 팀원이 Gitlab 레포지토리에 새로운 코드 Push
  2. Webhook Trigger: Gitlab이 Jenkins에게 빌드 시작에 대한 이벤트를 전달
  3. CI (Build & Push): Jenkins가 Docker 이미지를 빌드하고 Gitlab container registry에 저장
  4. CD (SSH Deploy): Jenkins가 운영 서버에 SSH로 원격 접속하여 docker compose pull & up 실행


사전 준비

이 배포 파이프라인을 제대로 실습하기 위해서는 몇 가지 준비사항이 있습니다.

  • 1. 배포 테스트를 위한 웹 프로젝트
    • 어떤 프로젝트라도 상관 없습니다. 이 실습은 단순히 Jenkins를 이용하여 배포 자동화를 테스트해보기 위함이니 아주 간단한 API 코드만 구현하셔도 됩니다.
  • 2. Gitlab
    • 해당 실습에서는 코드 저장소를 github가 아닌 self-hosted 기반인 gitlab을 사용합니다.
    • gitlab 설치 시 Container Registry 옵션을 활성화하셔야 원활한 실습 진행이 가능합니다.
    • Gitlab 설치 가이드
  • 3. Jenkins 설치


[준비] GitLab과 Jenkins 연결

1. Gitlab 토큰 발급 및 Jenkins 등록

  • GitLab: 생성한 프로젝트의 Settings -> Access Tokens에서 토큰을 생성합니다.
    • 권한: read_api, read_registry, write_registry
  • Jenkins: Jenkins 관리 -> Credentials에서 Username with password 타입으로 등록합니다.
    • ID: gitlab-auth-id (Jenkinsfile에서 참조할 이름)
    • Username: GitLab 계정명
    • Password: 방금 발급받은 토큰명 입력

2. 설정 테스트!

Jenkins에서 새 파이프라인 생성 시, SCM 설정에서 레포지토리 URL과 위에서 만든 Credential을 선택했을 때 에러 없이 연결되는지 확인하세요!!!



1. SSH 보안 연결

배포 서버에 안전하게 명령을 내리기 위해 SSH 비대칭 키 방식을 사용합니다!

관련해서 아래 게시글을 참조하시면 더 수월합니다!


SSH 키 생성 및 운영 서버 등록

1. 키 생성: Jenkins 컨테이너 내부에서 실행합니다.

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_jenkins

2. 공개키 전송: 운영 서버의 ~/.ssh/authorized_keys에 id_rsa_jenkins.pub 내용을 추가합니다.

# 운영 서버에서 권한 설정 필수~
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

3. Jenkins Credentials 등록: SSH Username with private key 타입으로 추가합니다.

  • ID: server-ssh-key
  • Private Key: 위에서 생성한 id_rsa_jenkins (비밀키) 내용 붙여넣기.
  • Username: 접속하고자 하는 원격 서버의 계정명

image


4. 접속 테스트

Jenkins 파이프라인을 다음과 같이 작성한 후, 실행하여 로그에 Hello, jhlee37!가 정상 출력되는지 테스트합시다.

pipeline {
    agent any

    stages {
        stage('Test echo') {
            steps {
                // SSH Agent를 사용하여 원격 서버에 접속
                sshagent(credentials: ['server-ssh-key']) {
                    // 원격 서버에서 명령어 실행
                    sh """
                        ssh -o StrictHostKeyChecking=no jhlee37@192.168.219.111 '
                            echo Hello, jhlee37!
                        '
                    """
                }
            }
        }
    }
}

image
출력에 성공했네요.

    Tag -
Loading script...