- 환경 변수를 사용하기
- 디버그 모드에서 실행하기
- 슈퍼유저 권한
- 구성 파일
- 신호
- 명령어 개요
- 등록 관련 명령어
- 서비스 관련 명령
- Run-related commands
- 내부 명령어
- 문제 해결
-
gitlab-runner stop가 정상적으로 종료되지 않음
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 형식을 사용합니다.
편집할 파일은 다음과 같습니다:
- *nix 시스템에서 GitLab Runner가 슈퍼유저(
root)로 실행될 때:/etc/gitlab-runner/config.toml - *nix 시스템에서 GitLab Runner가 비루트로 실행될 때:
~/.gitlab-runner/config.toml - 다른 시스템에서:
./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>
경고:
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 버전 인쇄
다음에서는 각 명령어가 수행하는 작업에 대해 자세히 설명합니다.
등록 관련 명령어
다음 명령어를 사용하여 새로운 러너를 등록하거나, 여전히 등록된 경우 목록 및 검증을 수행하세요.
이 명령어는 다음과 같은 인수를 지원합니다:
| 매개변수 | 기본값 | 설명 |
|---|---|---|
--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 명령 전에 환경 변수를 구성하여 지정할 수 있습니다:
<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 /runnersREST 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 installgitlab-runner uninstallgitlab-runner startgitlab-runner stopgitlab-runner restartgitlab-runner status- 다수의 서비스
- 서비스 관련 명령을 실행할 때 접근 거부
모든 서비스 관련 명령은 다음과 같은 인수를 허용합니다:
| 매개변수 | 기본값 | 설명 |
|---|---|---|
--service |
gitlab-runner |
사용자 정의 서비스 이름 지정 |
--config |
구성 파일를 참조하십시오 | 사용할 사용자 정의 구성 파일 지정 |
gitlab-runner install
이 명령은 GitLab Runner를 서비스로 설치합니다.
실행하는 시스템에 따라 다양한 인수 집합을 허용합니다.
Windows에서 실행하거나 슈퍼 사용자로 실행하는 경우, shell 실행기와 함께 실행되는 빌드의 권한을 낮출 수 있는 --user 플래그를 사용할 수 있습니다.
| 매개변수 | 기본값 | 설명 |
|---|---|---|
--service |
gitlab-runner |
사용할 서비스 이름 지정 |
--config |
구성 파일을 참조하십시오 | 사용할 사용자 정의 구성 파일 지정 |
--syslog |
true (systemd가 아닌 시스템의 경우) |
서비스가 시스템 로깅 서비스와 통합되어야 하는지 여부 지정 |
--working-directory |
현재 디렉토리 | shell 실행기와 함께 빌드가 실행될 때 모든 데이터가 저장되는 루트 디렉토리 지정 |
--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이 아닙니다.
Multiple services
--service 플래그를 지정하여 여러 개의 GitLab Runner 서비스를 설치할 수 있으며, 여러 개의 별도 구성을 가질 수 있습니다.
Run-related commands
이 명령은 GitLab에서 빌드를 가져오고 처리할 수 있습니다.
gitlab-runner run
이 명령은 GitLab Runner가 서비스로 시작될 때 실행되는 주요 명령입니다. config.toml에서 정의된 모든 러너를 읽고 모두 실행하려고 합니다.
이 명령은 신호를 수신할 때까지 실행되고 작동합니다.
다음 매개변수를 허용합니다.
| Parameter | Default | Description |
|---|---|---|
--config |
See configuration-file | 사용될 사용자 정의 구성 파일을 지정합니다. |
--working-directory |
현재 디렉토리 | shell 실행기를 사용할 때 모든 데이터가 저장되는 루트 디렉토리를 지정합니다. |
--user |
현재 사용자 | 빌드를 실행하는 사용자를 지정합니다. |
--syslog |
false |
모든 로그를 SysLog(Unix) 또는 EventLog(Windows)로 전송합니다. |
--listen-address |
비어 있음 | Prometheus 메트릭 HTTP 서버가 수신해야 할 주소 (<host>:<port>) |
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 파일이 생성된 후에는 읽기 전용으로 권한을 재설정할 수 있습니다.
도움말