GitLab Runner에는 러너를 등록하고, 관리하고, 빌드를 실행하는 데 사용하는 명령어 세트가 포함되어 있습니다.

다음을 실행하여 명령어 목록을 확인할 수 있습니다:

gitlab-runner --help

명령어 뒤에 --help를 추가하면 해당 명령어의 도움말 페이지를 볼 수 있습니다:

gitlab-runner <command> --help

환경 변수 사용#

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

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

gitlab-runner run --help

출력 결과는 다음과 비슷합니다:

NAME:
   gitlab-runner run - run multi runner service

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

OPTIONS:
   -c, --config "/Users/ayufan/.gitlab-runner/config.toml"      Config file [$CONFIG_FILE]

디버그 모드로 실행#

정의되지 않은 동작이나 오류의 원인을 찾고 있다면 디버그 모드를 사용하세요.

디버그 모드로 명령어를 실행하려면 명령어 앞에 --debug를 붙이세요:

gitlab-runner --debug <command>

슈퍼 유저 권한#

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

gitlab-runner 명령어를 실행하면 어떤 모드로 실행 중인지 표시됩니다:

$ gitlab-runner run

INFO[0000] Starting multi-runner from /Users/ayufan/.gitlab-runner/config.toml ...  builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...

이 모드로 작업하려는 것이 확실한 경우 user-mode를 사용하세요. 그렇지 않으면 명령어 앞에 sudo를 붙이세요:

$ sudo gitlab-runner run

INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml ...  builds=0
INFO[0000] Running in system-mode.

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

설정 파일#

GitLab Runner 설정은 TOML 형식을 사용합니다.

편집할 파일을 찾는 방법:

1. GitLab Runner가 슈퍼 유저(root)로 실행될 때 *nix 시스템: /etc/gitlab-runner/config.toml
2. GitLab Runner가 non-root로 실행될 때 *nix 시스템: ~/.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>

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

명령어 개요#

인수 없이 gitlab-runner를 실행하면 다음이 표시됩니다:

NAME:
   gitlab-runner - a GitLab Runner

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

VERSION:
   17.10.1 (ef334dcc)

AUTHOR:
   GitLab Inc. <support@gitlab.com>

