---

Advanced configuration#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

GitLab Runner와 등록된 개별 러너의 동작을 변경하려면 config.toml 파일을 수정하세요.

config.toml 파일의 위치:

• GitLab Runner를 root로 실행하는 *nix 시스템의 경우 /etc/gitlab-runner/. 이 디렉터리는 서비스 구성 경로이기도 합니다.

• GitLab Runner를 root가 아닌 사용자로 실행하는 *nix 시스템의 경우 ~/.gitlab-runner/.

• 그 외 시스템의 경우 ./.

GitLab Runner는 대부분의 옵션을 변경해도 재시작이 필요하지 않습니다. 여기에는 [[runners]] 섹션의 파라미터와 전역 섹션의 대부분의 파라미터가 포함되며, listen_address는 예외입니다. 러너가 이미 등록되어 있다면 다시 등록할 필요가 없습니다.

GitLab Runner는 3초마다 구성 변경 사항을 확인하고 필요한 경우 다시 로드합니다. GitLab Runner는 SIGHUP 시그널에 응답하여 구성을 다시 로드하기도 합니다.

Configuration validation#

History

• GitLab Runner 15.10에서 도입됨

Configuration validation은 config.toml 파일의 구조를 검사하는 프로세스입니다. Configuration validator의 출력은 info 레벨 메시지만 제공합니다.

Configuration validation 프로세스는 정보 제공 목적으로만 사용됩니다. 이 출력을 통해 러너 구성의 잠재적 문제를 식별할 수 있습니다. Configuration validation은 모든 가능한 문제를 잡아내지 못할 수 있으며, 메시지가 없다고 해서 config.toml 파일이 완벽하다고 보장하지는 않습니다.

global 섹션#

이 설정들은 전역으로 적용됩니다. 모든 러너에 적용됩니다.

Configuration warnings#

Long polling issues#

GitLab Workhorse를 통해 GitLab long polling이 켜져 있을 때, 여러 구성 시나리오에서 GitLab Runner가 long polling 문제를 겪을 수 있습니다. 구성에 따라 성능 병목에서 심각한 처리 지연에 이르기까지 다양합니다. GitLab Runner worker가 장시간 long polling 요청에 멈춰 있을 수 있으며(GitLab Workhorse 구성 -apiCiLongPollingDuration과 일치하며 기본값은 50초), 이로 인해 다른 job이 제때 처리되지 못할 수 있습니다.

이 문제는 GitLab CI/CD long polling 기능과 관련이 있으며, GitLab Workhorse의 -apiCiLongPollingDuration 설정으로 제어됩니다. 켜져 있으면 job 요청이 job을 사용할 수 있을 때까지 구성된 시간만큼 최대로 대기할 수 있습니다.

기본 GitLab Workhorse long polling 구성 값은 50초입니다(최근 GitLab 버전에서는 기본적으로 켜져 있음).

다음은 몇 가지 구성 예시입니다:

• Omnibus: /etc/gitlab/gitlab.rb의 gitlab_workhorse['api_ci_long_polling_duration'] = "50s"

• Helm chart: gitlab.webservice.workhorse.extraArgs 설정 사용

• CLI: gitlab-workhorse -apiCiLongPollingDuration 50s

자세한 내용은 다음을 참조하세요:

• 러너의 Long polling

• Workhorse 구성

증상:

• 일부 프로젝트의 job이 시작 전 지연을 겪음(시간은 GitLab 인스턴스 long polling 타임아웃과 일치)

• 다른 프로젝트의 job은 즉시 실행됨

• 러너 로그의 경고 메시지: CONFIGURATION: Long polling issues detected

일반적인 문제 시나리오:

• Worker 고갈 병목: concurrent 설정이 러너 수보다 적음(심각한 병목)

• 요청 병목: request_concurrency=1인 러너가 long polling 중 job 지연 유발

• 빌드 제한 병목: limit 설정이 낮은(≤2) 러너와 request_concurrency=1의 조합

GitLab Runner는 문제 시나리오를 자동으로 감지하고 경고 메시지에 맞춤 해결책을 제공합니다. 일반적인 해결책은 다음과 같습니다:

• 러너 수를 초과하도록 concurrent 설정을 늘린다.

• 대용량 러너의 request_concurrency 값을 1보다 높게 설정한다(기본값은 1). 시스템 상태를 파악하고 최적값을 찾으려면 러너 모니터링 활성화를 고려하세요. FF_USE_ADAPTIVE_REQUEST_CONCURRENCY 기능 플래그는 워크로드에 따라 request_concurrency를 자동으로 조정하며 기본적으로 켜져 있습니다. 이를 끈 경우 다시 켜는 것을 고려하세요. 적응형 동시성에 대한 자세한 내용은 기능 플래그 문서를 참조하세요.

• 예상 job 볼륨에 맞게 limit 설정을 조정한다.

Example problematic configurations#

시나리오 1: Worker 고갈 병목:

concurrent = 2  # Only 2 concurrent workers

[[runners]]
  name = "runner-1"
[[runners]]
  name = "runner-2"
[[runners]]
  name = "runner-3"  # 3 runners, only 2 workers - severe bottleneck

시나리오 2: 요청 병목:

concurrent = 4  # 4 workers available

[[runners]]
  name = "high-volume-runner"
  request_concurrency = 1  # Default: only 1 request at a time
  limit = 10               # Can handle 10 jobs, but only 1 request slot

시나리오 3: 빌드 제한 병목:

concurrent = 4

[[runners]]
  name = "limited-runner"
  limit = 2                # Only 2 builds allowed
  request_concurrency = 1  # Only 1 request at a time
  # Creates severe bottleneck: builds at capacity + request slot blocked by long polling

Example corrected configuration#

concurrent = 4  # Adequate worker capacity

[[runners]]
  name = "high-volume-runner"
  request_concurrency = 3  # Allow multiple simultaneous requests
  limit = 10

[[runners]]
  name = "balanced-runner"
  request_concurrency = 2
  limit = 5

구성 예시:

# Example `config.toml` file

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file
log_level = "warning"
log_format = "text"
check_interval = 3 # Value in seconds

[[runners]]
  name = "first"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "shell"
  (...)

[[runners]]
  name = "second"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker"
  (...)

[[runners]]
  name = "third"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker-autoscaler"
  (...)

log_format examples (truncated)#

runner#

Runtime platform                                    arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...

Configuration loaded                                builds=0
listen_address not defined, metrics & debug endpoints disabled  builds=0
[session_server].listen_address not defined, session endpoints disabled  builds=0

text#

INFO[0000] Runtime platform                              arch=amd64 os=darwin pid=37773 revision=HEAD version="development version"
INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...
INFO[0000]
INFO[0000] Configuration loaded                          builds=0
INFO[0000] listen_address not defined, metrics & debug endpoints disabled  builds=0
INFO[0000] [session_server].listen_address not defined, session endpoints disabled  builds=0

json#

{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2025-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2025-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Running in user-mode.","time":"2025-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Use sudo for system-mode:","time":"2025-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2025-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2025-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"Configuration loaded","time":"2025-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address not defined, metrics & debug endpoints disabled","time":"2025-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2025-06-05T15:57:35+02:00"}

check_interval 작동 방식#

config.toml에 [[runners]] 섹션이 두 개 이상 있는 경우, GitLab Runner는 GitLab Runner가 구성된 GitLab 인스턴스에 job 요청을 지속적으로 예약하는 루프를 포함합니다.

다음 예시는 check_interval이 10초이고 두 개의 [[runners]] 섹션(runner-1과 runner-2)이 있는 경우입니다. GitLab Runner는 10초마다 요청을 보내고 5초간 대기합니다:

• check_interval 값을 가져옴(10s).

• 러너 목록을 가져옴(runner-1, runner-2).

• 대기 간격을 계산함(10s / 2 = 5s).

• 무한 루프 시작:

runner-1에 대한 job을 요청함.

• 5s 대기.

• runner-2에 대한 job을 요청함.

• 5s 대기.

기본적으로 러너는 job을 수신하면 사용 가능한 job이 없거나 실행 중인 job 수가 concurrent 또는 limit에 도달할 때까지 즉시 재폴링합니다. 이 동작을 변경하려면 strict_check_interval을 true로 설정하세요. 활성화하면 러너는 check 간격을 엄격하게 준수하여 job 수신 여부와 관계없이 check_interval초마다(이 예시에서는 5초) 한 번씩 요청을 보냅니다. 이 설정을 켜면 러너 집합 전체에 걸쳐 job 분배를 개선하고 한 러너가 대부분의 job을 처리하는 동안 다른 러너가 유휴 상태로 남는 것을 방지할 수 있습니다. 단, job이 큐에서 더 오래 대기할 수 있습니다.

check_interval 구성 예시:

# Example `config.toml` file

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file.
log_level = "warning"
log_format = "json"
check_interval = 10 # Value in seconds

[[runners]]
  name = "runner-1"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "shell"
  (...)

[[runners]]
  name = "runner-2"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker"
  (...)

이 예시에서 러너 프로세스의 job 요청은 5초마다 발생합니다. runner-1과 runner-2가 동일한 GitLab 인스턴스에 연결된 경우, 해당 GitLab 인스턴스도 이 러너로부터 5초마다 새 요청을 받습니다.

runner-1의 첫 번째 요청과 두 번째 요청 사이에는 두 번의 대기 기간이 발생합니다. 각 기간은 5초이므로, runner-1의 연속적인 요청 사이에는 약 10초가 소요됩니다. runner-2도 마찬가지입니다.

러너를 더 많이 정의할수록 대기 간격이 짧아집니다. 단, 특정 러너에 대한 요청은 다른 모든 러너의 요청 및 대기 기간이 호출된 후에 반복됩니다.

[machine] 섹션#

History

• GitLab Runner 18.10에서 도입됨.

[machine] 섹션은 docker+machine executor 제공자에 대한 전역 설정을 구성합니다. 이 설정은 docker+machine executor를 사용하는 모든 러너에 적용됩니다.

[machine.shutdown_drain] 섹션#

러너 프로세스가 종료될 때, 풀의 유휴 머신은 일반적으로 계속 실행 상태로 남습니다. 이를 외부에서 정리해야 합니다(예: systemd post-stop 훅 사용). shutdown_drain 섹션은 종료 시 러너가 유휴 머신을 자동으로 제거하도록 구성합니다.

