Haru Utils

CI RUNNER

GitLab Runner 설치와 안전한 등록

전용 실행 호스트에 GitLab Runner를 설치하고 인증 토큰을 명령 이력에 남기지 않은 채 대화형으로 등록한 뒤, 실제 보호 브랜치 작업과 격리·롤백까지 검증합니다.
GitLab Runner 설치GitLab Runner 등록runner authentication tokenGitLab CI executorGitLab Runner 보안
지원 환경Ubuntu 24.04 LTS 또는 Debian 12의 전용 Runner 호스트
예상 시간약 45분
난이도중급
검토일2026-08-28

BEFORE YOU START

시작 전에 준비하세요

01

GitLab Maintainer 이상 권한으로 UI에서 생성한 runner authentication token

02

현재 세션 외 복구 콘솔과 sudo 권한, 승인된 점검 시간

03

Runner 전용 호스트와 실행기 선택, 허용 프로젝트·태그·보호 브랜치 정책

04

Docker executor를 선택한다면 먼저 검증된 Docker Engine 구성

권장 대상 프로젝트·그룹 Runner를 처음 등록하면서 토큰 노출과 신뢰되지 않은 CI 작업의 호스트 침해를 함께 방지하려는 개발자·운영자

FOLLOW THE RECIPE

8단계 구성·점검 레시피

1
확인시스템을 변경하지 않는 점검 단계

Runner 범위와 격리 경계 확정

Runner는 CI 작업의 임의 코드를 실행하므로 GitLab 서버와 분리된 전용 호스트를 사용합니다. 프로젝트·그룹·인스턴스 범위와 신뢰 수준이 다른 작업은 토큰과 실행 호스트를 분리합니다.

운영체제와 아키텍처
cat /etc/os-release
uname -m
현재 권한과 가상화
id
sudo -v
systemd-detect-virt
GitLab TLS 연결
curl --fail --silent --show-error --head https://<GITLAB_HOST>/users/sign_in
인증 토큰이나 프로젝트 경로를 URL query·fragment에 넣지 않습니다.
  • GitLab 애플리케이션 서버와 다른 호스트를 준비했습니다.
  • 신뢰되지 않은 포크·공개 프로젝트 작업과 내부 배포 작업을 같은 Runner에 섞지 않습니다.
  • 복구 콘솔과 호스트 스냅샷 또는 설정 백업 경로를 확보했습니다.
결과 읽기

공유 shell executor는 작업이 호스트 계정 권한으로 실행되어 격리 수준이 낮습니다. 신뢰 경계가 불명확하면 등록 전에 전용 VM·컨테이너 executor 설계를 다시 합니다.

다음 판단

기존 Runner와 서비스·디스크·네트워크 기준값을 남깁니다.

2
확인시스템을 변경하지 않는 점검 단계

기존 설치와 용량·포트 사전 점검

기존 등록을 덮어쓰지 않도록 패키지·서비스·config.toml 존재 여부와 작업 공간 여유를 확인합니다. 설정 파일 내용은 토큰을 포함하므로 출력하지 않습니다.

기존 버전
gitlab-runner --version
없다는 메시지는 신규 설치라는 뜻입니다.
서비스 상태
systemctl status gitlab-runner --no-pager
실패해도 신규 설치라면 정상입니다.
설정 파일 메타데이터
sudo stat -c '%U %G %a %n' /etc/gitlab-runner/config.toml
내용을 cat·grep으로 출력하지 않습니다.
작업 공간과 메모리
df -hT / /var/lib/gitlab-runner
free -h
경로가 아직 없으면 루트 파일시스템만 판정합니다.
기준 리슨 포트
sudo ss -lntup
  • 기존 Runner 이름·범위·executor·작업 실행 여부를 GitLab UI와 대조했습니다.
  • config.toml이 있으면 권한과 별도 백업 위치를 정했습니다.
  • 예상 동시 작업 수에 맞는 CPU·메모리·디스크 여유가 있습니다.
