GitLab Runner commands

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed

GitLab Runner에는 등록, 관리 및 빌드 실행에 사용하는 일련의 명령이 포함되어 있습니다.

아래와 같이 명령어 목록을 확인할 수 있습니다. 

gitlab-runner --help

명령 뒤에 --help를 붙여서 명령의 특정 도움말 페이지를 볼 수 있습니다. 

gitlab-runner <명령> --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가 루트가 아닌 사용자로 실행되는 *nix 시스템의 경우: ~/.gitlab-runner/config.toml
  3. 다른 시스템의 경우: ./config.toml

대부분의 명령은 사용자 지정 구성 파일을 지정하는 인수를 허용하므로 한 대상 장치에 여러 가지 다른 구성을 가질 수 있습니다. 사용자 정의 구성 파일을 지정하려면 -c 또는 --config 플래그를 사용하거나 CONFIG_FILE 환경 변수를 사용하십시오.

시그널

시스템 시그널을 사용하여 GitLab Runner와 상호 작용할 수 있습니다. 다음 명령이 다음 시그널을 지원합니다.

명령 시그널 동작
register SIGINT 등록된 러너 등록을 취소하고 이미 등록되어 있으면 삭제합니다.
run, run-single SIGINT, SIGTERM 실행 중인 모든 빌드를 중단하고 가능한 빨리 종료합니다. 두 번 사용하여 즉시 종료합니다 (강제 종료).
run, run-single SIGQUIT 새로운 빌드를 수락하지 않음. 현재 실행 중인 빌드가 완료될 때까지 종료합니다 (정상 종료).
run SIGHUP 구성 파일을 다시로드합니다.

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

sudo kill -SIGHUP <main_runner_pid>

정상 종료를 위해: 

sudo kill -SIGQUIT <main_runner_pid>

경고: shell 또는 docker executor를 사용하는 경우 killall 또는 pkill을 사용하지 마십시오. 이로 인해 하위 프로세스가 같이 종료되어 신호가 제대로 처리되지 않을 수 있습니다.

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

명령 개요

아래와 같이 gitlab-runner를 인수 없이 실행하면 다음을 볼 수 있습니다. 

NAME:
   gitlab-runner - a GitLab Runner

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

VERSION:
   16.5.0 (853330f9)

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

등록 관련 명령어

새 러너를 등록하거나 등록된 러너 목록을 확인하고 확인하는 데 사용하는 다음 명령어를 사용하세요.

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

매개변수 기본값 설명
--config 구성 파일 섹션 참조 사용할 사용자 정의 구성 파일 지정

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 명령 전에 환경 변수를 구성하여: 

<다른 환경 변수>
export REGISTER_NON_INTERACTIVE=true
gitlab-runner register

참고: 참/거짓 매개변수는 명령줄에서 --key={true|false}와 같이 전달되어야 합니다.

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

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

gitlab-runner list

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

gitlab-runner verify

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

러너 확인 중... 활성 상태입니다                      runner=fee9938e
러너 확인 중... 활성 상태입니다                      runner=0db52b31
러너 확인 중... 활성 상태입니다                      runner=826f687f
러너 확인 중... 활성 상태입니다                      runner=32773c0f

GitLab에서 제거된 이전 러너를 제거하려면 다음 명령을 실행합니다.

경고: 이 작업은 되돌릴 수 없습니다. 이는 구성 파일을 업데이트하므로 실행하기 전에 config.toml을 백업했는지 확인하세요. 

gitlab-runner verify --delete

gitlab-runner unregister

이 명령은 GitLab Runners API를 사용하여 등록된 러너의 등록을 취소합니다.

다음 중 하나를 예상합니다:

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

--all-runners 옵션과 함께 사용하면 모든 연결된 러너를 등록 취소합니다.

참고: 러너는 GitLab Runners API를 사용하여 등록 취소할 수 있지만, 사용자의 구성은 수정되지 않습니다.

  • 러너가 러너 등록 토큰으로 생성된 경우, 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

그런 다음 다음 명령 중 하나로 정보를 사용하여 등록을 취소합니다.