드레인 작업은 전역 [`shutdown_timeout`](/19.2/runner/configuration/advanced-configuration/#the-global-section) 설정을 사용합니다.

기본 타임아웃인 30초는 머신 드레인에 일반적으로 너무 짧습니다. shutdown drain을 활성화할 때는 모든 머신이 제거될 수 있도록 shutdown_timeout을 늘려야 합니다. 최소 5분이 권장되며, 풀이 더 큰 경우 더 긴 타임아웃이 필요할 수 있습니다. 타임아웃이 너무 짧으면 러너가 경고를 기록합니다.

예시:

concurrent = 10
check_interval = 0
shutdown_timeout = 600  # 10 minutes - required for draining machines

[machine]
  [machine.shutdown_drain]
    enabled = true
    concurrency = 5
    max_retries = 3
    retry_backoff = "5s"

[[runners]]
  name = "my-runner"
  url = "https://gitlab.example.com/"
  token = "xxx"
  executor = "docker+machine"

  [runners.machine]
    IdleCount = 5
    IdleTime = 600
    MachineName = "auto-scale-%s"
    MachineDriver = "google"
    MachineOptions = ["google-project=my-project", "google-zone=us-central1-a"]

[session_server] 섹션#

job과 상호 작용하려면 [[runners]] 섹션 외부의 루트 레벨에 [session_server] 섹션을 지정합니다. 이 섹션은 개별 러너마다가 아닌 모든 러너에 대해 한 번만 구성합니다.

# Example `config.toml` file with session server configured

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file
log_level = "warning"
log_format = "runner"
check_interval = 3 # Value in seconds

[session_server]
  listen_address = "[::]:8093" # Listen on all available interfaces on port `8093`
  advertise_address = "runner-host-name.tld:8093"
  session_timeout = 1800

[session_server] 섹션을 구성할 때:

• listen_address 및 advertise_address는 host:port 형식을 사용합니다. 여기서 host는 IP 주소(127.0.0.1:8093) 또는 도메인(my-runner.example.com:8093)입니다. 러너는 이 정보를 사용하여 보안 연결을 위한 TLS 인증서를 생성합니다.

• GitLab이 listen_address 또는 advertise_address에 정의된 IP 주소 및 포트에 연결할 수 있는지 확인합니다.

• allow_local_requests_from_web_hooks_and_services 애플리케이션 설정을 활성화하지 않은 경우, advertise_address가 공인 IP 주소인지 확인합니다.

세션 서버 및 터미널 지원을 비활성화하려면 [session_server] 섹션을 삭제합니다.

러너 인스턴스가 이미 실행 중인 경우, `[session_server]` 섹션의 변경 사항을 적용하려면 `gitlab-runner restart`를 실행해야 할 수 있습니다.

GitLab Runner Docker 이미지를 사용하는 경우, docker run 명령에 -p 8093:8093을 추가하여 포트 8093을 노출해야 합니다.

[[runners]] 섹션#

각 [[runners]] 섹션은 하나의 러너를 정의합니다.

예시:

[[runners]]
  name = "example-runner"
  url = "http://gitlab.example.com/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
  clone_url = "http://gitlab.example.local"

민감한 값에 환경 변수 사용#

token 및 url 필드에 환경 변수를 사용하면 민감한 값을 구성 파일에 직접 저장하지 않아도 됩니다. $VAR 및 ${VAR} 구문 모두 지원됩니다.

[[runners]]
  name = "runner-1"
  url = "$GITLAB_URL"
  token = "${RUNNER_TOKEN_1}"
  executor = "docker"

[[runners]]
  name = "runner-2"
  url = "$GITLAB_URL"
  token = "${RUNNER_TOKEN_2}"
  executor = "docker"

이 기능은 다음과 같은 경우에 유용합니다:

• 토큰이 시크릿에서 마운트되는 쿠버네티스 배포

• 토큰이 환경 변수로 전달되는 Docker 배포

• 버전 관리되는 구성 파일에서 시크릿을 피하는 경우

레거시 /ci URL 접미사#

History

• GitLab Runner 1.0.0에서 더 이상 사용되지 않음(Deprecated).

• GitLab Runner 18.7.0에서 경고 추가됨.

GitLab Runner 1.0.0 이전 버전에서는 러너 URL이 /ci 접미사와 함께 구성되었습니다. 예를 들어 url = "https://gitlab.example.com/ci". 이 접미사는 더 이상 필요하지 않으며 구성에서 제거해야 합니다.

config.toml에 /ci 접미사가 포함된 URL이 있는 경우, GitLab Runner가 구성을 처리할 때 자동으로 이를 제거합니다. 단, 잠재적인 문제를 피하기 위해 구성 파일을 업데이트하여 접미사를 제거하는 것이 좋습니다.

알려진 문제#

• Git 서브모듈 인증 실패: GIT_SUBMODULE_FORCE_HTTPS=true로 설정된 경우, 서브모듈이 fatal: could not read Username for 'https://gitlab.example.com': terminal prompts disabled와 같은 인증 오류와 함께 클론에 실패할 수 있습니다. 이 문제는 /ci 접미사가 Git URL 재작성 규칙을 방해하기 때문에 발생합니다. 자세한 내용은 이슈 581678을 참조하세요.

문제가 있는 구성:

[[runners]]
  name = "legacy-runner"
  url = "https://gitlab.example.com/ci"  # Remove the /ci suffix
  token = "TOKEN"
  executor = "docker"

수정된 구성:

[[runners]]
  name = "legacy-runner"
  url = "https://gitlab.example.com"  # /ci suffix removed
  token = "TOKEN"
  executor = "docker"

GitLab Runner가 /ci 접미사가 포함된 URL로 시작하면 다음과 같은 경고 메시지를 기록합니다:

WARNING: The runner URL contains a legacy '/ci' suffix. This suffix is deprecated and should be
removed from the configuration. Git submodules may fail to clone with authentication errors if this
suffix is present. Please update the 'url' field in your config.toml to remove the '/ci' suffix.
See https://docs.gitlab.com/runner/configuration/advanced-configuration/#legacy-ci-url-suffix for more information.

이 경고를 해결하려면 config.toml 파일을 편집하여 url 필드에서 /ci 접미사를 제거합니다.

clone_url 작동 방식#

러너가 사용할 수 없는 URL에서 GitLab 인스턴스를 사용할 수 있는 경우, clone_url을 구성할 수 있습니다.

예를 들어, 방화벽이 러너의 URL 접근을 차단할 수 있습니다. 러너가 192.168.1.23 노드에 접근할 수 있으면 clone_url을 http://192.168.1.23으로 설정합니다.

clone_url이 설정된 경우, 러너는 http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git 형식의 클론 URL을 구성합니다.

`clone_url`은 Git LFS 엔드포인트 또는 아티팩트 업로드나 다운로드에는 영향을 미치지 않습니다.

Git LFS 엔드포인트 수정#

Git LFS 엔드포인트를 수정하려면 다음 파일 중 하나에서 pre_get_sources_script를 설정합니다:

config.toml:

pre_get_sources_script = "mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template; git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://<alternative-endpoint>"

.gitlab-ci.yml:

default:
  hooks:
    pre_get_sources_script:
      - mkdir -p $RUNNER_TEMP_PROJECT_DIR/git-template
      - git config -f $RUNNER_TEMP_PROJECT_DIR/git-template/config lfs.url https://localhost

unhealthy_requests_limit 및 unhealthy_interval 작동 방식#

GitLab 인스턴스를 오랫동안 사용할 수 없는 경우(예: 버전 업그레이드 중), 해당 러너는 유휴 상태가 됩니다. 러너는 GitLab 인스턴스가 다시 사용 가능해진 후 30~60분이 지나야 job 처리를 재개합니다.

러너가 유휴 상태로 전환되기까지 대기하는 시간을 늘리거나 줄이려면 unhealthy_interval 설정을 변경하세요.

GitLab 서버에 대한 러너의 연결 시도 횟수를 변경하고 유휴 상태가 되기 전에 비정상 슬립을 받으려면 unhealthy_requests_limit 설정을 변경하세요. 자세한 내용은 check_interval 작동 방식을 참조하세요.

Prepare Stage 타임아웃#

History

• GitLab Runner 19.0.0에서 도입됨.

prepare_timeout 설정은 러너가 job 스크립트를 실행하기 전에 실행 환경 준비에 소비하는 시간을 제한합니다. prepare stage는 두 가지 단계로 구성됩니다:

• Executor 초기화 (prepare_executor): 러너가 실행 환경을 설정합니다. 예를 들어 Docker 컨테이너 시작, 쿠버네티스 Pod 스케줄링, SSH 연결 등을 수행합니다.

• 셸 환경 설정 (prepare_script): 러너가 셸 환경(PATH, 작업 디렉터리, 셸 함수 등)을 초기화하는 스크립트를 생성하고 실행합니다. 이는 이후 job Stage에 필요한 환경을 준비합니다.

prepare stage가 prepare_timeout을 초과하면 job은 즉시 실패합니다. 이후 Stage (get_sources, restore_cache, script 등)는 prepare_timeout의 적용을 받지 않습니다. 해당 Stage들은 전체 job 타임아웃을 대신 사용합니다.

기본 동작: prepare_timeout이 설정되지 않았거나, 0이거나, job 타임아웃을 초과하는 경우, 러너는 prepare stage에 job 타임아웃을 사용합니다.

prepare_timeout을 설정해야 하는 경우#

느리거나 응답하지 않는 환경 초기화로 인해 job 작업이 시작되기 전에 전체 job 타임아웃이 소비될 수 있을 때 prepare_timeout을 설정하세요. 일반적인 시나리오는 다음과 같습니다:

• Docker 이미지 풀: 컨테이너 레지스트리가 느리거나 연결할 수 없는 경우, 이미지 풀이 전체 job 타임아웃 동안 중단될 수 있습니다. 바쁜 러너에서 중단된 풀은 사용 가능한 모든 job 슬롯을 채워 새 job 시작을 막습니다. prepare_timeout은 이런 job을 빠르게 실패 처리하여 러너 용량을 확보합니다.

• 사용자 정의 또는 HPC Executor: Executor가 HPC job 큐와 같은 외부 리소스 스케줄러의 용량 할당을 기다려야 하는 경우, 시작 시간이 예측 불가능하고 매우 길어질 수 있습니다. prepare_timeout 없이는 중단된 job이 전체 job 타임아웃 동안 러너 슬롯을 점유합니다.

설정 예시#

[[runners]]
  name = "my-runner"
  url = "https://gitlab.example.com/"
  token = "TOKEN"
  executor = "docker"
  prepare_timeout = "5m"

소스 가져오기 Stage에 대한 동일한 제어 방법은 get_sources_timeout을 참조하세요.

소스 가져오기 타임아웃#

History

• GitLab Runner 19.1.0에서 도입됨.

get_sources_timeout 설정은 러너가 프로젝트 리포지터리(서브모듈 포함)를 클론하거나 가져오는 get_sources stage에 소비하는 시간을 제한합니다.

get_sources stage가 get_sources_timeout을 초과하면 job은 즉시 실패합니다. 이후 Stage(restore_cache, download_artifacts, script)는 get_sources_timeout의 적용을 받지 않습니다. 해당 Stage들은 전체 job 타임아웃을 대신 사용합니다.

기본 동작: get_sources_timeout이 설정되지 않았거나, 0이거나, job 타임아웃을 초과하는 경우, 러너는 get_sources stage에 job 타임아웃을 사용합니다.

get_sources_timeout을 설정해야 하는 경우#

느리거나 응답하지 않는 네트워크 상태로 인해 리포지터리 가져오기가 완료되기 전에 전체 job 타임아웃이 소비될 수 있을 때 get_sources_timeout을 설정하세요. 일반적인 시나리오는 다음과 같습니다:

• 불안정한 네트워크에서의 Git 클론 중단: 클론 또는 가져오기 도중 원격 서버나 중간 네트워크가 느려지거나 연결할 수 없게 되면 작업이 전체 job 타임아웃 동안 중단될 수 있습니다. 바쁜 러너에서 중단된 job은 사용 가능한 모든 슬롯을 채워 새 job 시작을 막습니다. get_sources_timeout은 이런 job을 빠르게 실패 처리하여 러너 용량을 확보합니다.

• 서브모듈 가져오기 중단: 서브모듈은 종종 다른 호스트(다른 도메인, 서드파티 서비스)의 리포지터리를 참조합니다. 해당 호스트 중 하나가 느리거나 연결할 수 없게 되면 get_sources stage가 중단됩니다. 제한된 타임아웃은 단일 불량 서브모듈 호스트가 전체 job 타임아웃 동안 러너 슬롯을 점유하는 것을 방지합니다.

설정 예시#

[[runners]]
  name = "my-runner"
  url = "https://gitlab.example.com/"
  token = "TOKEN"
  executor = "docker"
  get_sources_timeout = "5m"

Executor 준비 Stage에 대한 동일한 제어 방법은 prepare_timeout을 참조하세요.

[runners.experimental.boot_verify] 섹션#

• Status: Experiment
  

boot_verify 섹션은 러너가 /health/ready를 보고하기 전에 프로세스 시작 시 러너를 통해 합성 job을 실행합니다. job이 실패하면 러너는 0이 아닌 코드로 종료되어 오케스트레이터가 러너를 재시작합니다. 이 동작은 인증은 가능하지만 작업을 프로비저닝하거나 디스패치할 수 없는 러너를 감지하며, 이는 기본 활성(liveness) 및 준비(readiness) 프로브가 놓치는 부분입니다. 이 검사는 프로세스 시작마다 한 번 실행되며 구성 다시 로드 시에는 다시 실행되지 않습니다.

합성 job은 러너의 기본 이미지에서 실행되므로 docker 및 kubernetes Executor에는 기본 이미지가 구성되어 있어야 합니다.

예시:

[[runners]]
  name = "my-runner"
  url = "https://gitlab.example.com/"
  token = "TOKEN"
  executor = "kubernetes"

  [runners.experimental.boot_verify]
    enabled = true
    timeout = "5m"
    acquire_min_backoff = "1s"
    acquire_max_backoff = "10s"

Executor#

다음 Executor를 사용할 수 있습니다.

셸#

셸 Executor를 사용하도록 설정된 경우 CI/CD job은 호스트 머신에서 로컬로 실행됩니다. 지원되는 운영 체제 셸은 다음과 같습니다:

shell 옵션이 bash 또는 sh로 설정되면 Bash의 ANSI-C quoting을 사용하여 job 스크립트를 셸 이스케이프 처리합니다.

POSIX 호환 셸 사용#

GitLab Runner 14.9 이상에서는 기능 플래그 활성화를 통해 FF_POSIXLY_CORRECT_ESCAPES라는 기능 플래그를 활성화하면 dash와 같은 POSIX 호환 셸을 사용할 수 있습니다. 활성화하면 POSIX 호환 셸 이스케이프 메커니즘인 “Double Quotes”가 사용됩니다.

[runners.docker] 섹션#

다음 설정은 Docker 컨테이너 파라미터를 정의합니다. 이 설정은 러너가 Docker Executor를 사용하도록 설정된 경우에 적용됩니다.

서비스로서의 Docker-in-Docker 또는 job 내에서 설정된 컨테이너 런타임은 이 파라미터를 상속하지 않습니다.

[[runners.docker.services]] 섹션#

job과 함께 실행할 추가 서비스를 지정합니다. 사용 가능한 이미지 목록은 Docker Registry를 참조하세요. 각 서비스는 별도의 컨테이너에서 실행되며 job에 연결됩니다.

예시:

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  memory = "128m"
  memory_swap = "256m"
  memory_reservation = "64m"
  oom_kill_disable = false
  cpuset_cpus = "0,1"
  cpuset_mems = "0,1"
  cpus = "2"
  dns = ["8.8.8.8"]
  dns_search = [""]
  service_memory = "128m"
  service_memory_swap = "256m"
  service_memory_reservation = "64m"
  service_cpuset_cpus = "0,1"
  service_cpus = "2"
  services_limit = 5
  privileged = false
  group_add = ["docker"]
  cap_add = ["NET_ADMIN"]
  cap_drop = ["DAC_OVERRIDE"]
  devices = ["/dev/net/tun"]
  disable_cache = false
  wait_for_services_timeout = 30
  cache_dir = ""
  volumes = ["/data", "/home/project/cache"]
  extra_hosts = ["other-host:127.0.0.1"]
  shm_size = 300000
  volumes_from = ["storage_container:ro"]
  links = ["mysql_container:mysql"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9", "redis:*", "mysql:*"]
  log_options = { env = "GITLAB_CI_JOB_ID,GITLAB_CI_JOB_NAME", labels = "com.gitlab.gitlab-runner.type" }
  [runners.docker.ulimit]
    "rtprio" = "99"
  [[runners.docker.services]]
    name = "registry.example.com/svc1"
    alias = "svc1"
    entrypoint = ["entrypoint.sh"]
    command = ["executable","param1","param2"]
    environment = ["ENV1=value1", "ENV2=value2"]
  [[runners.docker.services]]
    name = "redis:2.8"
    alias = "cache"
  [[runners.docker.services]]
    name = "postgres:9"
    alias = "postgres-db"
  [runners.docker.sysctls]
    "net.ipv4.ip_forward" = "1"

[runners.docker] 섹션의 볼륨#

볼륨에 대한 자세한 내용은 Docker 문서를 참조하세요.

다음 예시는 [runners.docker] 섹션에서 볼륨을 지정하는 방법을 보여줍니다.

예시 1: 데이터 볼륨 추가#

데이터 볼륨은 Union File System을 우회하는 하나 이상의 컨테이너 내 특별히 지정된 디렉터리입니다. 데이터 볼륨은 컨테이너의 수명 주기와 무관하게 데이터를 지속적으로 보존하도록 설계되었습니다.

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/volume/in/container"]

이 예시는 컨테이너 내 /path/to/volume/in/container 경로에 새 볼륨을 생성합니다.

예시 2: 호스트 디렉터리를 데이터 볼륨으로 마운트#

컨테이너 외부에 디렉터리를 저장하려는 경우, Docker 데몬 호스트의 디렉터리를 컨테이너에 마운트할 수 있습니다.

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  privileged = false
  disable_cache = true
  volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"]

이 예시는 CI/CD 호스트의 /path/to/bind/from/host를 컨테이너 내 /path/to/bind/in/container에서 사용합니다.

GitLab Runner 11.11 이상은 정의된 서비스에 대해서도 호스트 디렉터리를 마운트합니다.

Docker 로그 옵션#

log_options 파라미터를 사용하면 json-file 로그 드라이버에 대한 Docker 컨테이너 로그 옵션을 구성할 수 있습니다. 보안 및 호환성을 위해 env와 labels 옵션만 지원됩니다.

지원되는 로그 옵션#

• env: 로그 항목에 포함할 환경 변수 이름의 쉼표로 구분된 목록

• labels: 로그 항목에 포함할 컨테이너 라벨 이름의 쉼표로 구분된 목록

구성 예시#

다음은 몇 가지 구성 예시입니다.

[[runners]]
  [runners.docker]
    # Include specific environment variables in logs
    log_options = { env = "GITLAB_CI_JOB_ID,GITLAB_CI_JOB_NAME,CI_PIPELINE_ID" }

[[runners]]
  [runners.docker]
    # Include container labels in logs
    log_options = { labels = "com.gitlab.gitlab-runner.type" }

[[runners]]
  [runners.docker]
    # Include both environment variables and labels
    log_options = { env = "GITLAB_CI_JOB_ID,GITLAB_CI_JOB_NAME", labels = "com.gitlab.gitlab-runner.type" }

유효성 검사 및 오류 처리#

GitLab Runner는 executor 준비 중에 로그 옵션의 유효성을 검사합니다. max-size, max-file, compress와 같이 지원되지 않는 옵션을 지정하면 job이 즉시 구성 오류와 함께 실패합니다.

로그 옵션은 메인 job 컨테이너 및 CI/CD 구성에 정의된 모든 서비스 컨테이너에 적용됩니다.

Docker 로깅에 대한 자세한 내용은 Docker json-file 로그 드라이버 문서를 참조하세요.

프라이빗 컨테이너 레지스트리 사용#

job의 이미지 소스로 프라이빗 레지스트리를 사용하려면, CI/CD 변수 DOCKER_AUTH_CONFIG를 통해 인가를 구성하세요. 이 변수는 다음 중 한 곳에 설정할 수 있습니다.

• 프로젝트의 CI/CD 설정에서 file 유형으로 설정

• config.toml 파일에서 설정

if-not-present 풀 정책과 함께 프라이빗 레지스트리를 사용하면 보안상의 영향이 발생할 수 있습니다. 풀 정책 작동 방식에 대한 자세한 내용은 러너가 이미지를 가져오는 방법 구성을 참조하세요.

프라이빗 컨테이너 레지스트리 사용에 대한 자세한 내용은 다음을 참조하세요.

• 프라이빗 컨테이너 레지스트리에서 이미지 접근

• .gitlab-ci.yml 키워드 참조

러너가 수행하는 단계를 요약하면 다음과 같습니다.

• 이미지 이름에서 레지스트리 이름을 찾습니다.

• 값이 비어 있지 않으면, executor가 해당 레지스트리에 대한 인증 구성을 검색합니다.

• 마지막으로 지정된 레지스트리에 해당하는 인증이 발견되면, 이후의 풀 작업에 이를 사용합니다.

GitLab 통합 레지스트리 지원#

GitLab은 통합 레지스트리에 대한 자격 증명을 job 데이터와 함께 전송합니다. 이 자격 증명은 레지스트리의 인가 파라미터 목록에 자동으로 추가됩니다.

이 단계 이후, 레지스트리에 대한 인가는 DOCKER_AUTH_CONFIG 변수로 추가된 구성과 유사하게 진행됩니다.

job에서는 GitLab 통합 레지스트리의 이미지가 프라이빗이거나 보호된 경우에도 사용할 수 있습니다. job이 접근할 수 있는 이미지에 대한 정보는 CI/CD job 토큰 문서 문서를 참조하세요.

Docker 인가 해결 우선순위#

앞서 설명한 바와 같이, GitLab Runner는 다양한 방법으로 전송된 자격 증명을 사용하여 Docker를 레지스트리에 대해 인가할 수 있습니다. 올바른 레지스트리를 찾기 위해 다음과 같은 우선순위가 적용됩니다.

• DOCKER_AUTH_CONFIG로 구성된 자격 증명.

• GitLab Runner 호스트의 ~/.docker/config.json 또는 ~/.dockercfg 파일을 통해 로컬로 구성된 자격 증명 (예: 호스트에서 docker login 실행).

• job의 페이로드와 함께 기본으로 전송되는 자격 증명 (예: 앞서 설명한 통합 레지스트리에 대한 자격 증명).

레지스트리에 대해 처음 발견된 자격 증명이 사용됩니다. 예를 들어, 통합 레지스트리에 대한 자격 증명을 DOCKER_AUTH_CONFIG 변수로 추가하면 기본 자격 증명이 재정의됩니다.

[runners.parallels] 섹션#

다음 파라미터는 Parallels에 사용됩니다.

예시:

[runners.parallels]
  base_name = "my-parallels-image"
  template_name = ""
  disable_snapshots = false

[runners.virtualbox] 섹션#

다음 파라미터는 VirtualBox에 사용됩니다. 이 executor는 VirtualBox 머신을 제어하기 위해 vboxmanage 실행 파일에 의존하므로, Windows 호스트에서는 PATH 환경 변수를 조정해야 합니다: PATH=%PATH%;C:\Program Files\Oracle\VirtualBox.

예시:

[runners.virtualbox]
  base_name = "my-virtualbox-image"
  base_snapshot = "my-image-snapshot"
  disable_snapshots = false
  start_type = "headless"

start_type 파라미터는 가상 이미지 시작 시 사용할 그래픽 프론트엔드를 결정합니다. 유효한 값은 호스트 및 게스트 조합에서 지원하는 headless(기본값), gui, separate입니다.

기본 VM 이미지 재정의#

Parallels 및 VirtualBox executor 모두에서 base_name으로 지정된 기본 VM 이름을 재정의할 수 있습니다. 이를 위해 .gitlab-ci.yml 파일의 image 파라미터를 사용합니다.

하위 호환성을 위해 기본적으로 이 값을 재정의할 수 없습니다. base_name으로 지정된 이미지만 허용됩니다.

사용자가 .gitlab-ci.yml의 image 파라미터를 사용하여 VM 이미지를 선택할 수 있도록 허용하려면:

[runners.virtualbox]
  ...
  allowed_images = [".*"]

이 예시에서는 기존 VM 이미지를 모두 사용할 수 있습니다.

allowed_images 파라미터는 정규 표현식의 목록입니다. 필요에 따라 정밀하게 구성할 수 있습니다. 예를 들어, 특정 VM 이미지만 허용하려면 다음과 같은 정규식을 사용할 수 있습니다.

[runners.virtualbox]
  ...
  allowed_images = ["^allowed_vm[1-2]$"]

이 예시에서는 allowed_vm1과 allowed_vm2만 허용됩니다. 다른 시도는 오류가 발생합니다.

[runners.ssh] 섹션#

다음 파라미터는 SSH 연결을 정의합니다.

예시:

[runners.ssh]
  host = "my-production-server"
  port = "22"
  user = "root"
  password = "production-server-password"
  identity_file = ""

[runners.machine] 섹션#

다음 파라미터는 Docker Machine 기반 자동 스케일링 기능을 정의합니다. 자세한 내용은 Docker Machine Executor 자동 스케일링 구성을 참조하세요.

[[runners.machine.autoscaling]] 섹션#

다음 파라미터는 Instance 또는 Docker Autoscaler executor 사용 시 이용 가능한 구성을 정의합니다.

예시:

[runners.machine]
  IdleCount = 5
  IdleTime = 600
  MaxBuilds = 100
  MachineName = "auto-scale-%s"
  MachineDriver = "google" # Refer to Docker Machine docs on how to authenticate: https://docs.docker.com/machine/drivers/gce/#credentials
  MachineOptions = [
      # Additional machine options can be added using the Google Compute Engine driver.
      # If you experience problems with an unreachable host (ex. "Waiting for SSH"),
      # you should remove optional parameters to help with debugging.
      # https://docs.docker.com/machine/drivers/gce/
      "google-project=GOOGLE-PROJECT-ID",
      "google-zone=GOOGLE-ZONE", # e.g. 'us-central1-a', full list in https://cloud.google.com/compute/docs/regions-zones/
  ]
  [[runners.machine.autoscaling]]
    Periods = ["* * 9-17 * * mon-fri *"]
    IdleCount = 50
    IdleCountMin = 5
    IdleScaleFactor = 1.5 # Means that current number of Idle machines will be 1.5*in-use machines,
                          # no more than 50 (the value of IdleCount) and no less than 5 (the value of IdleCountMin)
    IdleTime = 3600
    Timezone = "UTC"
  [[runners.machine.autoscaling]]
    Periods = ["* * * * * sat,sun *"]
    IdleCount = 5
    IdleTime = 60
    Timezone = "UTC"

Periods 구문#

Periods 설정은 cron 스타일 형식으로 표현된 시간 주기의 문자열 패턴 배열을 포함합니다. 해당 줄은 다음 필드들로 구성됩니다:

[second] [minute] [hour] [day of month] [month] [day of week] [year]

표준 cron 설정 파일과 마찬가지로, 필드에는 단일 값, 범위, 목록, 별표를 사용할 수 있습니다. 구문에 대한 자세한 설명을 참조하세요.

[runners.instance] 섹션#

[runners.autoscaler] 섹션#

History

• Introduced in GitLab Runner v15.10.0.

다음 파라미터는 오토스케일러 기능을 구성합니다. 이 파라미터들은 Instance 및 Docker Autoscaler executor에서만 사용할 수 있습니다.

유휴 스케일 규칙으로 instance_ready_command가 자주 실패하는 경우, 러너가 job을 수락하는 것보다 더 빠르게 인스턴스가 삭제되고 생성될 수 있습니다. 스케일 스로틀링을 지원하기 위해 GitLab 17.0에서 지수 백오프가 추가되었습니다.

오토스케일러 구성 옵션은 구성 변경 시 다시 로드되지 않습니다. 단,

GitLab 17.5.0 이상에서는 구성이 변경될 때 [[runners.autoscaler.policy]] 항목이 다시 로드됩니다.

[runners.autoscaler.plugin_config] 섹션#

이 해시 테이블은 JSON으로 재인코딩되어 구성된 플러그인에 직접 전달됩니다.

fleeting 플러그인은 일반적으로 지원되는 구성에 대한 문서를 함께 제공합니다.

[runners.autoscaler.scale_throttle] 섹션#

History

• Introduced in GitLab Runner v17.0.0.

limit과 burst의 관계#

스케일 스로틀은 인스턴스를 생성하기 위해 토큰 할당량 시스템을 사용합니다. 이 시스템은 두 가지 값으로 정의됩니다:

• burst: 할당량의 최대 크기입니다.

• limit: 초당 할당량이 갱신되는 속도입니다.

한 번에 생성할 수 있는 인스턴스 수는 남아 있는 할당량에 따라 달라집니다. 할당량이 충분하면 해당 양만큼 인스턴스를 생성할 수 있습니다. 할당량이 소진되면 초당 limit개의 인스턴스를 생성할 수 있습니다. 인스턴스 생성이 중단되면 할당량은 burst 값에 도달할 때까지 초당 limit씩 증가합니다.

예를 들어, limit이 1이고 burst가 60인 경우:

• 60개의 인스턴스를 즉시 생성할 수 있지만 스로틀링이 적용됩니다.

• 60초를 기다리면 다시 60개의 인스턴스를 즉시 생성할 수 있습니다.

• 기다리지 않으면 초당 1개의 인스턴스를 생성할 수 있습니다.

[runners.autoscaler.connector_config] 섹션#

fleeting 플러그인은 일반적으로 지원되는 연결 옵션에 대한 문서를 함께 제공합니다.

플러그인은 커넥터 구성을 자동으로 업데이트합니다. [runners.autoscaler.connector_config]를 사용하여 커넥터 구성의 자동 업데이트를 재정의하거나, 플러그인이 결정할 수 없는 빈 값을 채울 수 있습니다.

[runners.autoscaler.state_storage] 섹션#

• Status: Beta
  

History

• Introduced in GitLab Runner 17.5.0.

상태 스토리지가 비활성화된 상태(기본값)에서 GitLab Runner가 시작되면, 안전을 위해 기존 fleeting 인스턴스가 즉시 삭제됩니다. 예를 들어, max_use_count가 1로 설정된 경우, 사용 현황을 알 수 없으면 이미 사용된 인스턴스에 job이 잘못 할당될 수 있습니다.

상태 스토리지 기능을 활성화하면 인스턴스의 상태가 로컬 디스크에 유지됩니다. 이 경우 GitLab Runner가 시작될 때 인스턴스가 존재하면 삭제되지 않습니다. 캐시된 연결 세부 정보, 사용 횟수 및 기타 구성이 복원됩니다.

상태 스토리지 기능을 활성화할 때 다음 사항을 고려하세요:

인스턴스의 인증 세부 정보(사용자 이름, 비밀번호, 키)는 디스크에 남아 있습니다.

인스턴스가 job을 활발히 실행 중인 상태에서 복원되면, GitLab Runner는 기본적으로 해당 인스턴스를 삭제합니다. 이 동작은 GitLab Runner가 job을 재개할 수 없으므로 안전성을 보장합니다. 인스턴스를 유지하려면 keep_instance_with_acquisitions를 true로 설정하세요.

keep_instance_with_acquisitions를 true로 설정하면 인스턴스에서 진행 중인 job에 대해 신경 쓰지 않을 때 유용합니다. 또한 instance_ready_command 구성 옵션을 사용하여 인스턴스를 유지하기 위해 환경을 정리할 수 있습니다. 여기에는 실행 중인 모든 명령을 중지하거나 Docker 컨테이너를 강제로 삭제하는 것이 포함될 수 있습니다.

[[runners.autoscaler.policy]] 섹션#

참고 - 이 맥락에서 idle_count는 레거시 오토스케일링 방식에서처럼 오토스케일된 머신의 수가 아니라 job의 수를 나타냅니다.

유휴 인스턴스를 제거할지 결정하기 위해, taskscaler는 idle_time을 인스턴스의 유휴 지속 시간과 비교합니다. 각 인스턴스의 유휴 기간은 인스턴스가 다음 시점부터 계산됩니다:

• 마지막으로 job을 완료한 시점(이전에 사용된 인스턴스인 경우).

• 프로비전된 시점(한 번도 사용되지 않은 경우).

이 확인은 스케일링 이벤트 중에 수행됩니다. 구성된 idle_time을 초과한 인스턴스는, 필요한 idle_count job 용량을 유지하기 위해 필요하지 않은 한 삭제됩니다.

scale_factor가 설정되면, idle_count는 최소 idle 용량이 되고 scaler_factor_limit은 최대 idle 용량이 됩니다.

여러 정책을 정의할 수 있습니다. 마지막으로 일치하는 정책이 사용됩니다.

다음 예시에서는 월요일부터 금요일까지 08:00~15:59 사이에 유휴 횟수 1이 사용됩니다. 그 외의 경우 유휴 횟수는 0입니다.

[[runners.autoscaler.policy]]
  idle_count        = 0
  idle_time         = "0s"
  periods           = ["* * * * *"]

[[runners.autoscaler.policy]]
  idle_count        = 1
  idle_time         = "30m0s"
  periods           = ["* 8-15 * * mon-fri"]

Periods 구문#

periods 설정은 정책이 활성화되는 기간을 나타내는 unix-cron 형식 문자열의 배열을 포함합니다. cron 형식은 5개의 필드로 구성됩니다:

 ┌────────── minute (0 - 59)
 │ ┌──────── hour (0 - 23)
 │ │ ┌────── day of month (1 - 31)
 │ │ │ ┌──── month (1 - 12)
 │ │ │ │ ┌── day of week (1 - 7 or MON-SUN, 0 is an alias for Sunday)
 * * * * *

• -를 두 숫자 사이에 사용하여 범위를 지정할 수 있습니다.

• *를 사용하여 해당 필드의 유효한 값 전체 범위를 나타낼 수 있습니다.

• / 뒤에 숫자를 사용하거나 범위 뒤에 사용하여 해당 범위를 해당 숫자만큼 건너뛸 수 있습니다. 예를 들어, 시간 필드에 0-12/2를 사용하면 00:00에서 00:12 사이의 매 2시간마다 기간이 활성화됩니다.

• ,를 사용하여 필드에 유효한 숫자나 범위의 목록을 구분할 수 있습니다. 예: 1,2,6-9.

이 cron job은 시간의 범위를 나타낸다는 점을 기억하는 것이 중요합니다. 예를 들어:

[runners.autoscaler.vm_isolation] 섹션#

VM Isolation은 nesting을 사용하며, 이는 macOS에서만 지원됩니다.

[runners.autoscaler.vm_isolation.connector_config] 섹션#

[runners.autoscaler.vm_isolation.connector_config] 섹션의 파라미터는 [runners.autoscaler.connector_config] 섹션과 동일하지만, 오토스케일된 인스턴스가 아닌 nesting으로 프로비전된 가상 머신에 연결하는 데 사용됩니다.

[runners.custom] 섹션#

다음 파라미터는 커스텀 executor에 대한 구성을 정의합니다.

[runners.cache] 섹션#

다음 파라미터는 분산 캐시 기능을 정의합니다. 자세한 내용은 러너 오토스케일 문서를 참조하세요.

다음 환경 변수를 사용하여 캐시 압축을 구성할 수 있습니다:

tarzstd 형식은 TAR과 Zstandard 압축을 함께 사용하며, zip보다 더 나은 압축률을 제공합니다. 압축 수준은 fastest(최대 속도를 위한 최소 압축)부터 slowest(가장 작은 파일 크기를 위한 최대 압축)까지 다양합니다. default 수준은 압축률과 속도 사이의 균형 잡힌 절충안을 제공합니다.

예시:

job:
  variables:
    CACHE_COMPRESSION_FORMAT: tarzstd
    CACHE_COMPRESSION_LEVEL: fast

병렬 캐시 오브젝트 스토리지 전송#

기본적으로, 캐시 다운로드는 단일 HTTP GET 또는 GoCloud 읽기 스트림을 사용하며, GoCloud 경로(예: RoleARN이 있는 S3)를 사용하는 캐시 업로드는 한 번에 하나의 동시 멀티파트 파트를 사용합니다.

FF_USE_PARALLEL_CACHE_TRANSFER 기능 플래그를 사용하여 오브젝트 스토리지에 대한 빠른 링크에서 더 높은 처리량을 활성화할 수 있습니다. 활성화되면:

• 다운로드 시 백엔드가 범위를 지원하고 캐시 오브젝트가 하나의 청크보다 큰 경우, 여러 동시 범위 GET(사전 서명된 URL; HEAD 대신 작은 초기 Range 요청이 사용됨 — HEAD는 S3와 같은 GET 전용 사전 서명된 URL에서 자주 실패함) 또는 동시 GoCloud 범위 읽기를 사용할 수 있습니다.

• 업로드 시 GoCloud 경로에서 동시 파트를 사용한 멀티파트 업로드를 사용합니다.

기능 플래그가 꺼져 있으면 아래 변수와 관계없이 동작이 변경되지 않습니다. 다음 job 환경 변수로 병렬 처리를 조정할 수 있습니다(cache-extractor 및 cache-archiver 헬퍼에서 읽음):

예시:

job:
  variables:
    FF_USE_PARALLEL_CACHE_TRANSFER: "true"
    CACHE_CONCURRENCY: "8"
    CACHE_CHUNK_SIZE: "16777216"

병렬 아티팩트 다운로드 (직접 다운로드)#

기본적으로, direct_download가 오브젝트 스토리지로 리다이렉트를 반환하면 러너는 단일 HTTP GET 스트림으로 아티팩트를 다운로드합니다.

오브젝트 스토리지 백엔드가 Content-Range 합계가 포함된 206 Partial Content를 지원할 때 병렬 HTTP Range GET을 허용하려면 FF_USE_PARALLEL_ARTIFACT_TRANSFER 기능 플래그를 활성화하십시오. 청크 크기와 동시성은 러너에서 고정됩니다(CACHE_* 변수가 아님). 이 플래그는 FF_USE_PARALLEL_CACHE_TRANSFER와 독립적입니다.

예시:

job:
  variables:
    FF_USE_PARALLEL_ARTIFACT_TRANSFER: "true"

캐시 메커니즘은 사전 서명된 URL을 사용하여 캐시를 업로드하고 다운로드합니다. URL은 GitLab Runner가 자체 인스턴스에서 서명합니다. job의 스크립트(캐시 업로드/다운로드 스크립트 포함)가 로컬 또는 외부 머신에서 실행되는지는 중요하지 않습니다. 예를 들어, shell 또는 docker 실행기는 GitLab Runner 프로세스가 실행 중인 동일한 머신에서 스크립트를 실행합니다. 동시에 virtualbox 또는 docker+machine은 스크립트를 실행하기 위해 별도의 VM에 연결합니다. 이 프로세스는 보안상의 이유로, 캐시 어댑터의 자격 증명이 유출될 가능성을 최소화하기 위한 것입니다.

S3 캐시 어댑터가 IAM 인스턴스 프로파일을 사용하도록 구성된 경우, 어댑터는 GitLab Runner 머신에 연결된 프로파일을 사용합니다. 마찬가지로 GCS 캐시 어댑터의 경우, CredentialsFile을 사용하도록 구성된 경우 해당 파일이 GitLab Runner 머신에 존재해야 합니다.

이 표는 register를 위한 config.toml, CLI 옵션 및 환경 변수를 나열합니다. 이러한 환경 변수를 정의하면 새 GitLab Runner를 등록한 후 해당 값이 config.toml에 저장됩니다.

config.toml에서 S3 자격 증명을 생략하고 환경에서 정적 자격 증명을 로드하려면 AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY를 정의할 수 있습니다. 자세한 내용은 AWS SDK 기본 자격 증명 체인 섹션을 참조하십시오.

캐시 키 처리#

History

• GitLab Runner 18.4.0에서 도입됨.

• FF_HASH_CACHE_KEYS가 활성화된 경우 분산 캐시의 오브젝트 경로가 샤드 접두사를 포함하도록 GitLab Runner 19.0에서 변경됨.

GitLab Runner 18.4.0 이상에서는 FF_HASH_CACHE_KEYS 기능 플래그를 사용하여 캐시 키를 해시할 수 있습니다.

FF_HASH_CACHE_KEYS가 꺼져 있을 때(기본값), GitLab Runner는 캐시 키를 사용하여 로컬 캐시 파일과 스토리지 버킷의 오브젝트 경로를 모두 구성하기 전에 캐시 키를 정제합니다. 정제로 인해 캐시 키가 변경되면 GitLab Runner는 이 변경 사항을 기록합니다. GitLab Runner가 캐시 키를 정제할 수 없는 경우에도 이를 기록하며, 해당 특정 캐시를 사용하지 않습니다.

이 기능 플래그를 켜면, GitLab Runner는 로컬 캐시 아티팩트와 원격 스토리지 버킷의 오브젝트 경로를 구성하기 전에 캐시 키(SHA-256)를 해시합니다. GitLab Runner는 캐시 키를 정제하지 않습니다. 어떤 캐시 키가 특정 캐시 아티팩트를 생성했는지 이해하는 데 도움을 주기 위해 GitLab Runner는 해당 아티팩트에 메타데이터를 첨부합니다:

로컬 캐시 아티팩트의 경우, GitLab Runner는 캐시 아티팩트 cache.zip 옆에 다음 내용을 포함하는 metadata.json 파일을 배치합니다:

{"cachekey": "the human readable cache key"}

분산 캐시의 캐시 아티팩트의 경우, GitLab Runner는 cachekey 키를 사용하여 스토리지 오브젝트 블롭에 메타데이터를 직접 첨부합니다. 클라우드 제공업체의 메커니즘을 사용하여 이를 조회할 수 있습니다. 예시는 AWS S3의 사용자 정의 오브젝트 메타데이터를 참조하십시오.

FF_HASH_CACHE_KEYS를 사용한 분산 캐시 오브젝트 경로#

GitLab Runner 19.0 이상에서 FF_HASH_CACHE_KEYS가 활성화된 경우, GitLab Runner는 분산 캐시 오브젝트 경로에 SHA-256 해시의 처음 두 16진수 문자를 샤드 접두사로 삽입합니다:

[path/][runner/<token>/]project/<project_id>/<shard>/<hash>/cache.zip

예시:

runner/abc123/project/42/d0/d03a852ba491ba611e907b1ef60ad5c4516a05b8f3aae6abb77f42bc60325aed/cache.zip

이렇게 하면 프로젝트당 256개의 고유한 오브젝트 접두사에 캐시 오브젝트가 분산되어, 많은 병렬 job이 높은 요청 속도로 캐시에 접근할 때 발생하는 Amazon S3 503 (Slow Down) 응답을 방지합니다.

GitLab Runner 19.0으로 업그레이드하는 것은 `FF_HASH_CACHE_KEYS`를 사용하는 경우 브레이킹 체인지입니다.

FF_HASH_CACHE_KEYS가 이미 활성화된 상태에서 GitLab Runner 19.0 이상으로 업그레이드하면, 샤드 접두사로 인해 분산 스토리지의 모든 캐시 아티팩트에 대한 오브젝트 경로가 변경됩니다. 이전 경로 (.../<hash>/cache.zip)에 저장된 기존 오브젝트는 접근할 수 없게 됩니다. 업그레이드 후 첫 번째 job 실행 시 캐시 미스와 캐시 아티팩트 재빌드가 예상됩니다.

캐시 키 처리 동작 요약#

FF_HASH_CACHE_KEYS를 변경하면, 캐시 키를 해시하는 것이 캐시 아티팩트의 이름과 위치를 변경하기 때문에 GitLab Runner는 기존 캐시 아티팩트를 무시합니다. 이 변경은 FF_HASH_CACHE_KEYS=true에서 FF_HASH_CACHE_KEYS=false로의 방향 및 그 반대 방향 모두에 적용됩니다.

분산 캐시를 공유하지만 FF_HASH_CACHE_KEYS에 대한 설정이 다른 여러 러너를 실행하는 경우, 캐시 아티팩트를 공유하지 않습니다.

따라서 모범 사례는 다음과 같습니다:

분산 캐시를 공유하는 러너들 전체에서 FF_HASH_CACHE_KEYS를 동기화 상태로 유지하십시오.

FF_HASH_CACHE_KEYS를 변경한 후 캐시 미스, 캐시 아티팩트 재빌드 및 첫 번째 job 실행 시간이 길어지는 것을 예상하십시오.

GitLab Runner가 기본 캐시 위치와 대체 캐시 위치를 모두 확인하는 전환 기간 동안 추가 네트워크 요청이 발생하는 것을 예상하십시오.

`FF_HASH_CACHE_KEYS`를 켜더라도 이전 버전의 헬퍼 바이너리를 실행하는 경우

(예: 헬퍼 이미지를 이전 버전으로 고정했기 때문에), 캐시 키를 해시하고 캐시를 업로드하거나 다운로드하는 것은 여전히 작동합니다. 그러나 GitLab Runner는 캐시 아티팩트의 메타데이터를 유지하지 않습니다.

[runners.cache.s3] 섹션#

다음 매개변수는 캐시를 위한 S3 스토리지를 정의합니다.

예시:

[runners.cache]
  Type = "s3"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.s3]
    ServerAddress = "s3.amazonaws.com"
    AccessKey = "AWS_S3_ACCESS_KEY"
    SecretKey = "AWS_S3_SECRET_KEY"
    BucketName = "runners-cache"
    BucketLocation = "eu-west-1"
    Insecure = false
    ServerSideEncryption = "KMS"
    ServerSideEncryptionKeyID = "alias/my-key"

인증#

GitLab Runner는 구성에 따라 S3에 대해 다양한 인증 방법을 사용합니다.

정적 자격 증명#

러너는 다음과 같은 경우 정적 액세스 키 인증을 사용합니다:

• ServerAddress, AccessKey, SecretKey 매개변수가 지정되어 있지만 AuthenticationType이 제공되지 않은 경우.

• AuthenticationType = "access-key"가 명시적으로 설정된 경우.

AWS SDK 기본 자격 증명 체인#

러너는 다음과 같은 경우 AWS SDK 기본 자격 증명 체인을 사용합니다:

• ServerAddress, AccessKey, SecretKey 중 하나라도 생략되고 AuthenticationType이 제공되지 않은 경우.

• AuthenticationType = "iam"이 명시적으로 설정된 경우.

자격 증명 체인은 다음 순서로 인증을 시도합니다:

• 환경 변수(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)

• 공유 자격 증명 파일(~/.aws/credentials)

• IAM 인스턴스 프로파일(EC2 인스턴스의 경우)

• SDK에서 지원하는 기타 AWS 자격 증명 소스

RoleARN이 지정되지 않은 경우, 기본 자격 증명 체인은 러너 매니저에 의해 실행되며, 이는 빌드가 실행되는 머신과 반드시 동일한 머신일 필요가 없습니다. 예를 들어, 자동 스케일 구성에서 job은 다른 머신에서 실행됩니다. 마찬가지로, 쿠버네티스 실행기의 경우 빌드 Pod도 러너 매니저와 다른 노드에서 실행될 수 있습니다. 이 동작은 러너 매니저에만 버킷 수준 액세스를 부여할 수 있도록 합니다.

RoleARN이 지정된 경우, 자격 증명은 헬퍼 이미지의 실행 컨텍스트 내에서 확인됩니다. 자세한 내용은 RoleARN을 참조하세요.

Helm 차트를 사용하여 GitLab Runner를 설치하고 values.yaml 파일에서 rbac.create가 true로 설정된 경우, 서비스 계정이 생성됩니다. 서비스 계정의 어노테이션은 rbac.serviceAccountAnnotations 섹션에서 가져옵니다.

Amazon EKS의 러너에서는 서비스 계정에 할당할 IAM 권한을 지정할 수 있습니다. 필요한 특정 어노테이션은 eks.amazonaws.com/role-arn: arn:aws:iam:::role/입니다.

이 권한에 대한 IAM 정책에는 지정된 버킷에 대해 다음 작업을 수행할 권한이 있어야 합니다:

• s3:PutObject

• s3:GetObjectVersion

• s3:GetObject

• s3:DeleteObject

• s3:ListBucket

KMS 유형의 ServerSideEncryption을 사용하는 경우, 이 권한에는 지정된 AWS KMS 키에 대해 다음 작업을 수행할 권한도 있어야 합니다:

• kms:Encrypt

• kms:Decrypt

• kms:ReEncrypt*

• kms:GenerateDataKey*

• kms:DescribeKey

SSE-C 유형의 ServerSideEncryption은 지원되지 않습니다. SSE-C는 사용자가 제공한 키를 포함하는 헤더를 사전 서명된 URL과 함께 다운로드 요청에 제공해야 합니다. 이는 키 소재를 job에 전달해야 함을 의미하며, 이 경우 키를 안전하게 보관할 수 없습니다. 이로 인해 복호화 키가 유출될 가능성이 있습니다. 이 문제에 대한 논의는 이 머지 리퀘스트에서 확인할 수 있습니다.

AWS S3 캐시에 업로드할 수 있는 단일 파일의 최대 크기는 5GB입니다.

이 동작에 대한 잠재적 해결 방법에 대한 논의는 이 이슈에서 확인할 수 있습니다.

러너 캐시용 S3 버킷에서 KMS 키 암호화 사용#

GenerateDataKey API는 KMS 대칭 키를 사용하여 클라이언트 측 암호화를 위한 데이터 키를 생성합니다(https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). KMS 키 구성은 다음과 같아야 합니다:

rbac.serviceAccountName에 정의된 ServiceAccount에 할당된 권한에 대한 IAM 정책에는 KMS 키에 대해 다음 작업을 수행할 권한이 있어야 합니다:

• kms:GetPublicKey

• kms:Decrypt

• kms:Encrypt

• kms:DescribeKey

• kms:GenerateDataKey

RoleARN으로 멀티파트 전송 활성화#

캐시에 대한 접근을 제한하기 위해, 러너 매니저는 job이 캐시에서 다운로드하거나 업로드할 때 시간 제한이 있는 사전 서명된 URL을 생성합니다. 그러나 AWS S3는 단일 PUT 요청을 5GB로 제한합니다. 5GB보다 큰 파일의 경우 멀티파트 업로드 API를 사용해야 합니다.

멀티파트 전송은 AWS S3에서만 지원되며 다른 S3 제공업체에서는 지원되지 않습니다. 러너 매니저는 여러 프로젝트의 job을 처리하므로, 버킷 전체 권한이 있는 S3 자격 증명을 공유할 수 없습니다. 대신 러너 매니저는 시간 제한이 있는 사전 서명된 URL과 범위가 좁은 자격 증명을 사용하여 특정 객체 하나에 대한 접근만 허용합니다.

AWS에서 S3 멀티파트 전송을 사용하려면 RoleARN에 IAM 권한을 arn:aws:iam:::: 형식으로 지정하세요. 이 권한은 버킷의 특정 blob에 쓸 수 있는 범위가 좁은 시간 제한 AWS 자격 증명을 생성합니다. 원래 S3 자격 증명이 지정된 RoleARN에 대해 AssumeRole에 접근할 수 있는지 확인하세요.

RoleARN에 지정된 IAM 권한에는 다음 권한이 있어야 합니다:

• BucketName에 지정된 버킷에 대한 s3:GetObject 접근 권한.

• BucketName에 지정된 버킷에 대한 s3:PutObject 접근 권한.

• BucketName에 지정된 버킷에 대한 s3:ListBucket 접근 권한.

• KMS 또는 DSSE-KMS를 사용한 서버 측 암호화가 활성화된 경우 kms:Decrypt 및 kms:GenerateDataKey.

예를 들어, ARN이 arn:aws:iam::1234567890123:role/my-instance-role인 EC2 인스턴스에 my-instance-role이라는 IAM 권한이 연결되어 있다고 가정합니다.

BucketName에 대해 s3:PutObject 권한만 있는 새 권한 arn:aws:iam::1234567890123:role/my-upload-role을 생성할 수 있습니다. my-instance-role의 AWS 설정에서 Trust relationships는 다음과 유사하게 보일 수 있습니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::1234567890123:role/my-upload-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

my-instance-role을 RoleARN으로 재사용하여 새 권한 생성을 피할 수도 있습니다. my-instance-role에 AssumeRole 권한이 있는지 확인하세요. 예를 들어, EC2 인스턴스와 연결된 IAM 프로파일의 Trust relationships는 다음과 같을 수 있습니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com",
                "AWS": "arn:aws:iam::1234567890123:role/my-instance-role"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

AWS 명령줄 인터페이스를 사용하여 인스턴스에 AssumeRole 권한이 있는지 확인할 수 있습니다. 예:

aws sts assume-role --role-arn arn:aws:iam::1234567890123:role/my-upload-role --role-session-name gitlab-runner-test1

RoleARN으로 업로드 작동 방식#

RoleARN이 있는 경우, 러너가 캐시에 업로드할 때마다 다음이 수행됩니다:

러너 매니저가 원래 S3 자격 증명(AuthenticationType, AccessKey, SecretKey를 통해 지정됨)을 가져옵니다.

S3 자격 증명으로, 러너 매니저는 RoleARN과 함께 Amazon Security Token Service(STS)에 AssumeRole 요청을 보냅니다. 정책 요청은 다음과 유사하게 보입니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:PutObject"],
            "Resource": "arn:aws:s3:::/"
        }
    ]
}

