• 환경 변수를 사용하기
• 디버그 모드에서 실행하기
• 슈퍼유저 권한
• 구성 파일
• 신호
• 명령어 개요
• 등록 관련 명령어
  • gitlab-runner register
    • 대화형 등록
    • 비대화형 등록
    • [[runners]] 구성 템플릿 파일
  • gitlab-runner list
  • gitlab-runner verify
  • gitlab-runner unregister
    • URL 및 토큰으로
    • 이름으로
    • 모든 러너
  • gitlab-runner reset-token
    • 러너의 현재 토큰으로
    • PAT 및 러너 이름으로
    • PAT, GitLab URL 및 러너 ID로
    • 모든 러너
• 서비스 관련 명령
  • gitlab-runner install
  • gitlab-runner uninstall
  • gitlab-runner start
  • gitlab-runner stop
  • gitlab-runner restart
  • gitlab-runner status
  • Multiple services
• Run-related commands
  • gitlab-runner run
  • gitlab-runner run-single
  • gitlab-runner exec (removed)
• 내부 명령어
  • gitlab-runner artifacts-downloader
  • gitlab-runner artifacts-uploader
  • gitlab-runner cache-archiver
  • gitlab-runner cache-extractor
• 문제 해결
  • 서비스 관련 명령어를 실행할 때 Access Denied
• gitlab-runner stop가 정상적으로 종료되지 않음
  • 시스템 ID 상태 파일 저장: 접근 거부

GitLab Runner 명령어

GitLab Runner는 빌드를 등록하고 관리하며 실행하는 데 사용하는 명령어 세트를 포함합니다.

명령어 목록을 보려면 다음을 실행하세요:

gitlab-runner --help  

특정 명령어에 대해 구체적인 도움말 페이지를 보려면 명령어 뒤에 --help를 추가하세요:

gitlab-runner <command> --help  

환경 변수를 사용하기

대부분의 명령어는 명령어에 구성 정보를 전달하는 방법으로 환경 변수를 지원합니다.

특정 명령어에 대해 --help를 호출하면 환경 변수의 이름을 확인할 수 있습니다. 예를 들어, run 명령어에 대한 도움말 메시지는 아래와 같습니다:

gitlab-runner run --help  

출력은 다음과 비슷합니다:

NAME:  
   gitlab-runner run - 멀티 러너 서비스 실행  

USAGE:  
   gitlab-runner run [command options] [arguments...]  

OPTIONS:  
   -c, --config "/Users/ayufan/.gitlab-runner/config.toml"      구성 파일 [$CONFIG_FILE]  

디버그 모드에서 실행하기

디버그 모드는 정의되지 않은 동작이나 오류의 원인을 찾을 때 특히 유용합니다.

명령어를 디버그 모드에서 실행하려면 --debug로 명령어를 접두어 붙입니다:

gitlab-runner --debug <command>  

슈퍼유저 권한

GitLab Runner의 구성에 접근하는 명령어는 슈퍼유저(root)로 실행할 때 다르게 동작합니다. 파일 위치는 명령어를 실행하는 사용자에 따라 달라집니다.

gitlab-runner 명령어를 실행하면 실행 모드를 확인할 수 있습니다:

$ gitlab-runner run  

INFO[0000] /Users/ayufan/.gitlab-runner/config.toml에서 멀티 러너 시작 ...  builds=0  
WARN[0000] 사용자 모드에서 실행 중입니다.  
WARN[0000] 시스템 모드 사용:  
WARN[0000] $ sudo gitlab-runner...  

확실히 이 모드로 작업하고 싶다면 user-mode를 사용하세요. 그렇지 않으면 명령어에 sudo를 접두어 붙이세요:

$ sudo gitlab-runner run  

INFO[0000] /etc/gitlab-runner/config.toml에서 멀티 러너 시작 ...  builds=0  
INFO[0000] 시스템 모드에서 실행 중입니다.  

Windows의 경우, 명령 프롬프트를 관리자 권한으로 실행해야 할 수도 있습니다.

구성 파일

GitLab Runner 구성은 TOML 형식을 사용합니다.

편집할 파일은 다음과 같습니다:

1. *nix 시스템에서 GitLab Runner가 슈퍼유저(root)로 실행될 때: /etc/gitlab-runner/config.toml
2. *nix 시스템에서 GitLab Runner가 비루트로 실행될 때: ~/.gitlab-runner/config.toml
3. 다른 시스템에서: ./config.toml