경고: 이 작업은 되돌릴 수 없습니다. 이는 구성 파일을 업데이트하므로 실행하기 전에 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

이 명령은 러너 ID 또는 현재 토큰](https://docs.gitlab.com/ee/api/runners.html#reset-runners-authentication-token-by-using-the-current-token)을 사용하여 GitLab Runners API를 통해 러너의 토큰을 재설정합니다.

러너의 이름(또는 URL 및 ID)과 선택적으로 토큰을 사용하는 경우 PAT가 필요합니다. --all-runners 옵션과 함께 사용하면 모든 연결된 러너의 토큰을 재설정합니다.

Runner의 현재 토큰을 사용하여 

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

PAT 및 Runner 이름 사용 

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

PAT, GitLab URL 및 Runner ID 사용 

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

모든 Runners 

gitlab-runners reset-token --all-runners

서비스 관련 명령어

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

서비스 관련된 모든 명령어는 이러한 매개변수를 허용합니다:

매개변수 기본값 설명
--service gitlab-runner 사용할 사용자 지정 서비스 이름 지정
--config 구성 파일 참조 사용할 사용자 정의 구성 파일 지정

gitlab-runner install

이 명령어는 GitLab Runner를 서비스로 설치합니다. 실행되는 시스템에 따라 다른 매개변수 세트를 허용합니다.

  • Windows에서 또는 관리자 권한으로 실행할 때는 –user 플래그를 허용하여 shell executor로 실행되는 빌드의 특권을 해제할 수 있습니다.
매개변수 기본값 설명
--service gitlab-runner 사용할 서비스 이름 지정
--config 구성 파일 참조 사용할 사용자 정의 구성 파일 지정
--syslog (systemd시스템이 아닌 경우) true 시스템 로깅 서비스에 통합해야 하는지 여부 지정
--working-directory 현재 디렉토리 shell executor로 빌드가 실행될 때 모든 데이터가 저장되는 루트 디렉토리를 지정
--user root 빌드를 실행하는 사용자 지정
--password 없음 빌드를 실행하는 사용자의 비밀번호 지정

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 서비스를 설치하고 별도의 구성을 사용할 수 있습니다.

Run 관련 명령어

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

gitlab-runner run

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

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

매개변수 기본값 설명
--config 구성 파일 참조 사용할 사용자 정의 구성 파일 지정
--working-directory 현재 디렉토리 shell executor로 빌드가 실행될 때 모든 데이터가 저장되는 루트 디렉토리 지정
--user 현재 사용자 빌드를 실행하는 사용자 지정
--syslog false 모든 로그를 SysLog(유닉스) 또는 EventLog(Windows)로 보내는지 여부 지정
--listen-address 비어있음 Prometheus 메트릭 HTTP 서버가 수신해야 하는 주소(<호스트>:<포트>)를 지정

gitlab-runner run-single

이는 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

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

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

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

gitlab-runner run-single --help

--max-builds 옵션을 사용하여 Runner가 종료되기 전에 실행하는 빌드 수를 제어할 수 있습니다. 0의 기본값은 Runner에 빌드 제한이 없고 작업이 영구적으로 실행됩니다.

또한 --wait-timeout 옵션을 사용하여 Runner가 작업 직전에 대기하는 시간을 제어할 수 있습니다. 0의 기본값은 Runner가 작업 사이에 영구적으로 대기합니다.

내부 명령어

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 시스템에서는 상위 명령 프롬프트를 사용합니다. 관리자 명령 프롬프트를 실행합니다. 가장 간단한 방법은 Windows 검색란에 명령 프롬프트를 입력하고 마우스 오른쪽 버튼을 클릭하여 관리자로 실행을 선택하는 것입니다. 이후, 실행 여부를 확인하는 메시지가 표시됩니다.

gitlab-runner stop 실행 시 우아하게 종료되지 않음

호스트에 설치된 러너가 로컬 실행자로 실행될 때 아티팩트를 다운로드하거나 업로드하거나 캐시를 처리하는 등의 작업을 수행하려면 추가 프로세스가 시작됩니다. 이러한 프로세스는 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 파일이 생성되면 권한을 읽기 전용으로 재설정할 수 있습니다.