결과 읽기

기존 서비스가 active이면 실행 중 작업을 GitLab UI에서 확인하지 않고 패키지를 갱신하거나 서비스를 재시작하지 않습니다.

다음 판단

공식 저장소 스크립트를 내려받아 사람이 검토한 뒤 패키지를 설치합니다.

3
변경패키지·설정·서비스 상태가 달라지는 단계

공식 저장소 검토 후 패키지 설치

GitLab 공식 저장소 구성 스크립트는 내려받기와 실행을 분리합니다. curl 출력을 셸에 직접 연결하지 않고 내용을 검토한 뒤에만 실행하며, 패키지 변경 목록도 대화형으로 승인합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.
공식 저장소 스크립트 다운로드
curl --fail --location --output /tmp/gitlab-runner-repository.deb.sh "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh"
스크립트 메타데이터와 내용 검토
ls -l /tmp/gitlab-runner-repository.deb.sh
sha256sum /tmp/gitlab-runner-repository.deb.sh
less /tmp/gitlab-runner-repository.deb.sh
호스트·저장소 경로·키 설치 범위가 예상과 다르면 실행하지 않습니다.
검토한 스크립트 실행
sudo bash /tmp/gitlab-runner-repository.deb.sh
다운로드 직후 자동 실행하지 말고 검토한 동일 파일인지 체크섬으로 대조합니다.
패키지 후보 검토
apt-cache policy gitlab-runner
Runner 설치
sudo apt install gitlab-runner
표시되는 출처와 버전을 읽고 승인하며 무인 옵션을 사용하지 않습니다.
설치 결과
gitlab-runner --version
systemctl is-enabled gitlab-runner
systemctl is-active gitlab-runner
  • 저장소 스크립트가 packages.gitlab.com 공식 주소에서 왔고 실행 전 내용을 검토했습니다.
  • APT 후보가 GitLab Runner 공식 저장소를 가리킵니다.
  • Self-Managed GitLab과 Runner 버전 호환성을 확인했습니다.
결과 읽기

패키지 서명이나 저장소 TLS 검증이 실패하면 우회 옵션을 쓰지 말고 시스템 시간·CA·프록시·저장소 URL을 먼저 복구합니다.

다음 판단

토큰을 인자·환경변수에 넣지 않는 대화형 등록을 수행합니다.

4
주의권한·연결·중단 영향을 확인할 단계

인증 토큰을 노출하지 않고 대화형 등록

GitLab UI에서 프로젝트·그룹 Runner를 먼저 만들고 발급된 glrt 계열 인증 토큰을 대화형 프롬프트에만 붙여넣습니다. 토큰을 URL, 셸 인자, 환경변수, 메신저, 화면 캡처에 넣지 않습니다.

기존 설정 백업
sudo cp --archive --no-clobber /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.<BACKUP_SUFFIX>.bak
기존 파일이 있을 때만 실행하고 아직 존재하지 않는 고유 접미사를 사용합니다.
대화형 Runner 등록
sudo gitlab-runner register --url https://<GITLAB_HOST>/
토큰 질문이 나타날 때만 직접 붙여넣습니다. 등록 후 클립보드를 지우고 셸 기록·화면 녹화에 토큰이 없는지 확인합니다.
설정 구문·스키마 검사
sudo gitlab-runner lint --config /etc/gitlab-runner/config.toml
list 명령은 인증 토큰을 출력할 수 있어 사용하지 않습니다. lint 결과도 외부 공유 전 Runner 이름과 호스트 정보를 가립니다.
설정 권한
sudo chown root:root /etc/gitlab-runner/config.toml
sudo chmod 600 /etc/gitlab-runner/config.toml
안전 옵션 편집
sudoedit /etc/gitlab-runner/config.toml
token 줄은 복사·수정하지 말고 concurrent, limit, executor 격리 옵션만 승인된 값으로 조정합니다.
  • 토큰이 명령 이력·프로세스 인자·URL·화면 캡처에 남지 않았습니다.
  • Runner 이름과 태그가 목적을 드러내고 untagged 작업 허용 여부를 최소화했습니다.
  • 보호 브랜치 전용 Runner이면 GitLab UI에서도 Protected로 제한했습니다.
  • config.toml은 root만 읽을 수 있습니다.