대부분의 명령어는 사용자 지정 구성 파일을 지정하는 인수를 허용하므로 단일 머신에서 다양한 구성을 가질 수 있습니다. 사용자 지정 구성 파일을 지정하려면 -c 또는 --config 플래그를 사용하거나 CONFIG_FILE 환경 변수를 사용하세요.

신호

시스템 신호를 사용하여 GitLab Runner와 상호작용할 수 있습니다. 다음 명령어는 다음 신호를 지원합니다:

예를 들어, 러너의 구성 파일을 강제로 다시 로드하려면 다음을 실행하세요:

sudo kill -SIGHUP <main_runner_pid>  

정상 종료 시:

sudo kill -SIGQUIT <main_runner_pid>  

경고:
killall 또는 pkill을 정상 종료에 사용하지 마세요. shell 또는 docker 실행기를 사용하는 경우, 서브 프로세스를 종료하면서 신호 처리가 잘못될 수 있습니다. 작업을 처리하는 주요 프로세스에서만 사용하세요.

운영 체제가 서비스가 실패할 경우 자동으로 재시작하도록 구성된 경우(일부 플랫폼에서 기본값) 위의 신호로 종료할 경우 러너가 자동으로 재시작될 수 있습니다.

명령어 개요

인수가 없는 상태에서 gitlab-runner를 실행하면 다음과 같은 내용이 표시됩니다:

이름:
   gitlab-runner - GitLab Runner

사용법:
   gitlab-runner [전역 옵션] 명령 [명령 옵션] [인수...]

버전:
   16.5.0 (853330f9)

작성자:
   GitLab Inc. <support@gitlab.com>

명령어:
   list                  구성된 모든 러너 목록
   run                   다중 러너 서비스 실행
   register              새로운 러너 등록
   reset-token           러너의 토큰 재설정
   install               서비스 설치
   uninstall             서비스 제거
   start                 서비스 시작
   stop                  서비스 중지
   restart               서비스 재시작
   status                서비스 상태 가져오기
   run-single            단일 러너 시작
   unregister            특정 러너 등록 해제
   verify                모든 등록된 러너 검증
   artifacts-downloader  빌드 아티팩트 다운로드 및 추출 (내부)
   artifacts-uploader    빌드 아티팩트 생성 및 업로드 (내부)
   cache-archiver        캐시 아티팩트 생성 및 업로드 (내부)
   cache-extractor       캐시 아티팩트 다운로드 및 추출 (내부)
   cache-init            캐시 경로에 대한 권한 변경 (내부)
   health-check          특정 주소의 상태 검사
   read-logs             파일에서 작업 로그 읽기, Kubernetes 실행기에 의해 사용됨 (내부)
   help, h               명령어 목록 또는 특정 명령에 대한 도움을 표시합니다