요청이 성공하면, 러너 매니저는 제한된 세션으로 임시 AWS 자격 증명을 얻습니다.

러너 매니저는 이러한 자격 증명과 URL을 s3://<bucket name>/<filename> 형식으로 캐시 아카이버에 전달하고, 아카이버는 파일을 업로드합니다.

AssumeRole Prometheus 메트릭#

RoleARN이 설정된 경우, GitLab Runner는 STS 요청 동작 모니터링을 위해 다음 Prometheus 메트릭을 노출합니다:

Kubernetes ServiceAccount 리소스에 IAM 권한 활성화#

서비스 계정에 IAM 권한을 사용하려면, 클러스터에 대한 IAM OIDC 공급자가 존재해야 합니다. IAM OIDC 공급자가 클러스터와 연결된 후, 러너의 서비스 계정과 연결할 IAM 권한을 생성할 수 있습니다.

Create Role 창의 Select type of trusted entity 아래에서 Web Identity를 선택합니다.

권한의 Trusted Relationships tab에서:

Trusted entities 섹션은 다음 형식이어야 합니다: arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/. OIDC ID는 EKS 클러스터의 Configuration 탭에서 확인할 수 있습니다.

Condition 섹션에는 rbac.serviceAccountName에 정의된 GitLab Runner 서비스 계정 또는 rbac.create가 true로 설정된 경우 생성된 기본 서비스 계정이 있어야 합니다:

S3 Express One Zone 버킷 사용#

History

• GitLab Runner 17.5.0에서 도입됨.

  S3 Express One Zone 디렉터리 버킷은 RoleARN과 함께 작동하지 않습니다. 러너 매니저가 특정 객체 하나에 대한 접근을 제한할 수 없기 때문입니다.

• Amazon 튜토리얼에 따라 S3 Express One Zone 버킷을 설정합니다.

• BucketName 및 BucketLocation으로 config.toml을 구성합니다.

• S3 Express는 듀얼 스택 엔드포인트를 지원하지 않으므로 DualStack을 false로 설정합니다.

config.toml 예시:

[runners.cache]
  Type = "s3"
  [runners.cache.s3]
    BucketName = "example-express--usw2-az1--x-s3"
    BucketLocation = "us-west-2"
    DualStack = false

[runners.cache.gcs] 섹션#

다음 파라미터는 Google Cloud Storage에 대한 기본 지원을 정의합니다. 이러한 값에 대한 자세한 내용은 Google Cloud Storage(GCS) 인증 문서를 참조하세요.

예시:

config.toml 파일에 직접 구성된 자격 증명:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    AccessID = "cache-access-account@test-project-123456.iam.gserviceaccount.com"
    PrivateKey = "-----BEGIN PRIVATE KEY-----\nXXXXXX\n-----END PRIVATE KEY-----\n"
    BucketName = "runners-cache"
    UniverseDomain = "googleapis.com"  # Optional

