[GitLab] - CI/CD 파이프라인 구축하기 1 (Gitlab Runner 설치)

안녕하세요, 지난 글에서는 제가 여러 고민 끝에 왜 GitLab.com을 선택했는지에 대한 이야기를 풀어보았습니다.

 

오늘은 그 다음 단계로, 우리가 작성할 CI/CD 파이프라인을 실제로 실행해 줄 GitLab Runner를 직접 설치하고 연결하는 과정을 다루겠습니다. GitLab에서 기본으로 제공하는 공유 러너(Shared Runner)도 있지만, 저는 독립적이고 안정적인 환경을 위해 AWS EC2에 전용 러너를 구축하기로 결정했습니다.

 

현재 제 환경은 GitLab Runner만을 위한 EC2 인스턴스를 하나 생성해 둔 상태입니다. 이제부터 이곳에 러너를 설치하고, 제가 속한 그룹(Group)의 모든 프로젝트가 함께 사용할 수 있는 '그룹 러너(Group Runner)'로 등록하는 과정을 차근차근 보여드리겠습니다.

1. GitLab에서 Group Runner 생성

가장 먼저 할 일은 GitLab UI에서 러너를 등록할 공간을 만드는 것입니다. 특정 프로젝트가 아닌 그룹 전체에서 사용할 러너이므로, 그룹 설정 메뉴로 이동합니다.

 

 

버튼을 누르면 러너 생성 화면으로 이동하며, 여기서 러너의 특징(플랫폼, 태그 등)을 지정할 수 있습니다. 저는 우선 별다른 설정 없이 Create runner 버튼을 눌러주었습니다.

2. 등록 토큰(Token) 확인 및 보관

러너를 생성하고 나면, "Success!" 메시지와 함께 이 러너를 서버에 연결할 때 필요한 **인증 토큰(registration token)**이 화면에 나타납니다.

 

 

이 토큰은 실제 서버에서 러너를 등록할 때 해당 러너의 소유권을 증명하는 비밀번호 같은 역할을 합니다. 따라서 반드시 이 토큰을 안전한 곳에 보관해야 합니다.

3. EC2 서버에 GitLab Runner 설치

이제 EC2 서버에 러너를 설치할 차례입니다. 준비해 둔 EC2 서버에 접속하여 아래 명령어들을 차례로 실행합니다.

3-1. GitLab Runner 공식 저장소 추가

먼저, 시스템의 패키지 관리자(apt)가 GitLab Runner 패키지를 찾을 수 있도록 공식 저장소 정보를 추가하는 과정이 필요합니다.

Bash

 

# GitLab Runner 패키지 저장소 정보를 시스템에 추가합니다.
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

# graviton 기반 ec2라면 아래 명령어를 추천드리나 위의 명령어로도 구동가능합니다.
curl -L --output gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-arm64

3-2. GitLab Runner 패키지 설치

저장소 정보가 추가되었으므로, apt 명령어를 통해 간단하게 설치할 수 있습니다.

Bash

 

# gitlab-runner를 설치합니다. (-y 플래그는 설치 과정의 모든 질문에 'yes'로 답합니다)
sudo apt-get install gitlab-runner -y


### graviton일 경우
# 실행 가능하게 만들기
chmod +x gitlab-runner

# 시스템 경로로 이동
sudo mv gitlab-runner /usr/local/bin/gitlab-runner

설치가 완료되면, 아래 명령어로 버전을 확인하는 것이 좋습니다.

Bash

 

# 설치된 버전을 확인합니다.
gitlab-runner --version
# Version:      17.1.0  (예시)
# ...

4. Runner 등록: GitLab과 EC2 연결

서버에 설치된 러너와 GitLab에 생성한 러너 공간을 연결하는 단계입니다. 2단계에서 보관한 토큰을 이때 사용합니다. 아래 명령어를 입력하면, 몇 가지 정보를 입력받는 대화형 프롬프트가 시작됩니다.

Bash

 

# gitlab-runner 등록을 시작합니다.
sudo gitlab-runner register

이제 터미널의 질문에 순서대로 답변하면 됩니다. 제가 입력한 내용은 아래와 같습니다.

• Enter the GitLab instance URL: https://gitlab.com/ 을 입력했습니다.
• Enter the registration token: 2단계에서 복사한 glrt-로 시작하는 토큰을 붙여넣습니다.
• Enter a description for the runner: 이 러너를 식별할 수 있는 이름을 입력합니다. (예: my-group-docker-runner)
• Enter tags for the runner: 이 러너가 처리할 작업을 구분하는 태그입니다. (예: docker, linux, medium)
• Enter an executor: 가장 중요한 단계입니다. 저는 여기서 docker를 입력했습니다. 각 파이프라인 작업을 격리된 도커 컨테이너 환경에서 실행하겠다는 의미입니다.
• Enter the default Docker image to use: Docker executor 선택 시 사용할 기본 도커 이미지를 지정합니다. (예: node:18-alpine)

모든 정보 입력이 끝나면 러너 등록이 성공적으로 완료됩니다.

5. Docker 설치 및 권한 설정

executor로 docker를 선택했으므로, 이 서버에는 Docker가 반드시 설치되어 있어야 합니다. 또한 gitlab-runner가 Docker 명령어를 실행할 수 있도록 권한을 부여해야 합니다.

Bash

 

# 1. Docker 설치 (Ubuntu 기준)
sudo apt-get update
sudo apt-get install docker.io -y

# 2. Docker 서비스 시작 및 부팅 시 자동 실행 설정
sudo systemctl start docker
sudo systemctl enable docker

# 3. gitlab-runner 사용자를 docker 그룹에 추가
# 이 과정을 통해 gitlab-runner가 sudo 없이 docker 명령을 내릴 수 있게 됩니다.
sudo usermod -aG docker gitlab-runner

여기서 usermod 명령어는 매우 중요합니다. gitlab-runner 프로세스는 gitlab-runner라는 시스템 사용자로 실행되므로, 이 사용자에게 Docker 제어 권한을 부여하지 않으면 파이프라인 실행 시 오류가 발생합니다.

6. 최종 확인

모든 과정을 정상적으로 마쳤다면, 다시 GitLab의 Runner 설정 화면으로 돌아가서 확인합니다. 'New' 상태로 보였던 러너가, 이제는 초록색 점과 함께 온라인 상태로 활성화된 것을 확인할 수 있습니다.

 

 

이것으로 파이프라인 실행을 위한 전용 러너가 24시간 대기 상태로 준비 완료되었습니다.

마무리하며

오늘은 CI/CD 파이프라인의 핵심 요소인 GitLab Runner를 EC2 서버에 직접 설치하고, 그룹 내 여러 프로젝트에서 재사용할 수 있도록 등록하는 과정을 진행했습니다. 한번 구축해두면 향후 개발 경험의 질을 크게 향상시킬 수 있을 것입니다.

다음 글에서는 준비된 러너를 활용하기 위해 AWS ECR을 구성하여 도커 이미지를 관리할 수 있는 저장소를 구축하는 과정을 다루어보겠습니다. 그 과정도 기대해주시기 바랍니다.