결과 읽기

등록 실패 때 같은 토큰을 여러 명령 형태로 반복 노출하지 않습니다. GitLab UI에서 토큰 상태·TLS·Runner/GitLab 호환성을 확인하고 노출 가능성이 있으면 즉시 회전합니다.

다음 판단

서비스가 설정을 읽는지 검증한 뒤 제한된 테스트 작업을 실행합니다.

5
주의권한·연결·중단 영향을 확인할 단계

서비스 시작과 등록 연결 확인

config.toml 백업과 권한을 확인한 뒤 서비스를 시작합니다. GitLab Runner는 대부분의 설정을 자동으로 다시 읽지만 설치 직후에는 서비스 상태와 원격 등록을 명시적으로 확인합니다.

서비스 활성화와 시작
sudo systemctl enable gitlab-runner.service
sudo systemctl start gitlab-runner.service
서비스 상태
systemctl is-enabled gitlab-runner.service
systemctl is-active gitlab-runner.service
systemctl status gitlab-runner.service --no-pager
GitLab 등록 확인
sudo gitlab-runner verify
모든 등록이 alive인지 보고 config.toml 내용은 출력하지 않습니다.
최근 로그
sudo journalctl -u gitlab-runner.service -n 120 --no-pager
URL·프로젝트·호스트 정보는 외부 공유 전에 가립니다.
  • 서비스가 enabled·active입니다.
  • gitlab-runner verify가 등록된 Runner와 GitLab 통신에 성공했습니다.
  • 최근 로그에 TLS·인증·executor 초기화 오류가 없습니다.
결과 읽기

서비스 active는 Runner가 GitLab에서 작업을 받을 수 있다는 뜻이 아닙니다. verify와 GitLab UI online 상태를 함께 확인합니다.

다음 판단

최소 권한 테스트 프로젝트에서 두 번째 실제 작업을 실행합니다.

6
주의권한·연결·중단 영향을 확인할 단계

제한된 CI 작업으로 실행 경계 검증

전용 테스트 프로젝트의 보호 브랜치에서 비밀변수 없이 읽기 전용 작업을 실행합니다. 성공 후 다른 작업을 한 번 더 실행해 일회성 등록 성공이 아닌지 확인합니다.

Runner 프로세스와 서비스 계정
systemctl show gitlab-runner.service -p User -p Group -p ActiveState -p SubState
ps -u gitlab-runner -o pid,etime,comm
작업 디렉터리 사용량
sudo du -sh /home/gitlab-runner /var/lib/gitlab-runner 2>/dev/null
존재하는 경로만 합산합니다.
등록 재검증
sudo gitlab-runner verify
작업 후 로그
sudo journalctl -u gitlab-runner.service --since '-15 min' --no-pager
  • 보호 브랜치의 읽기 전용 테스트 작업이 성공했습니다.
  • 같은 태그로 두 번째 작업도 성공해 polling과 executor 재사용을 확인했습니다.
  • 작업 로그에 인증 토큰·배포 비밀·호스트 전역 환경이 노출되지 않았습니다.
  • 취소한 작업의 프로세스와 임시 자원이 남지 않았습니다.
결과 읽기

UI에서 online이어도 잘못된 태그·보호 설정·executor 이미지 때문에 작업이 pending일 수 있습니다. 서버 로그보다 먼저 Job의 요구 태그와 Runner 정책을 대조합니다.

다음 판단

캐시·권한·토큰 회전·패치 정책을 운영 기준에 맞게 잠급니다.