GCP에서 다운로드한 JSON 파일의 자격 증명:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    CredentialsFile = "/etc/gitlab-runner/service-account.json"
    BucketName = "runners-cache"
    UniverseDomain = "googleapis.com"  # Optional

GCP 메타데이터 서버의 애플리케이션 기본 자격 증명(ADC):

GitLab Runner와 Google Cloud ADC를 함께 사용하는 경우, 일반적으로 기본 서비스 계정을 사용합니다. 이 경우 인스턴스에 자격 증명을 별도로 제공하지 않아도 됩니다:

[runners.cache]
  Type = "gcs"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.gcs]
    BucketName = "runners-cache"
    UniverseDomain = "googleapis.com"  # Optional

ADC를 사용하는 경우, 사용하는 서비스 계정에 iam.serviceAccounts.signBlob 권한이 있는지 확인하세요. 일반적으로 이 권한은 서비스 계정에 Service Account Token Creator 역할을 부여하는 방식으로 설정합니다.

GKE의 Workload Identity Federation#

GKE의 Workload Identity Federation은 애플리케이션 기본 자격 증명(ADC)을 통해 지원됩니다. 워크로드 아이덴티티가 정상적으로 작동하지 않는 경우:

러너 Pod 로그(빌드 로그가 아님)에서 ERROR: generating signed URL 메시지를 확인하세요. 이 오류는 다음과 같은 권한 문제를 나타낼 수 있습니다:

IAM returned 403 Forbidden: Permission 'iam.serviceAccounts.getAccessToken' denied on resource (or it may not exist).

러너 Pod 내부에서 다음 curl 명령을 실행해 보세요:

curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/email

이 명령은 올바른 쿠버네티스 서비스 계정을 반환해야 합니다. 다음으로, 액세스 토큰을 가져오세요:

curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token?scopes=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform

명령이 성공하면 액세스 토큰이 포함된 JSON 페이로드가 반환됩니다. 실패하는 경우 서비스 계정 권한을 확인하세요.

[runners.cache.azure] 섹션#

다음 파라미터는 Azure Blob Storage에 대한 기본 지원을 정의합니다. 자세한 내용은 Azure Blob Storage 문서를 참조하세요. S3와 GCS는 객체 모음을 bucket이라고 부르는 반면, Azure는 블롭 모음을 container라는 단어로 표현합니다.

예시:

[runners.cache]
  Type = "azure"
  Path = "path/to/prefix"
  Shared = false
  [runners.cache.azure]
    AccountName = ""
    AccountKey = ""
    ContainerName = "runners-cache"
    StorageDomain = "blob.core.windows.net"

Azure 워크로드 및 관리 아이덴티티#

History

• Introduced in GitLab Runner v17.5.0.

