서론
gitlab으로 상태관리를 하고있다면, 가장 접근성이 좋은 CI/CD 방법은 GitLab Runner를 활용해 자동화된 CI/CD 파이프라인을 구축하는 것이라고 생각합니다. Gitlab 내에서 코드 작성부터 테스트, 배포까지 손쉽게 관리가 가능하기 때문인데요.
해당 포스팅을 통해 CI/CD 파이프라인을 구축하는 방법을 단계 별로 설명해보겠습니다🤓
Gitlab Runner?
GitLab Runner는 GitLab CI/CD 파이프라인에서 작업(Job)을 실행하는 애플리케이션입니다.
Runner는 다양한 실행 환경(가상 머신, Docker 컨테이너, 호스트 머신)에서 작업을 처리하며, GitLab과 통신해 빌드, 테스트, 배포를 자동화합니다.
- 주요 기능:
- 코드 빌드 및 테스트 실행
- Docker와의 연동 지원
- 다양한 실행 모드(shell, Docker, Kubernetes)
Gitlab Runner는 아래처럼 두 가지로 구분할 수 있는데요.
- GitLab-hosted runners
- GitLab에서 호스팅하는 Runner로, GitLab.com에서 제공하는 공용 Runner
- 기본적으로 모든 프로젝트에서 활성화
- 사용자 측에서 별도의 설치나 설정 불필요
- self-managed runners
- 사용자가 직접 설치 및 관리하는 Runner로, 자체 서버, 가상 머신, Docker 등을 활용해 구성
- 직접 Runner를 설치한 후 GitLab.com 혹은 자체 인스턴스에 Runner를 등록 가능
저는 특정 프로젝트에서만 활성화되는 self-managed runner를 설치 및 등록해보도록 하겠습니다!
(이 과정은 프로젝트의 Owner 권한이 있는 계정으로 진행 가능합니다.)
Gitlab Runner 설치/등록
1. Gitlab Runner 설치
깃랩 러너를 설치하기 위한 명령어는 배포판 별로 조금씩 다른데요.
정리해 보았으나 더 정확한 명령어는 docs/chatGPT에 검색해보기!
(참고: 공식 GitLab Runner 설치 문서)
Ubuntu/Debian
# 1. 패키지 저장소 추가
curl -fsSL https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
# 2. GitLab Runner 설치
sudo apt-get install gitlab-runner
CentOS/RHEL
# 1. 패키지 저장소 추가
curl -fsSL https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
# 2. GitLab Runner 설치
sudo yum install gitlab-runner
Fedora
# 1. 패키지 저장소 추가
curl -fsSL https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
# 2. GitLab Runner 설치
sudo dnf install gitlab-runner
Arch Linux
# GitLab Runner 설치
sudo pacman -S gitlab-runner
2. 설치 확인
gitlab-runner -v
정상적으로 설치가 완료되었다면 아래와 같이 깃랩 러너의 정보가 출력됩니다.
$ gitlab-runner -v
Version: 17.7.0
Git revision: 3153ccc6
Git branch: 17-7-stable
GO version: go1.23.2
Built: 2024-12-19T20:10:51+0000
OS/Arch: linux/amd64
3. Runner 등록
runner을 등록하기 전, 미리 숙지하거나 결정해야 할 부분을 알려드리겠습니다!
-
ci/cd pipeline을 구축하고자 하는 프로젝트의 registration token 알아두기
-
해당 깃랩 프로젝트 > Settings > CI/CD 창으로 이동합니다.
-
아래와 같이 Runners 탭을 Expand해 registration token을 저장해둡니다.
-
-
Runner의 tag를 지정할지 결정하기
- tag는 파이프라인 작업(Job)이 실행될 특정 Runner를 지정하는 데 사용되는 메커니즘입니다.
- 특정 Runner에 태그를 설정하고, 후에 설명될 gitlab-ci.yml 파일 작성 시 해당 태그를 지정하면 그 Runner에서만 작업이 실행됩니다.
- 저는 특정 Runner에 작업을 제한할 필요가 없는 상황이라고 생각해 tag를 지정하지 않았습니다.
-
Runner의 optional maintenance note 결정하기
- optional maintenance note란 GitLab Runner를 관리할 때 선택적으로 추가할 수 있는 설명 필드입니다.
- Runner의 목적, 상태, 담당자 등에 대한 추가 정보를 기록하는 데 사용합니다.
- 저는 필요 없어서 pass~
-
excutor 결정하기
- Runner가 CI/CD 작업(Job)을 실행할 방법 또는 환경을 지정합니다.
- 저는 shell을 선택했습니다.
모든 과정이 끝났다면 아래와 같이 명령어를 입력해 Runner를 최종적으로 등록해줍니다!
$ sudo gitlab-runner register
sudo gitlab-runner register
Runtime platform arch=amd64 os=linux pid=1029900 revision=3153ccc6 version=17.7.0
Running in system-mode.
Enter the GitLab instance URL (for example, https://gitlab.com/):
# 해당하는 gitlab의 url 입력
Enter the registration token:
# 해당하는 프로젝트의 registration token 입력
Enter a description for the runner:
# 깃랩 러너의 description 입력 (optional)
Enter tags for the runner (comma-separated):
# 깃랩 러너의 tag 입력 (optional)
Enter optional maintenance note for the runner:
# 깃랩 러너의 maintenance note 입력 (optional)
Enter an executor: custom, shell, instance, virtualbox, docker-autoscaler, docker+machine, kubernetes, docker, docker-windows, parallels, ssh:
# 사용할 executor 입력
4. 등록 확인
아래 명령어를 통해 깃랩 러너가 정상적으로 등록되었는지 확인합니다.
$ sudo gitlab-runner list
혹은 해당 깃랩 프로젝트 > Settings > CI/CD 창의 Runners 탭에서 아래와 같이 확인이 가능합니다.
gitlab-ci.yml 파일 작성
이제 해당 프로젝트에서 gitlab ci/cd 파이프라인으로 어떻게 동작시킬지를 구성해주는 gitlab-ci.yml 파일을 작성해보겠습니다!
먼저 gitlab-ci.yml 파일은 파이프라인의 흐름을 정의하는 파일로, 기본 구조는 아래와 같습니다.
stages:
- build
- test
- deploy
- 빌드 단계: 코드를 컴파일하거나 패키징
- 테스트 단계: 자동화된 테스트 실행
- 배포 단계: 서버로 코드 전송 및 서비스 재시작
해당 프로젝트의 루트 디렉토리에 gitlab-ci.yml 파일을 추가한 뒤, 원하는 파이프라인의 흐름대로 작성해주시면 됩니다.
저는 프론트엔드 프로젝트의 빌드와 배포 과정 자동화 파이프라인을 정의하기 위해 아래와 같이 작성했습니다.
stages:
- build
- deploy
variables:
DEPLOY_DIR: /usr/share/nginx/poc-front
REMOTE_SERVER: 192.168.999.999 # 예시
REMOTE_USER: root # 예시
# 캐시 설정
cache:
key:
files:
- package.json
paths:
- node_modules/
# 빌드
build:
stage: build
script:
- npm install
- npm run build
- ls -l dist/
artifacts:
paths:
- dist/
# 배포
deploy:
stage: deploy
script:
- ssh-keyscan $REMOTE_SERVER >> ~/.ssh/known_hosts
- ssh $REMOTE_USER@$REMOTE_SERVER "echo SSH connection successful"
- scp -r dist/* "$REMOTE_USER@$REMOTE_SERVER:$DEPLOY_DIR"
only:
- main
하나씩 뜯어가며 살펴볼까요?
stages:
- build
- deploy
stages****는 파이프라인의 단계를 정의합니다. 각 단계는 순서대로 실행됩니다.
build****: 프로젝트 빌드 작업을 수행deploy****: 빌드된 파일을 원격 서버로 배포
variables:
DEPLOY_DIR: /usr/share/nginx/poc-front
REMOTE_SERVER: 192.168.999.999
REMOTE_USER: root
파이프라인 전역에서 사용할 변수를 정의합니다.
이 변수들은 script 내에서 $DEPLOY_DIR, $REMOTE_SERVER와 같은 형태로 참조됩니다.
cache:
key:
files:
- package.json
paths:
- node_modules/
파이프라인 실행 시 node_modules 디렉토리를 캐시로 저장하여, 의존성 설치를 빠르게 처리하고자 했습니다.
build:
stage: build
script:
- npm install
- npm run build
- ls -l dist/
artifacts:
paths:
- dist/
빌드 과정에 대한 스크립트입니다.
script****: 실행할 명령어들npm install: 의존성 설치npm run build: 프로젝트를 빌드하여dist디렉터리에 결과물 생성ls -l dist/: 빌드 결과물 확인
artifacts****:- 빌드 결과물인
dist/디렉터리를 다음 단계(deploy)로 전달
- 빌드 결과물인
deploy:
stage: deploy
script:
- ssh-keyscan $REMOTE_SERVER >> ~/.ssh/known_hosts
- ssh $REMOTE_USER@$REMOTE_SERVER "echo SSH connection successful"
- scp -r dist/* "$REMOTE_USER@$REMOTE_SERVER:$DEPLOY_DIR"
only:
- main
배포 과정에 대한 스크립트입니다.
script****: 실행할 명령어들ssh-keyscan: 원격 서버의 SSH 키를~/.ssh/known_hosts에 추가하여 SSH 접속 경고를 방지ssh: 원격 서버와 SSH 연결을 테스트scp:dist/디렉터리의 모든 파일을$REMOTE_USER@$REMOTE_SERVER:$DEPLOY_DIR로 복사
only****:- 이 Job은
main브랜치에서만 실행함을 명시
- 이 Job은
배포 확인
위 스크립트에 명시된 바와 같이, 이제 main 브랜치에 코드가 푸시되면 파이프라인이 실행됩니다.
main 브랜치에 gitlab-ci.yml을 포함해 코드를 푸시해보면 아래와 같이 해당 깃랩 프로젝트 > Build > Pipelines 창에서 Job의 진행상황을 파악할 수 있습니다.