7
주의권한·연결·중단 영향을 확인할 단계

Runner 신뢰 범위와 비밀 접근 최소화

Runner 인증 토큰은 config.toml에 저장되므로 파일 접근을 제한하고 주기적으로 회전합니다. privileged 컨테이너, 호스트 Docker 소켓, 광범위 캐시 공유는 별도 격리 위험 검토 없이는 사용하지 않습니다.

설정·서비스 파일 권한
sudo stat -c '%U %G %a %n' /etc/gitlab-runner/config.toml /etc/systemd/system/gitlab-runner.service
계정 그룹과 로그인 셸
getent passwd gitlab-runner
id gitlab-runner
Runner 호스트 리슨 포트
sudo ss -lntup
업데이트 후보
apt list --upgradable 2>/dev/null | grep -E '^gitlab-runner/'
후보가 있으면 실행 중 작업과 릴리스 노트를 확인해 점검 시간에 적용합니다.
  • config.toml을 백업·지원 요청·로그 수집에 그대로 포함하지 않습니다.
  • Runner를 Protected·Locked·태그 정책으로 필요한 프로젝트에만 연결했습니다.
  • 민감 배포 Runner와 공개 포크 작업 Runner를 별도 호스트·토큰으로 분리했습니다.
  • Docker 소켓·privileged 모드·호스트 경로 마운트는 기본값으로 허용하지 않습니다.
  • 토큰 회전·Runner 폐기·호스트 재이미징 절차를 기록했습니다.
결과 읽기

Runner가 실행한 코드는 서비스 계정 이상의 권한을 얻을 수 있습니다. 설정 파일 권한만으로 충분하지 않으며 executor·네트워크·클라우드 역할까지 같은 신뢰 경계로 검토합니다.

다음 판단

운영 지표와 캐시 용량을 관찰하고 문제가 있으면 안전한 중지·복원 분기로 이동합니다.

8
변경패키지·설정·서비스 상태가 달라지는 단계

작업 수신 중지와 등록 구성 보존

문제가 생기면 GitLab UI에서 Runner를 먼저 Pause해 새 작업을 차단하고 실행 중 작업의 종료를 확인합니다. 토큰·config.toml·작업 로그는 삭제하지 않고 조사 가능한 상태로 보존합니다.

변경 단계입니다. 대상 서버, 백업 파일, 서비스 중단 영향과 바로 이전 상태로 돌아가는 방법을 다시 확인하세요.
실행 중 작업 확인
sudo gitlab-runner status
ps -u gitlab-runner -o pid,etime,comm
GitLab UI에서 Pause한 뒤 실행 중 작업이 없을 때만 중지합니다.
서비스 중지와 자동 시작 해제
sudo systemctl stop gitlab-runner.service
sudo systemctl disable gitlab-runner.service
중지 검증
systemctl is-active gitlab-runner.service
systemctl is-enabled gitlab-runner.service
inactive·disabled가 예상 결과입니다.
기존 설정 백업 복원
sudo cp --preserve=all /etc/gitlab-runner/config.toml.<BACKUP_SUFFIX>.bak /etc/gitlab-runner/config.toml
백업이 실제 이번 변경 직전 파일임을 대조한 기존 설치 분기에서만 실행합니다.
신규 설정 보존 비활성화
sudo mv --no-clobber /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.disabled.<BACKUP_SUFFIX>
기존 백업이 없는 최초 등록 분기에서만 실행합니다. 삭제하지 않습니다.
복원 후 원격 연결 확인
sudo gitlab-runner verify
기존 설정 복원 분기에서만 실행하고 GitLab UI에서 예상 Runner만 online인지 확인합니다.
  • GitLab UI에서 새 작업 수신을 먼저 중지했습니다.
  • 실행 중 작업이 없어진 뒤 서비스를 중지했습니다.
  • 노출 가능성이 있는 인증 토큰은 UI에서 회전·폐기했습니다.
  • 기존 설치는 검증한 백업만 복원했고 신규 설치는 설정을 .disabled로 보존했습니다.
  • 원격 Runner 레코드 삭제는 조사와 토큰 폐기 후 GitLab UI에서 별도 승인했습니다.