COMMANDS:
   list                  List all configured runners
   run                   run multi runner service
   register              register a new runner
   reset-token           reset a runner's token
   install               install service
   uninstall             uninstall service
   start                 start service
   stop                  stop service
   restart               restart service
   status                get status of a service
   run-single            start single runner
   unregister            unregister specific runner
   verify                verify all registered runners
   wrapper               start multi runner service wrapped with gRPC manager server
   fleeting              manage fleeting plugins
   artifacts-downloader  download and extract build artifacts (internal)
   artifacts-uploader    create and upload build artifacts (internal)
   cache-archiver        create and upload cache artifacts (internal)
   cache-extractor       download and extract cache artifacts (internal)
   cache-init            changed permissions for cache paths (internal)
   health-check          check health for a specific address
   proxy-exec            execute internal commands (internal)
   read-logs             reads job logs from a file, used by kubernetes executor (internal)
   help, h               Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --cpuprofile value           write cpu profile to file [$CPU_PROFILE]
   --debug                      debug mode [$RUNNER_DEBUG]
   --log-format value           Choose log format (options: runner, text, json) [$LOG_FORMAT]
   --log-level value, -l value  Log level (options: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
   --help, -h                   show help
   --version, -v                print the version

아래에서 각 명령어가 상세하게 하는 일을 설명합니다.

등록 관련 명령어#

다음 명령어를 사용하여 새 러너를 등록하거나, 아직 등록되어 있는지 목록 확인 및 검증하세요.

• 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-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

[[runners]] 설정 템플릿 파일#

히스토리

• GitLab Runner 12.2에서 도입되었습니다.

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

gitlab-runner list#

이 명령어는 설정 파일에 저장된 모든 러너를 나열합니다.

gitlab-runner verify#

이 명령어는 등록된 러너가 GitLab에 연결할 수 있는지 확인합니다. 단, GitLab Runner 서비스에서 러너가 사용되고 있는지는 확인하지 않습니다. 출력 예시:

Verifying runner... is alive                        runner=fee9938e
Verifying runner... is alive                        runner=0db52b31
Verifying runner... is alive                        runner=826f687f
Verifying runner... is alive                        runner=32773c0f

GitLab에서 제거된 오래된 러너를 제거하려면 다음 명령어를 실행하세요.

gitlab-runner verify --delete

gitlab-runner unregister#

이 명령어는 GitLab Runners API를 사용하여 등록된 러너의 등록을 해제합니다.

다음 중 하나를 필요로 합니다:

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

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

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

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

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

그런 다음 이 정보를 사용하여 다음 명령어 중 하나로 등록을 해제하세요.

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 또는 슈퍼 유저로 실행할 때 --user 플래그를 허용하여 shell 실행기로 실행되는 빌드의 권한을 낮출 수 있습니다.

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이 아닌 값입니다.

여러 서비스#

--service 플래그를 지정하면 여러 개의 GitLab Runner 서비스를 별도의 여러 설정으로 설치할 수 있습니다.

사용자 서비스#

일부 init 시스템(예: systemd)을 사용하여 서비스를 사용자 서비스로 관리할 수 있습니다. init 시스템이 이 기능을 제공하고 gitlab-runner 서비스를 사용자 서비스로 관리하려면 서비스 관련 명령어를 실행할 때 --user-service 플래그를 지정하세요.

실행 관련 명령어#

이 명령어를 사용하여 GitLab에서 빌드를 가져오고 처리할 수 있습니다.

gitlab-runner run#

gitlab-runner run 명령어는 GitLab Runner가 서비스로 시작될 때 실행되는 메인 명령어입니다. config.toml에서 정의된 모든 러너를 읽고 모두 실행하려고 시도합니다.

명령어는 실행되어 신호를 받을 때까지 작동합니다.

다음 파라미터를 허용합니다.

gitlab-runner run-single#

히스토리

• 설정 파일 사용 기능이 GitLab Runner 17.1에서 도입되었습니다.

이 보조 명령어를 사용하여 단일 GitLab 인스턴스에서 단일 빌드를 실행하세요. 다음과 같이 사용할 수 있습니다:

• CLI 파라미터 또는 환경 변수로 GitLab URL과 러너 토큰을 포함한 모든 옵션을 사용합니다. 예를 들어 모든 파라미터가 명시적으로 지정된 단일 작업:

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

• 설정 파일에서 읽어 특정 러너 설정을 사용합니다. 예를 들어 설정 파일을 사용하는 단일 작업:

  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는 단일 바이너리로 배포되며 빌드 중에 사용되는 몇 가지 내부 명령어가 포함되어 있습니다.

gitlab-runner artifacts-downloader#

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

gitlab-runner artifacts-uploader#

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

gitlab-runner cache-archiver#

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

gitlab-runner cache-extractor#

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

트러블슈팅#

다음은 몇 가지 일반적인 문제입니다.

서비스 관련 명령어 실행 시 액세스 거부#

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

• Unix(Linux, macOS, FreeBSD) 시스템에서는 gitlab-runner 앞에 sudo를 붙이세요.
• Windows 시스템에서는 상승된 명령 프롬프트를 사용하세요. Administrator 명령 프롬프트를 실행하세요. Windows 검색 필드에 Command Prompt를 입력하고 마우스 오른쪽 버튼을 클릭하여 Run as administrator를 선택하세요. 상승된 명령 프롬프트를 실행하려는지 확인하세요.

gitlab-runner stop이 정상적으로 종료되지 않는 경우#

GitLab Runner가 호스트에 설치되어 로컬 실행기를 실행하는 경우 아티팩트 다운로드 또는 업로드, 캐시 처리와 같은 작업을 위한 추가 프로세스를 시작합니다. 이러한 프로세스는 gitlab-runner 명령어로 실행되므로 pkill -QUIT gitlab-runner 또는 killall QUIT gitlab-runner를 사용하여 종료할 수 있습니다. 종료하면 담당 작업이 실패합니다.

이를 방지하는 두 가지 방법:

• SIGQUIT를 종료 신호로 사용하는 로컬 서비스(예: systemd)로 러너를 등록하고 gitlab-runner stop 또는 systemctl stop gitlab-runner.service를 사용합니다. 이 동작을 활성화하는 예시 설정:

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

  • 설정 변경을 적용하려면 이 파일을 만든 후 systemctl daemon-reload로 systemd를 다시 로드하세요.

• 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 파일이 생성되면 권한을 읽기 전용으로 재설정할 수 있습니다.