Azure 워크로드 또는 관리 아이덴티티를 사용하려면 구성에서 AccountKey를 생략하세요. AccountKey가 비어 있으면 러너는 다음을 시도합니다:

• DefaultAzureCredential을 사용하여 임시 자격 증명을 가져옵니다.

• User Delegation Key를 가져옵니다.

• 해당 키로 SAS 토큰을 생성하여 Storage Account 블롭에 접근합니다.

인스턴스에 Storage Blob Data Contributor 역할이 할당되어 있는지 확인하세요. 인스턴스가 위 작업을 수행할 권한이 없는 경우, GitLab Runner는 AuthorizationPermissionMismatch 오류를 보고합니다.

Azure 워크로드 아이덴티티를 사용하려면 runner.kubernetes 섹션에 아이덴티티와 연결된 service_account 및 Pod 라벨 azure.workload.identity/use를 추가하세요. 예를 들어, service_account가 gitlab-runner인 경우:

  [runners.kubernetes]
    service_account = "gitlab-runner"
    [runners.kubernetes.pod_labels]
      "azure.workload.identity/use" = "true"

service_account에 azure.workload.identity/client-id 어노테이션이 연결되어 있는지 확인하세요:

serviceAccount:
  annotations:
    azure.workload.identity/client-id: 

GitLab 17.7 이상에서는 이 구성만으로 워크로드 아이덴티티를 설정하기에 충분합니다.

그러나 GitLab Runner 17.5 및 17.6에서는 러너 매니저에 다음도 추가로 구성해야 합니다:

• azure.workload.identity/use Pod 라벨

• 워크로드 아이덴티티에 사용할 서비스 계정

예를 들어, GitLab Runner Helm 차트를 사용하는 경우:

serviceAccount:
  name: "gitlab-runner"
podLabels:
  azure.workload.identity/use: "true"

이 라벨이 필요한 이유는 자격 증명을 서로 다른 소스에서 가져오기 때문입니다. 캐시 다운로드 시에는 러너 매니저에서 자격 증명을 가져옵니다. 캐시 업로드 시에는 helper image를 실행하는 Pod에서 자격 증명을 가져옵니다.

자세한 내용은 이슈 38330을 참조하세요.

[runners.artifact] 섹션#

History

• Introduced in GitLab Runner 18.10.

다음 파라미터는 러너가 job 아티팩트를 업로드할 때 사용하는 HTTP 타임아웃을 제어합니다. 네트워크가 느리거나, 아티팩트 크기가 크거나, 스토리지 백엔드 지연이 높은 환경에서는 기본 1시간 업로드 타임아웃이 부족할 수 있습니다. 더 빠르게 실패하도록 줄이는 것도 고려할 수 있습니다.

예상되는 가장 큰 아티팩트 크기와 사용 가능한 대역폭에 맞게 upload_timeout을 설정하세요.

예시:

[runners.artifact]
  upload_timeout = "2h"
  response_header_timeout = "15m"

[runners.kubernetes] 섹션#

다음 표는 쿠버네티스 executor에서 사용할 수 있는 구성 파라미터를 나열합니다. 추가 파라미터는 쿠버네티스 executor 문서를 참조하세요.

예시:

[runners.kubernetes]
  host = "https://45.67.34.123:4892"
  cert_file = "/etc/ssl/kubernetes/api.crt"
  key_file = "/etc/ssl/kubernetes/api.key"
  ca_file = "/etc/ssl/kubernetes/ca.crt"
  image = "golang:1.8"
  privileged = true
  allow_privilege_escalation = true
  image_pull_secrets = ["docker-registry-credentials", "optional-additional-credentials"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9.4", "postgres:latest"]
  logs_base_dir = "/tmp"
  scripts_base_dir = "/tmp"
  [runners.kubernetes.node_selector]
    gitlab = "true"

Helper image#

docker, docker+machine, 또는 kubernetes executor를 사용하는 경우, GitLab Runner는 Git, 아티팩트, 캐시 작업을 처리하기 위해 특정 컨테이너를 사용합니다. 이 컨테이너는 helper image라는 이름의 이미지로 생성됩니다.

helper image는 amd64, arm, arm64, s390x, ppc64le, riscv64 아키텍처를 지원합니다. 이 이미지에는 gitlab-runner-helper 바이너리가 포함되어 있으며, 이는 GitLab Runner 바이너리의 특수 컴파일 버전입니다. 사용 가능한 명령의 일부만 포함되어 있으며, Git, Git LFS, SSL 인증서 저장소가 포함됩니다.

helper image에는 alpine, alpine3.21, alpine-latest, ubi-fips, ubuntu 등 여러 버전이 있습니다. 작은 용량으로 인해 alpine 이미지가 기본값입니다. helper_image_flavor = "ubuntu"를 설정하면 helper image의 ubuntu 버전을 선택합니다.

GitLab Runner 16.1에서 17.1까지는 alpine이 alpine3.18의 별칭입니다. GitLab Runner 17.2에서 17.6까지는 alpine3.19의 별칭입니다. GitLab Runner 17.7 이상에서는 alpine3.21의 별칭입니다. GitLab Runner 18.4 이상에서는 alpine-latest의 별칭입니다.

alpine-latest 버전은 기본 이미지로 alpine:latest를 사용하며, 새로운 업스트림 버전이 릴리즈될 때 자연스럽게 버전이 업그레이드됩니다.

GitLab Runner가 DEB 또는 RPM 패키지로 설치된 경우, 지원되는 아키텍처용 이미지가 호스트에 설치됩니다. Docker Engine에서 지정된 이미지 버전을 찾지 못하면, 러너는 job을 실행하기 전에 자동으로 다운로드합니다. docker와 docker+machine executor 모두 이와 같은 방식으로 동작합니다.

alpine 버전의 경우, 기본 alpine 버전 이미지만 패키지에 포함됩니다. 다른 모든 버전은 레지스트리에서 다운로드됩니다.

kubernetes executor와 GitLab Runner를 수동으로 설치하는 경우는 다르게 동작합니다.

• 수동 설치의 경우, gitlab-runner-helper 바이너리가 포함되지 않습니다.

• kubernetes executor의 경우, 쿠버네티스 API는 로컬 아카이브에서 gitlab-runner-helper 이미지를 로드하는 것을 허용하지 않습니다.

두 경우 모두, GitLab Runner는 helper image를 다운로드합니다. 다운로드할 태그는 GitLab Runner 리비전과 아키텍처에 의해 결정됩니다.

Arm의 쿠버네티스를 위한 Helper image 구성#

기본적으로 아키텍처에 맞는 helper image가 자동으로 선택됩니다. arm64 쿠버네티스 클러스터에서 arm64 helper image를 사용하기 위해 커스텀 helper_image 경로를 설정해야 하는 경우, 구성 파일에서 다음 값을 설정하세요:

[runners.kubernetes]
  helper_image = "my.registry.local/gitlab/gitlab-runner-helper:arm64-v${CI_RUNNER_VERSION}"

Windows 헬퍼 이미지 선택#

Windows에서 GitLab Runner는 호스트의 Windows 버전 및 CPU 아키텍처(x86_64 또는 arm64)와 일치하는 헬퍼 이미지를 자동으로 선택합니다.

ARM64 헬퍼 이미지는 현재 Windows Server 2025(24H2)에서만 사용할 수 있습니다.

사용 가능한 이미지 목록은 Windows 헬퍼 이미지를 참조하세요.

구 버전의 Alpine Linux를 사용하는 러너 이미지#

History

• Introduced in GitLab Runner 14.5.

이미지는 여러 버전의 Alpine Linux로 빌드됩니다. 최신 버전의 Alpine을 사용할 수도 있지만, 동시에 이전 버전도 사용할 수 있습니다.

helper image의 경우, helper_image_flavor를 변경하거나 Helper image 섹션을 참조하세요.

GitLab Runner 이미지의 경우, 동일한 방식으로 alpine, alpine3.19, alpine3.21, 또는 alpine-latest를 이미지 버전 앞에 접두사로 사용합니다:

docker pull gitlab/gitlab-runner:alpine3.19-v16.1.0

Alpine pwsh 이미지#

GitLab Runner 16.1 이상에서는 고정된 Alpine 플레이버(alpine3.18, alpine3.19, alpine3.21)에 pwsh 변형이 있습니다. GitLab Runner 17.8 이상에서는 alpine-latest 플레이버에도 pwsh 변형이 있습니다. 이러한 이미지는 Alpine 기본 이미지 위에 PowerShell linux-musl 빌드를 설치하므로 모든 Alpine 버전을 지원합니다.

예시:

docker pull registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:alpine3.21-x86_64-v17.7.0-pwsh

Helper image 레지스트리#

GitLab 15.0 이하에서는 Docker Hub의 이미지를 사용하도록 helper image를 구성합니다.

GitLab 15.1 이상에서는 helper image를 GitLab.com의 GitLab Container Registry인 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}에서 가져옵니다. GitLab Self-Managed 인스턴스도 기본적으로 GitLab.com의 GitLab Container Registry에서 helper image를 가져옵니다. GitLab.com의 GitLab Container Registry 상태를 확인하려면 GitLab System Status를 참조하세요.