전역 옵션:
   --cpuprofile value           cpu 프로파일을 파일에 기록 [$CPU_PROFILE]
   --debug                      디버그 모드 [$RUNNER_DEBUG]
   --log-format value           로그 형식 선택 (옵션: runner, text, json) [$LOG_FORMAT]
   --log-level value, -l value  로그 수준 (옵션: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
   --help, -h                   도움말 표시
   --version, -v                버전 인쇄

다음에서는 각 명령어가 수행하는 작업에 대해 자세히 설명합니다.

등록 관련 명령어

다음 명령어를 사용하여 새로운 러너를 등록하거나, 여전히 등록된 경우 목록 및 검증을 수행하세요.

• gitlab-runner register
  • 대화형 등록
  • 비대화형 등록
• gitlab-runner list
• gitlab-runner verify
• gitlab-runner unregister

이 명령어는 다음과 같은 인수를 지원합니다:

gitlab-runner register

이 명령어는 GitLab Runners API를 사용하여 러너를 GitLab에 등록합니다.

등록된 러너는 구성 파일 에 추가됩니다.

하나의 GitLab Runner 설치에서 여러 구성 을 사용할 수 있습니다. gitlab-runner register를 실행하면 새로운 구성 항목이 추가됩니다. 이전 항목은 제거되지 않습니다.

러너를 등록하는 두 가지 옵션이 있습니다:

• 대화형.
• 비대화형.

참고: 러너는 GitLab Runners API를 사용하여 직접 등록할 수 있지만, 구성은 자동으로 생성되지 않습니다.

대화형 등록

이 명령어는 일반적으로 대화형 모드 (기본값)로 사용됩니다. 러너 등록 중 여러 질문을 받게 됩니다.

등록 명령을 호출할 때 인수를 추가하여 이 질문을 미리 채울 수 있습니다:

gitlab-runner register --name my-runner --url "http://gitlab.example.com" --token my-authentication-token

또는 register 명령어 전에 환경 변수를 설정하여 구성할 수 있습니다:

export CI_SERVER_URL=http://gitlab.example.com
export RUNNER_NAME=my-runner
export CI_SERVER_TOKEN=my-authentication-token
gitlab-runner register

모든 가능한 인수와 환경을 확인하려면 다음을 실행하세요:

gitlab-runner register --help

비대화형 등록

비대화형 / 비대면 모드에서 등록을 사용할 수 있습니다.

등록 명령을 호출할 때 인수를 지정할 수 있습니다:

gitlab-runner register --non-interactive <other-arguments>

또는 register 명령 전에 환경 변수를 구성하여 지정할 수 있습니다:

<other-environment-variables>
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register

참고: 부울 매개변수는 --key={true|false}와 함께 명령줄에서 전달되어야 합니다.

[[runners]] 구성 템플릿 파일

• GitLab Runner 12.2에서 도입됨.

추가 옵션은 구성 템플릿 파일 기능을 사용하여 러너 등록 중에 쉽게 구성할 수 있습니다.

gitlab-runner list

이 명령은 구성 파일에 저장된 모든 러너를 나열합니다.

gitlab-runner verify

이 명령은 등록된 러너가 GitLab에 연결할 수 있는지 확인하지만, 러너가 GitLab Runner 서비스에 사용되고 있는지를 확인하지는 않습니다. 예제 출력은 다음과 같습니다:

러너 확인 중... 살아 있음                        러너=fee9938e
러너 확인 중... 살아 있음                        러너=0db52b31
러너 확인 중... 살아 있음                        러너=826f687f
러너 확인 중... 살아 있음                        러너=32773c0f

GitLab에서 제거된 오래된 러너를 제거하려면 다음 명령을 실행하십시오.

경고: 이 작업은 되돌릴 수 없습니다. 구성 파일을 업데이트하므로 실행하기 전에 config.toml의 백업을 만들어 두십시오.

gitlab-runner verify --delete

gitlab-runner unregister

이 명령은 GitLab 러너 API를 사용하여 등록된 러너를 등록 해제합니다.

다음 중 하나를 기대합니다:

• 전체 URL과 러너의 토큰.
• 러너의 이름.

--all-runners 옵션을 사용하면 모든 연결된 러너를 등록 해제합니다.

참고: 러너는 GitLab 러너 API를 통해 등록 해제할 수 있지만, 구성은 사용자를 위해 수정되지 않습니다.

• 러너 등록 토큰으로 생성된 러너는 gitlab-runner unregister 러너 인증 토큰으로 러너를 삭제합니다.
• GitLab UI 또는 러너 API로 생성된 러너는 gitlab-runner unregister 러너 인증 토큰으로 러너 관리자를 삭제하지만, 러너는 삭제하지 않습니다. 러너를 완전히 제거하려면 러너 관리 페이지에서 러너를 삭제하세요 또는 DELETE /runners REST API 엔드포인트를 사용하세요.

단일 러너의 등록을 해제하려면 먼저 gitlab-runner list를 실행하여 러너의 세부정보를 얻으십시오:

test-runner     Executor=shell Token=t0k3n URL=http://gitlab.example.com

그런 다음 이 정보를 사용하여 다음 명령 중 하나를 사용하여 등록을 해제합니다.

경고: 이 작업은 되돌릴 수 없습니다. 구성 파일을 업데이트하므로 실행하기 전에 config.toml의 백업을 만들어 두십시오.

URL 및 토큰으로

gitlab-runner unregister --url "http://gitlab.example.com/" --token t0k3n

이름으로

gitlab-runner unregister --name test-runner

모든 러너

gitlab-runner unregister --all-runners

gitlab-runner reset-token

이 명령은 GitLab Runners API를 사용하여 러너의 토큰을 재설정합니다.
이때 러너 ID
또는 현재 토큰을 사용할 수 있습니다.

러너의 이름(또는 URL 및 ID)과 러너 ID로 재설정할 경우 선택적으로 PAT가 필요합니다.
토큰이 이미 만료된 경우 PAT와 러너 ID를 사용해야 합니다.

--all-runners 옵션을 사용하면 모든 연결된 러너의 토큰을 재설정합니다.

러너의 현재 토큰으로

gitlab-runner reset-token --name test-runner

PAT 및 러너 이름으로

gitlab-runner reset-token --name test-runner --pat PaT

PAT, GitLab URL 및 러너 ID로

gitlab-runner reset-token --url "https://gitlab.example.com/" --id 12345 --pat PaT

모든 러너

gitlab-runners reset-token --all-runners

서비스 관련 명령

다음 명령을 사용하면 러너를 시스템 또는 사용자 서비스로 관리할 수 있습니다.
이들을 사용하여 러너 서비스를 설치, 제거, 시작 및 중지할 수 있습니다.

• gitlab-runner install
• gitlab-runner uninstall
• gitlab-runner start
• gitlab-runner stop
• gitlab-runner restart
• gitlab-runner status
• 다수의 서비스
• 서비스 관련 명령을 실행할 때 접근 거부

모든 서비스 관련 명령은 다음과 같은 인수를 허용합니다:

gitlab-runner install

이 명령은 GitLab Runner를 서비스로 설치합니다.
실행하는 시스템에 따라 다양한 인수 집합을 허용합니다.

Windows에서 실행하거나 슈퍼 사용자로 실행하는 경우, shell 실행기와 함께 실행되는 빌드의 권한을 낮출 수 있는 --user 플래그를 사용할 수 있습니다.

gitlab-runner uninstall

이 명령은 GitLab Runner가 서비스로 실행되는 것을 중지하고 제거합니다.

gitlab-runner start

이 명령은 GitLab Runner 서비스를 시작합니다.

gitlab-runner stop

이 명령은 GitLab Runner 서비스를 중지합니다.

gitlab-runner restart

이 명령은 GitLab Runner 서비스를 중지한 다음 시작합니다.

gitlab-runner status

이 명령은 GitLab Runner 서비스의 상태를 출력합니다. 서비스가 실행 중일 때 종료 코드는 0이고 서비스가 실행되고 있지 않을 때는 0이 아닙니다.

Multiple services

--service 플래그를 지정하여 여러 개의 GitLab Runner 서비스를 설치할 수 있으며, 여러 개의 별도 구성을 가질 수 있습니다.

Run-related commands

이 명령은 GitLab에서 빌드를 가져오고 처리할 수 있습니다.

gitlab-runner run

이 명령은 GitLab Runner가 서비스로 시작될 때 실행되는 주요 명령입니다. config.toml에서 정의된 모든 러너를 읽고 모두 실행하려고 합니다.

이 명령은 신호를 수신할 때까지 실행되고 작동합니다.

다음 매개변수를 허용합니다.

gitlab-runner run-single

• GitLab Runner 17.1에서 도입된 구성 파일을 사용할 수 있습니다.

이는 단일 GitLab 인스턴스에서 단일 빌드만 실행하는 데 사용할 수 있는 보조 명령입니다. 다음을 수행할 수 있습니다:

• GitLab URL 및 Runner 토큰을 포함하여 CLI 매개변수 또는 환경 변수로 모든 옵션을 사용할 수 있습니다. 예를 들어, 모든 매개변수를 명시적으로 지정한 단일 작업:

  gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:2.7
  

• 특정 러너의 구성을 사용하기 위해 구성 파일을 읽을 수 있습니다. 예를 들어, 구성 파일을 사용한 단일 작업:

  gitlab-runner run-single -c ~/.gitlab-runner/config.toml -r runner-name
  

--help 플래그를 사용하여 모든 가능한 구성 옵션을 볼 수 있습니다:

gitlab-runner run-single --help

--max-builds 옵션을 사용하여 러너가 종료되기 전 몇 개의 빌드를 실행할지를 제어할 수 있습니다. 기본값인 0은 러너에 빌드 제한이 없으며 작업이 영원히 실행됨을 의미합니다.

또한 --wait-timeout 옵션을 사용하여 러너가 작업을 기다리는 시간을 제어할 수 있습니다. 기본값인 0은 러너에 타임아웃이 없으며 작업 간 영원히 대기함을 의미합니다.

gitlab-runner exec (removed)

이 기능은 GitLab 15.7에서 사용 중지(deprecated)되었고 17.0에서 제거(removed)되었습니다.

파이프라인 구문과 검증 시뮬레이션은 GitLab 파이프라인 편집기에서 사용 가능합니다.

내부 명령어

GitLab Runner는 단일 바이너리로 배포되며, 빌드 중에 사용되는 몇 가지 내부 명령어를 포함하고 있습니다.

gitlab-runner artifacts-downloader

GitLab에서 아티팩트 아카이브를 다운로드합니다.

gitlab-runner artifacts-uploader

GitLab에 아티팩트 아카이브를 업로드합니다.

gitlab-runner cache-archiver

캐시 아카이브를 생성하고, 로컬에 저장하거나 외부 서버에 업로드합니다.

gitlab-runner cache-extractor

로컬 또는 외부에 저장된 파일에서 캐시 아카이브를 복원합니다.

문제 해결

아래는 몇 가지 일반적인 함정입니다.

서비스 관련 명령어를 실행할 때 Access Denied

일반적으로 서비스 관련 명령어는 관리자 권한이 필요합니다:

• Unix (Linux, macOS, FreeBSD) 시스템에서는 gitlab-runner 앞에 sudo를 붙이십시오.
• Windows 시스템에서는 상승된 명령 프롬프트를 사용하십시오. Administrator 명령 프롬프트를 실행하세요. 가장 간단한 방법은 Windows 검색 필드에 Command Prompt를 입력하고 마우스 오른쪽 버튼을 클릭한 후 Run as administrator를 선택하는 것입니다. 상승된 명령 프롬프트를 실행하려는 것을 확인하라는 메시지가 표시됩니다.

gitlab-runner stop가 정상적으로 종료되지 않음

러너가 호스트에 설치되어 로컬 실행자를 실행하는 경우 다운로드 또는 업로드 아티팩트, 캐시 처리와 같은 일부 작업을 위해 추가 프로세스를 시작합니다.

이 프로세스는 gitlab-runner 명령으로 실행되므로 pkill -QUIT gitlab-runner 또는 killall QUIT gitlab-runner를 사용하여 종료할 수 있습니다. 이들을 종료하면 이들이 담당하는 작업이 실패합니다.

이 문제를 방지하는 두 가지 방법이 있습니다:

• 러너를 로컬 서비스(예: systemd)로 등록하고 SIGQUIT을 종료 신호로 설정하고, gitlab-runner stop 또는 systemctl stop gitlab-runner.service를 사용하세요. 다음은 이 동작을 활성화하기 위한 구성 예입니다:

  ; /etc/systemd/system/gitlab-runner.service.d/kill.conf
  [Service]
  KillSignal=SIGQUIT
  TimeoutStopSec=infinity
  

  • 이 파일을 생성한 후, 구성을 적용하려면 systemd를 systemctl daemon-reload로 다시 로드하십시오.

• kill -SIGQUIT <pid>로 프로세스를 수동으로 종료하세요. gitlab-runner 프로세스의 pid를 찾아야 합니다. 시작 시 표시되므로 로그를 통해 이를 찾을 수 있습니다:

  $ gitlab-runner run
  Runtime platform                                    arch=arm64 os=linux pid=8 revision=853330f9 version=16.5.0
  

시스템 ID 상태 파일 저장: 접근 거부

GitLab Runner 15.7 및 15.8은 config.toml 파일이 포함된 디렉터리에 대한 쓰기 권한이 없으면 시작되지 않을 수 있습니다.

GitLab Runner가 시작되면, config.toml이 포함된 디렉터리에서 .runner_system_id 파일을 검색합니다. .runner_system_id 파일을 찾을 수 없으면 새로 생성합니다. GitLab Runner에 쓰기 권한이 없으면 시작에 실패합니다.

이 문제를 해결하려면, 파일 쓰기 권한을 임시로 허용한 후 gitlab-runner run을 실행하세요. .runner_system_id 파일이 생성된 후에는 읽기 전용으로 권한을 재설정할 수 있습니다.