GitLab Runner 명령어

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

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

다음을 실행하여 명령어 디렉터리을 확인할 수 있습니다. 

gitlab-runner --help

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

gitlab-runner <command> --help

환경 변수 사용

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

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

gitlab-runner run --help

출력은 다음과 유사합니다: 

이름:
   gitlab-runner run - 다중 실행자 서비스 실행

사용법:
   gitlab-runner run [command options] [arguments...]

옵션들:
   -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>
caution
shell 또는 docker 실행자를 사용하는 경우 killall 또는 pkill을 사용하지 마십시오. 이는 하위 프로세스도 함께 종료되어 시그널이 적절하게 처리되지 않을 수 있습니다. 작업을 처리하는 주요 프로세스에만 사용하십시오.

서비스가 실패할 경우 (어떤 플랫폼의 기본 설정일 수 있음) 자동으로 다시 시작하도록 운영 체제가 구성된 경우 위의 시그널에 의해 종료된 경우 자동으로 실행자가 다시 시작될 수 있습니다.

명령어 개요

gitlab-runner를 인수 없이 실행하면 다음을 볼 수 있습니다: 

이름:
   gitlab-runner - a GitLab Runner

사용법:
   gitlab-runner [global options] command [command options] [arguments...]

버전:
   16.5.0 (853330f9)

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

COMMANDS:
   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             파일에서 작업 로그 읽기, 쿠버네티스 실행자에서 사용됨 (내부)
   help, h               명령어 디렉터리 또는 명령어에 대한 도움말 표시

GLOBAL OPTIONS:
   --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                버전 출력

아래에서 각 명령어가 하는 역할에 대해 상세히 설명합니다.

등록 관련 명령어

새 실행자를 등록하거나 등록된 실행자를 나열하고 확인하는 데 다음 명령어를 사용합니다.

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

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

gitlab-runner register

이 몤령어는 GitLab Runners API를 사용하여 GitLab에 실행자를 등록합니다.

등록된 실행자는 구성 파일에 추가됩니다. 한 대의 GitLab Runner 설치에서 여러 구성을 사용할 수 있습니다. gitlab-runner register를 실행하면 새 구성 항목이 추가됩니다. 기존 항목은 제거되지 않습니다.

실행자를 등록하는 두 가지 방법이 있습니다:

  • 대화식.
  • 비대화식.
note
실행자는 Runners API을 사용하여 직접 등록할 수 있지만 구성은 자동으로 생성되지 않습니다.

대화형 등록

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

이 질문은 등록 명령을 호출할 때 인수를 추가하여 미리 작성될 수 있습니다. 

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

또는 register 명령을 실행하기 전에 환경 변수를 구성함으로써 미리 작성할 수 있습니다. 

export CI_SERVER_URL=http://gitlab.example.com
export RUNNER_NAME=my-runner
export REGISTRATION_TOKEN=my-registration-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
note
부욜린 매개변수는 명령줄에서 --key={true|false}와 같이 전달해야 합니다.

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

  • 소개됨 in GitLab Runner 12.2.

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

gitlab-runner list

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

gitlab-runner verify

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

러너 확인... 활성화됨 runner=fee9938e
러너 확인... 활성화됨 runner=0db52b31
러너 확인... 활성화됨 runner=826f687f
러너 확인... 활성화됨 runner=32773c0f

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

caution
이 동작은 되돌릴 수 없습니다. 이것은 구성 파일을 업데이트하며, 실행하기 전에 config.toml의 백업을 꼭 확인하세요.
gitlab-runner verify --delete

gitlab-runner unregister

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

다음 중 하나가 필요합니다.

  • 완전한 URL 및 러너 토큰.
  • 러너 이름.

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

note
러너는 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

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

caution
이 동작은 되돌릴 수 없습니다. 이것은 구성 파일을 업데이트하며, 실행하기 전에 config.toml의 백업을 꼭 확인하세요.

URL 및 토큰으로 

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

이름으로 

gitlab-runner unregister --name test-runner
note
주어진 이름과 일치하는 러너가 여러 개인 경우 첫 번째 러너만 제거됩니다.

모든 러너 

gitlab-runner unregister --all-runners

gitlab-runner reset-token

이 명령은 GitLab 러너 API를 사용하여 러너 토큰을 재설정합니다. 러너 ID 또는 현재 토큰 을 사용하여 기대합니다.

러너의 이름(또는 URL 및 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

서비스 관련 명령

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

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

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

gitlab-runner install

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

Windows나 슈퍼 유저로 실행될 때 shell executor로 실행되는 빌드의 권한을 낮출 수 있는 --user 플래그를 허용합니다.

매개변수 기본값 설명
--service gitlab-runner 사용할 서비스 이름 지정
--config 구성 파일 참조 사용할 사용자 정의 구성 파일 특정
--syslog true(서비스가 systemd 시스템이 아닌 경우) 서비스가 시스템 로깅 서비스와 통합되어야 하는지 여부 명시
--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 서비스를 설치하고 별도의 구성으로 실행할 수 있습니다.

실행 관련 명령어

이 명령은 GitLab에서 빌드를 검색하고 처리하는 데 사용합니다.

gitlab-runner run

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

이 명령에는 다음 매개변수가 포함됩니다.

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

gitlab-runner run-single

이 명령은 단일 GitLab 인스턴스에서 하나의 빌드만 실행하는 데 사용할 수 있는 보조 명령어입니다. 구성 파일을 사용하지 않으며 옵션을 모두 매개변수 또는 환경 변수로 전달해야 합니다. GitLab URL 및 Runner 토큰도 지정해야 합니다.

예: 

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

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

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

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