헬퍼 이미지 재정의#

다음과 같은 이유로 헬퍼 이미지를 재정의해야 할 수 있습니다:

• job 실행 속도 향상: 인터넷 연결이 느린 환경에서는 같은 이미지를 여러 번 다운로드하면 job 실행 시간이 길어질 수 있습니다. registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ와 동일한 복사본이 저장된 로컬 레지스트리에서 헬퍼 이미지를 다운로드하면 속도를 높일 수 있습니다.

• 보안 문제: 사전 검토하지 않은 외부 의존성을 다운로드하지 않으려는 경우가 있습니다. 검토 후 로컬 리포지터리에 저장된 의존성만 사용하도록 요구하는 비즈니스 규칙이 있을 수 있습니다.

• 인터넷 액세스가 없는 빌드 환경: 오프라인 환경에 설치된 쿠버네티스 클러스터를 사용하는 경우, 로컬 이미지 레지스트리 또는 패키지 리포지터리를 통해 CI/CD job에서 사용하는 이미지를 가져올 수 있습니다.

• 추가 소프트웨어: git+http 대신 git+ssh로 액세스하는 서브모듈을 지원하기 위해 openssh와 같은 추가 소프트웨어를 헬퍼 이미지에 설치하려는 경우가 있습니다.

이러한 경우 helper_image 구성 필드를 사용하여 커스텀 이미지를 구성할 수 있습니다. 이 필드는 docker, docker+machine, kubernetes 익스큐터에서 사용할 수 있습니다:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag"

헬퍼 이미지의 버전은 GitLab Runner 버전과 엄격하게 연계되는 것으로 간주해야 합니다. 이 이미지를 제공하는 주된 이유 중 하나는 GitLab Runner가 gitlab-runner-helper 바이너리를 사용하기 때문입니다. 이 바이너리는 GitLab Runner 소스의 일부에서 컴파일됩니다. 이 바이너리는 두 바이너리 모두에서 동일할 것으로 예상되는 내부 API를 사용합니다.

기본적으로 GitLab Runner는 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ 이미지를 참조하며, 여기서 XYZ는 GitLab Runner 아키텍처와 Git 리비전을 기반으로 합니다. 버전 변수 중 하나를 사용하여 이미지 버전을 정의할 수 있습니다:

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

이 구성을 사용하면 GitLab Runner는 익스큐터에게 컴파일 데이터를 기반으로 한 x86_64-v${CI_RUNNER_VERSION} 버전의 이미지를 사용하도록 지시합니다. GitLab Runner를 새 버전으로 업데이트하면 GitLab Runner가 적절한 이미지를 다운로드하려고 시도합니다. GitLab Runner를 업그레이드하기 전에 이미지를 레지스트리에 업로드해야 합니다. 그렇지 않으면 job이 "No such image" 오류와 함께 실패하기 시작합니다.

헬퍼 이미지는 $CI_RUNNER_REVISION 외에도 $CI_RUNNER_VERSION으로 태그가 지정됩니다. 두 태그 모두 유효하며 동일한 이미지를 가리킵니다.

[[runners]]
  (...)
  executor = "docker"
  [runners.docker]
    (...)
    helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

PowerShell Core를 사용하는 경우#

PowerShell Core가 포함된 Linux용 헬퍼 이미지의 추가 버전이 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ-pwsh 태그로 게시됩니다.

[runners.custom_build_dir] 섹션#

History

• GitLab Runner 11.10에서 도입됨.

이 섹션은 커스텀 빌드 디렉터리 파라미터를 정의합니다.

이 기능은 명시적으로 구성하지 않으면 kubernetes, docker, docker+machine, docker autoscaler, instance 익스큐터에서 기본적으로 활성화됩니다. 다른 모든 익스큐터에서는 기본적으로 비활성화됩니다.

이 기능을 사용하려면 GIT_CLONE_PATH가 runners.builds_dir에 정의된 경로 내에 있어야 합니다. builds_dir을 사용하려면 $CI_BUILDS_DIR 변수를 사용하세요.

기본적으로 이 기능은 리소스를 잘 분리할 수 있는 docker와 kubernetes 익스큐터에서만 활성화됩니다. 이 기능은 모든 익스큐터에서 명시적으로 활성화할 수 있지만, builds_dir을 공유하고 concurrent > 1인 익스큐터와 함께 사용할 때는 주의가 필요합니다.

예시:

[runners.custom_build_dir]
  enabled = true

기본 빌드 디렉터리#

GitLab Runner는 *빌드 디렉터리(Builds Directory)*라고 알려진 기본 경로 아래에 존재하는 경로로 리포지터리를 복제합니다. 이 기본 디렉터리의 기본 위치는 익스큐터에 따라 다릅니다. 각 익스큐터별 위치는 다음과 같습니다:

• 쿠버네티스, Docker, Docker Machine 익스큐터의 경우, 컨테이너 내부의 /builds입니다.

• Instance의 경우, 타깃 머신에 대한 SSH 또는 WinRM 연결을 처리하도록 구성된 사용자의 홈 디렉터리에 있는 ~/builds입니다.

• Docker Autoscaler의 경우, 컨테이너 내부의 /builds입니다.

• Shell 익스큐터의 경우, $PWD/builds입니다.

• SSH, VirtualBox, Parallels 익스큐터의 경우, 타깃 머신에 대한 SSH 연결을 처리하도록 구성된 사용자의 홈 디렉터리에 있는 ~/builds입니다.

• Custom 익스큐터의 경우, 기본값이 제공되지 않으므로 명시적으로 구성해야 합니다. 그렇지 않으면 job이 실패합니다.

사용되는 빌드 디렉터리는 사용자가 builds_dir 설정으로 명시적으로 정의할 수 있습니다.

커스텀 디렉터리로 복제하려면

GIT_CLONE_PATH를 지정할 수도 있으며, 이 경우 아래 가이드라인은 적용되지 않습니다.

GitLab Runner는 실행하는 모든 job에 빌드 디렉터리를 사용하지만, {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_PROJECT_ID/$NAMESPACE/$PROJECT_NAME이라는 특정 패턴을 사용하여 중첩합니다. 예: /builds/2mn-ncv-/0/user/playground.

GitLab Runner는 빌드 디렉터리 내에 항목을 저장하는 것을 막지 않습니다. 예를 들어 CI 실행 중에 사용할 수 있는 도구를 /builds/tools 내에 저장할 수 있습니다. 하지만 이를 강력히 권장하지 않으며, 빌드 디렉터리 내에는 어떠한 항목도 저장해서는 안 됩니다. GitLab Runner는 이 디렉터리를 완전히 제어해야 하며, 이러한 경우 안정성을 보장하지 않습니다. CI에 필요한 의존성이 있다면 다른 위치에 설치해야 합니다.

Git 구성 정리#

History

• GitLab Runner 17.10에서 도입됨.

모든 빌드의 시작과 끝에서 GitLab Runner는 리포지터리 및 서브모듈에서 다음 파일을 제거합니다:

• Git 잠금 파일 ({index,shallow,HEAD,config}.lock)

• Post-checkout 훅 (hooks/post-checkout)

clean_git_config를 활성화하면 리포지터리, 서브모듈, Git 템플릿 디렉터리에서 다음 추가 파일 또는 디렉터리가 제거됩니다:

• .git/config 파일

• .git/hooks 디렉터리

이 정리 과정은 커스텀, 임시 또는 잠재적으로 악의적인 Git 구성이 job 간에 캐시되지 않도록 방지합니다.

GitLab Runner 17.10 이전에는 정리 동작이 달랐습니다:

• Git 잠금 파일 및 Post-checkout 훅 정리는 job 시작 시에만 수행되었고 종료 시에는 수행되지 않았습니다.

• 다른 Git 구성(clean_git_config로 현재 제어됨)은 FF_ENABLE_JOB_CLEANUP이 설정되지 않으면 제거되지 않았습니다. 이 플래그를 설정했을 때는 서브모듈 구성이 아닌 메인 리포지터리의 .git/config만 삭제되었습니다.

clean_git_config 설정의 기본값은 true입니다. 단, 다음의 경우에는 기본값이 false입니다:

• Shell 익스큐터를 사용하는 경우.

• Git 전략이 none으로 설정된 경우.

명시적인 clean_git_config 구성은 기본 설정보다 우선합니다.

[runners.referees] 섹션#

GitLab Runner referee를 사용하여 추가 job 모니터링 데이터를 GitLab에 전달하세요. Referee는 러너 매니저의 워커로, job과 관련된 추가 데이터를 쿼리하고 수집합니다. 결과는 job 아티팩트로 GitLab에 업로드됩니다.

Metrics Runner Referee 사용#

job을 실행하는 머신 또는 컨테이너가 Prometheus 메트릭을 노출하는 경우, GitLab Runner는 job 전체 실행 시간 동안 Prometheus 서버를 쿼리할 수 있습니다. 메트릭을 수신한 후 나중에 분석에 사용할 수 있는 job 아티팩트로 업로드됩니다.

docker-machine 익스큐터만 referee를 지원합니다.

GitLab Runner용 Metrics Runner Referee 구성#

config.toml 파일의 [[runner]] 섹션에 [runner.referees]와 [runner.referees.metrics]를 정의하고 다음 필드를 추가하세요:

다음은 node_exporter 메트릭에 대한 전체 구성 예시입니다:

[[runners]]
  [runners.referees]
    [runners.referees.metrics]
      prometheus_address = "http://localhost:9090"
      query_interval = 10
      metric_queries = [
        "arp_entries:rate(node_arp_entries{{selector}}[{interval}])",
        "context_switches:rate(node_context_switches_total{{selector}}[{interval}])",
        "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])",
        "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])",
        "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])",
        "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])",
        "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])",
        "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])",
        "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])",
        "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])",
        "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])",
        "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])",
        "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])",
        "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])",
        "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])",
        "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])",
        "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])"
      ]

메트릭 쿼리는 canonical_name:query_string 형식입니다. 쿼리 문자열은 실행 중에 대체되는 두 가지 변수를 지원합니다:

예를 들어, docker-machine 익스큐터를 사용하는 공유 GitLab Runner 환경의 {selector}는 node=shared-runner-123과 유사합니다.