결과 읽기

호스트 서비스만 중지해도 GitLab의 Runner 레코드와 인증 토큰은 남습니다. 침해 가능성이 있으면 Pause만으로 끝내지 말고 토큰을 회전하고 호스트를 재이미징합니다.

다음 판단

재등록 전 원인과 신뢰 경계를 바로잡고 별도 테스트 Runner에서 검증합니다.

SECURITY CHECK

운영 전 마지막 보안 점검

  • Runner 인증 토큰을 명령 인자·환경변수·URL·로그에 넣지 않는다.
  • 신뢰 수준이 다른 프로젝트는 Runner 호스트와 토큰을 분리한다.
  • config.toml은 root만 읽도록 제한한다.
  • privileged 실행, Docker 소켓, 호스트 경로 마운트는 별도 위험 승인 없이는 사용하지 않는다.
  • 보호 브랜치·태그·Locked 정책과 토큰 회전 주기를 운영 문서에 남긴다.

COMMON ERRORS

자주 막히는 지점

Runner가 offline

증상
서비스는 active지만 GitLab UI에서 offline으로 표시됩니다.
가능한 원인
TLS 신뢰, 프록시, GitLab URL, 토큰 회전 또는 버전 호환 문제가 흔합니다.
확인 순서
gitlab-runner verify와 journalctl을 확인하고 토큰을 출력하지 않은 채 UI의 Runner 상태와 대조합니다.
트러블슈팅으로 이어보기

작업이 pending

증상
Runner가 online인데 작업이 시작되지 않습니다.
가능한 원인
요구 태그, Protected·Locked 정책 또는 executor 용량이 작업과 맞지 않습니다.
확인 순서
Job의 태그·브랜치 보호 상태와 config.toml의 비밀이 아닌 제한 옵션을 비교합니다.

작업 후 디스크 증가

증상
빌드 캐시와 작업 디렉터리가 계속 커집니다.
가능한 원인
캐시 수명·동시성·컨테이너 정리 정책이 용량 계획과 맞지 않습니다.
확인 순서
사용량과 실행 중 작업을 먼저 확인하고 GitLab 공식 캐시 정리 정책을 점검 시간에 적용합니다.
트러블슈팅으로 이어보기

PRIMARY REFERENCES

공식 문서

설치 저장소와 지원 버전은 바뀔 수 있습니다. 검토일 이후에는 링크된 공식 문서와 현재 서버의 패키지 후보 버전을 함께 확인하세요.

TROUBLESHOOT NEXT

설치 후 문제라면 여기서 이어가세요

트러블슈팅 · SYSTEMD서비스가 시작되지 않거나 failed일 때진단 순서 보기 →트러블슈팅 · NETWORK PATH서버에서 외부 통신이 되지 않을 때진단 순서 보기 →트러블슈팅 · STORAGE FIRST AIDLinux 서버 디스크가 가득 찼을 때진단 순서 보기 →트러블슈팅 · DOCKER STORAGEDocker 디스크와 컨테이너 로그가 커질 때진단 순서 보기 →

NEXT RECIPE

함께 볼 구성 레시피

CONTAINER RUNTIMEDocker Engine와 Compose 설치8단계로 보기 →CODE QUALITY PLATFORMSonarQube 2026.1 LTA·PostgreSQL 연동8단계로 보기 →ARTIFACT REPOSITORYNexus Repository 설치와 저장공간 관리8단계로 보기 →

도구 빠른 검색

최근 사용한 도구를 다시 열거나, 이름과 기능으로 검색하세요.

검색어와 도구의 입력·결과는 저장하지 않습니다.

↑↓ 이동 · Enter 열기 · Esc 닫기