GitLab Runner와 개별 등록된 runner의 동작을 변경하려면 config.toml 파일을 수정하십시오.

config.toml 파일은 다음 위치에서 찾을 수 있습니다:

• GitLab Runner가 root로 실행될 때 *nix 시스템의 /etc/gitlab-runner/. 이 디렉토리는 서비스 구성 경로이기도 합니다.
• GitLab Runner가 non-root로 실행될 때 *nix 시스템의 ~/.gitlab-runner/.
• 기타 시스템의 ./.

GitLab Runner는 대부분의 옵션을 변경할 때 재시작이 필요하지 않습니다. 여기에는 [[runners]] 섹션의 파라미터와 listen_address를 제외한 전역 섹션의 대부분 파라미터가 포함됩니다. runner가 이미 등록된 경우 다시 등록할 필요가 없습니다.

GitLab Runner는 3초마다 구성 변경을 확인하고 필요한 경우 재로드합니다. GitLab Runner는 또한 SIGHUP 신호에 응답하여 구성을 재로드합니다.

구성 유효성 검사#

히스토리

• GitLab Runner 15.10에서 도입됨

구성 유효성 검사는 config.toml 파일의 구조를 확인하는 프로세스입니다. 구성 유효성 검사기의 출력은 info 수준 메시지만 제공합니다.

구성 유효성 검사 프로세스는 정보 제공 목적으로만 사용됩니다. 출력을 사용하여 runner 구성의 잠재적인 문제를 식별할 수 있습니다. 구성 유효성 검사가 가능한 모든 문제를 포착하지 못할 수 있으며, 메시지가 없다고 해서 config.toml 파일에 결함이 없다는 것을 보장하지는 않습니다.

전역 섹션#

이 설정은 전역입니다. 모든 runner에 적용됩니다.

구성 경고#

롱 폴링 문제#

GitLab Workhorse를 통해 GitLab 롱 폴링이 활성화된 경우, GitLab Runner는 여러 구성 시나리오에서 롱 폴링 문제를 경험할 수 있습니다. 이는 구성에 따라 성능 병목 현상부터 심각한 처리 지연까지 다양합니다. GitLab Runner 워커는 장시간 롱 폴링 요청에 멈춰서(GitLab Workhorse 구성 -apiCiLongPollingDuration과 일치하며, 기본값은 50초) 다른 작업이 즉시 처리되지 않을 수 있습니다.

이 문제는 GitLab Workhorse -apiCiLongPollingDuration 설정으로 제어되는 GitLab CI/CD 롱 폴링 기능과 관련이 있습니다. 활성화된 경우, 작업 요청이 작업을 사용할 수 있을 때까지 기다리는 동안 구성된 기간까지 차단될 수 있습니다.

기본 GitLab Workhorse 롱 폴링 구성 값은 50초입니다(최근 GitLab 버전에서 기본적으로 활성화됨).

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

• Omnibus: /etc/gitlab/gitlab.rb의 gitlab_workhorse['api_ci_long_polling_duration'] = "50s"
• Helm 차트: gitlab.webservice.workhorse.extraArgs 설정 사용
• CLI: gitlab-workhorse -apiCiLongPollingDuration 50s

자세한 내용은 다음을 참조하십시오:

• runner를 위한 롱 폴링
• Workhorse 구성

증상:

• 일부 프로젝트의 작업이 시작되기 전에 지연이 발생합니다(기간은 GitLab 인스턴스 롱 폴링 타임아웃과 일치)
• 다른 프로젝트의 작업은 즉시 실행됩니다
• runner 로그의 경고 메시지: CONFIGURATION: Long polling issues detected

일반적인 문제 시나리오:

• 워커 기아 병목 현상: concurrent 설정이 runner 수보다 작음(심각한 병목 현상)
• 요청 병목 현상: request_concurrency=1인 runner가 롱 폴링 중에 작업 지연을 유발
• 빌드 제한 병목 현상: 낮은 limit 설정(≤2)과 request_concurrency=1의 조합

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

• runner 수를 초과하도록 concurrent 설정을 늘립니다.
• 대용량 runner의 request_concurrency 값을 1보다 높게 설정합니다(기본값은 1). 시스템 상태를 파악하고 설정에 가장 적합한 값을 찾으려면 runner 모니터링 활성화를 고려하십시오. 워크로드에 따라 request_concurrency를 자동으로 조정하려면 FF_USE_ADAPTIVE_REQUEST_CONCURRENCY 기능 플래그 사용을 고려하십시오. 적응형 동시성에 대한 정보는 기능 플래그 문서를 참조하십시오.
• 예상 작업 볼륨에 맞게 limit 설정의 균형을 맞춥니다.

문제 구성 예시#

시나리오 1: 워커 기아 병목 현상:

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

수정된 구성 예시#

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 예시 (축약됨)#

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 \u0026 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 인스턴스에 작업 요청을 지속적으로 예약하는 루프를 포함합니다.

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

1. check_interval 값 가져오기(10s).
2. runner 목록 가져오기(runner-1, runner-2).
3. 슬립 간격 계산(10s / 2 = 5s).
4. 무한 루프 시작:
   1. runner-1에 대한 작업 요청.
   2. 5s 동안 대기.
   3. runner-2에 대한 작업 요청.
   4. 5s 동안 대기.

기본적으로 runner가 작업을 수신하면 사용 가능한 작업이 없거나 실행 중인 작업 수가 concurrent 또는 limit에 도달할 때까지 즉시 작업을 재폴링합니다. 이 동작을 변경하려면 strict_check_interval을 true로 설정하세요. 활성화하면 runner는 check_interval을 엄격히 준수하고 작업 수신 여부에 관계없이 check_interval초마다(이 예시에서는 5초) 하나의 요청을 보냅니다. 여러 runner의 작업 분산을 개선하고 한 runner가 대부분의 작업을 처리하는 것을 방지하려면 이 설정을 활성화하세요. 단, 작업이 대기열에서 더 오래 기다릴 수 있습니다.

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"
  (...)

이 예시에서 runner 프로세스의 작업 요청은 5초마다 이루어집니다. runner-1과 runner-2가 동일한 GitLab 인스턴스에 연결된 경우, 이 GitLab 인스턴스도 이 runner로부터 5초마다 새 요청을 받습니다.

runner-1의 첫 번째와 두 번째 요청 사이에 두 번의 슬립 기간이 발생합니다. 각 기간은 5초이므로 runner-1에 대한 후속 요청 사이에 약 10초가 걸립니다. runner-2에도 동일하게 적용됩니다.

더 많은 runner를 정의하면 슬립 간격이 짧아집니다. 그러나 runner에 대한 요청은 다른 모든 runner에 대한 요청과 해당 슬립 기간이 호출된 후 반복됩니다.

[machine] 섹션#

히스토리

• GitLab Runner 18.10에서 도입됨.

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

[machine.shutdown_drain] 섹션#

runner 프로세스가 종료되면 풀의 유휴 머신은 일반적으로 계속 실행됩니다. 외부에서 정리해야 합니다(예: systemd post-stop 훅을 통해). shutdown_drain 섹션은 종료 중에 유휴 머신을 자동으로 제거하도록 runner를 구성합니다.

예시:

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] 섹션#

작업과 상호 작용하려면 [[runners]] 섹션 외부의 루트 수준에 [session_server] 섹션을 지정하십시오. 개별 runner가 아닌 모든 runner에 대해 이 섹션을 한 번만 구성하십시오.

# 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)입니다. runner는 이 정보를 사용하여 보안 연결을 위한 TLS 인증서를 만듭니다.
• GitLab이 listen_address 또는 advertise_address에 정의된 IP 주소와 포트에 연결할 수 있는지 확인하십시오.
• 애플리케이션 설정 allow_local_requests_from_web_hooks_and_services를 활성화하지 않은 경우 advertise_address가 공개 IP 주소인지 확인하십시오.

세션 서버와 터미널 지원을 비활성화하려면 [session_server] 섹션을 삭제하십시오.

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

[[runners]] 섹션#

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

예시:

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

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

• 시크릿에서 토큰이 마운트되는 Kubernetes 배포
• 토큰이 환경 변수로 전달되는 Docker 배포
• 버전 제어 구성 파일에서 시크릿 방지

레거시 /ci URL 접미사#

히스토리

• GitLab Runner 1.0.0에서 사용 중단됨.
• GitLab Runner 18.7.0에서 경고 추가됨.

1.0.0 이전 버전의 GitLab Runner에서는 runner URL이 url = "https://gitlab.example.com/ci"와 같이 /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 작동 방식#

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

예를 들어 방화벽이 runner가 URL에 도달하는 것을 방지할 수 있습니다. runner가 192.168.1.23 노드에 도달할 수 있는 경우 clone_url을 http://192.168.1.23으로 설정하십시오.

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

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 인스턴스를 오랫동안 사용할 수 없는 경우(예: 버전 업그레이드 중), 해당 runner는 유휴 상태가 됩니다. GitLab 인스턴스가 다시 사용 가능해진 후 runner는 30-60분 동안 작업 처리를 재개하지 않습니다.

runner가 유휴 상태인 기간을 늘리거나 줄이려면 unhealthy_interval 설정을 변경하십시오.

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

준비 단계 타임아웃#

히스토리

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

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

• Executor 초기화 (prepare_executor): runner가 실행 환경을 설정합니다. 예: Docker 컨테이너 시작, Kubernetes pod 예약, SSH 연결 등.

• 셸 환경 설정 (prepare_script): runner가 후속 작업 단계에 필요한 셸 환경(PATH, 작업 디렉토리, 셸 함수 등)을 초기화하는 스크립트를 생성하고 실행합니다.

준비 단계가 prepare_timeout을 초과하면 작업이 즉시 실패합니다. 후속 단계(get_sources, restore_cache, script 등)는 prepare_timeout에 의해 제한되지 않으며 전체 작업 타임아웃을 사용합니다.

기본 동작: prepare_timeout이 설정되지 않거나 0이거나 작업 타임아웃을 초과하면 runner는 준비 단계에 작업 타임아웃을 사용합니다.

prepare_timeout 설정 시기#

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

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

• 사용자 정의 또는 HPC executor: executor가 외부 리소스 스케줄러의 용량 할당을 기다려야 하는 경우(HPC 작업 대기열 등) 시작이 예측 불가능하고 매우 길어질 수 있습니다. prepare_timeout이 없으면 중단된 작업이 전체 작업 타임아웃 동안 runner 슬롯을 점유합니다.

구성 예시#

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

Executor#

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

셸#

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

shell 옵션이 bash 또는 sh로 설정된 경우 Bash의 ANSI-C 인용을 사용하여 작업 스크립트를 셸 이스케이프합니다.

POSIX 호환 셸 사용#

GitLab Runner 14.9 이상에서는 FF_POSIXLY_CORRECT_ESCAPES라는 기능 플래그를 활성화하여 POSIX 호환 셸(예: dash)을 사용할 수 있습니다. 활성화되면 POSIX 호환 셸 이스케이프 메커니즘인 "이중 따옴표"가 사용됩니다.

[runners.docker] 섹션#

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

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

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

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

예시:

[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 파일 시스템을 우회하는 하나 이상의 컨테이너의 특별히 지정된 디렉토리입니다. 데이터 볼륨은 컨테이너의 수명 주기와 관계없이 데이터를 유지하도록 설계되었습니다.

[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"]

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

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와 같이 지원되지 않는 옵션을 지정하면 작업이 구성 오류와 함께 즉시 실패합니다.

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

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

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

프라이빗 레지스트리를 작업의 이미지 소스로 사용하려면 CI/CD 변수 DOCKER_AUTH_CONFIG로 인증을 구성하십시오. 변수는 다음 중 하나에서 설정할 수 있습니다:

• file 유형으로서의 프로젝트 CI/CD 설정
• config.toml 파일

if-not-present pull 정책과 함께 프라이빗 레지스트리를 사용하면 보안 문제가 발생할 수 있습니다. pull 정책 작동 방식에 대한 자세한 내용은 runner의 이미지 pull 방법 구성을 참조하십시오.

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

• 프라이빗 컨테이너 레지스트리에서 이미지 액세스
• .gitlab-ci.yml 키워드 참조

runner가 수행하는 단계를 요약하면 다음과 같습니다:

1. 이미지 이름에서 레지스트리 이름을 찾습니다.
2. 값이 비어 있지 않으면 executor는 이 레지스트리에 대한 인증 구성을 검색합니다.
3. 마지막으로 지정된 레지스트리에 해당하는 인증이 발견되면 이후 pull에서 이를 사용합니다.

GitLab 통합 레지스트리 지원#

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

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

작업에서는 이미지가 프라이빗 또는 보호된 경우에도 GitLab 통합 레지스트리의 모든 이미지를 사용할 수 있습니다. 작업이 액세스할 수 있는 이미지에 대한 정보는 CI/CD 작업 토큰 문서를 참조하십시오.

Docker 인증 확인 우선순위#

앞서 설명한 것처럼 GitLab Runner는 다양한 방법으로 전송된 자격 증명을 사용하여 레지스트리에 대해 Docker를 인증할 수 있습니다. 적절한 레지스트리를 찾기 위해 다음 우선순위가 고려됩니다:

1. DOCKER_AUTH_CONFIG로 구성된 자격 증명.
2. ~/.docker/config.json 또는 ~/.dockercfg 파일을 사용하여 GitLab Runner 호스트에서 로컬로 구성된 자격 증명(예: 호스트에서 docker login 실행).
3. 작업 페이로드와 함께 기본적으로 전송되는 자격 증명(예: 앞서 설명한 통합 레지스트리의 자격 증명).

레지스트리에서 발견된 첫 번째 자격 증명이 사용됩니다. 예를 들어 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] 섹션#

히스토리

• GitLab Runner v15.10.0에서 도입됨.

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

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

[runners.autoscaler.plugin_config] 섹션#

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

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

[runners.autoscaler.scale_throttle] 섹션#

히스토리

• 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] 섹션#

히스토리

• GitLab Runner 17.5.0에서 도입됨.

GitLab Runner가 상태 저장소가 비활성화된 상태(기본값)로 시작되면 기존 fleeting 인스턴스가 안전을 위해 즉시 제거됩니다. 예를 들어, max_use_count가 1로 설정된 경우 사용 상태를 모르면 이미 사용된 인스턴스에 실수로 작업을 할당할 수 있습니다.

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

상태 저장소 기능을 활성화할 때 다음 정보를 고려하십시오:

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

• 인스턴스가 작업을 활발히 실행 중일 때 복원되면 GitLab Runner가 기본적으로 이를 제거합니다. 이 동작은 GitLab Runner가 작업을 재개할 수 없기 때문에 안전을 보장합니다. 인스턴스를 유지하려면 keep_instance_with_acquisitions를 true로 설정하십시오.

  keep_instance_with_acquisitions를 true로 설정하면 인스턴스에서 진행 중인 작업에 관계없이 유용합니다. instance_ready_command 구성 옵션을 사용하여 인스턴스를 유지하기 위해 환경을 정리할 수도 있습니다. 여기에는 모든 실행 중인 명령 중지 또는 강제로 Docker 컨테이너 제거가 포함될 수 있습니다.

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

참고 - 이 컨텍스트의 idle_count는 레거시 자동 스케일링 방법에서와 같이 자동 스케일된 머신 수가 아닌 작업 수를 나타냅니다.

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

• 마지막으로 작업을 완료한 시간(인스턴스가 이전에 사용된 경우).
• 프로비저닝된 시간(이전에 사용되지 않은 경우).

이 확인은 스케일링 이벤트 중에 발생합니다. 구성된 idle_time을 초과하는 인스턴스는 필요한 idle_count 작업 용량을 유지하는 데 필요하지 않는 한 제거됩니다.

scale_factor가 설정된 경우 idle_count는 최소 idle 용량이 되고 scaler_factor_limit는 최대 idle 용량이 됩니다.

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

다음 예시에서 유휴 횟수 1은 월요일부터 금요일 08:00에서 15:59 사이에 사용됩니다. 그 외에는 유휴 횟수가 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 작업은 시간의 범위를 나타냅니다. 예를 들어:

[runners.autoscaler.vm_isolation] 섹션#

VM 격리는 macOS에서만 지원되는 nesting을 사용합니다.

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

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

[runners.custom] 섹션#

다음 파라미터는 custom executor의 구성을 정의합니다.

[runners.cache] 섹션#

다음 파라미터는 분산 캐시 기능을 정의합니다. 세부 정보는 runner 자동 스케일 문서에서 확인하십시오.

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

tarzstd 형식은 Zstandard 압축과 함께 TAR을 사용하며 zip보다 더 나은 압축 비율을 제공합니다. 압축 수준은 fastest(최소 압축, 최대 속도)부터 slowest(최대 압축, 가장 작은 파일 크기)까지 범위입니다. default 수준은 압축 비율과 속도 사이의 균형 잡힌 트레이드오프를 제공합니다.

예시:

job:
  variables:
    CACHE_COMPRESSION_FORMAT: tarzstd
    CACHE_COMPRESSION_LEVEL: fast

캐시 메커니즘은 사전 서명된 URL을 사용하여 캐시를 업로드하고 다운로드합니다. URL은 GitLab Runner 자체 인스턴스에서 서명됩니다. 작업의 스크립트(캐시 업로드/다운로드 스크립트 포함)가 로컬 또는 외부 머신에서 실행되는지는 중요하지 않습니다. 예를 들어 shell 또는 docker executor는 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 기본 자격 증명 체인 섹션을 참조하십시오.

캐시 키 처리#

히스토리

• 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 키로 메타데이터를 스토리지 객체 blob에 직접 연결합니다. 클라우드 공급자의 메커니즘을 사용하여 쿼리할 수 있습니다. 예시는 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개의 고유한 오브젝트 접두사에 캐시 객체를 분산하여 많은 병렬 작업이 높은 요청 속도로 캐시에 액세스할 때 Amazon S3 503(Slow Down) 응답을 방지합니다.

캐시 키 처리 동작 요약#

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

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

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

• 분산 캐시를 공유하는 runner 간에 FF_HASH_CACHE_KEYS를 동기화합니다.

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

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

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

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

• 다운로드는 백엔드가 범위를 지원하고 캐시 객체가 하나의 청크보다 큰 경우 여러 동시 범위 GET(사전 서명된 URL) 또는 동시 GoCloud 범위 읽기를 사용할 수 있습니다.

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

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

예시:

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

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

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

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

예시:

job:
  variables:
    FF_USE_PARALLEL_ARTIFACT_TRANSFER: "true"

인증#

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

정적 자격 증명#

runner는 다음 경우에 정적 액세스 키 인증을 사용합니다:

• ServerAddress, AccessKey, SecretKey 파라미터는 지정되었지만 AuthenticationType이 제공되지 않은 경우.
• AuthenticationType = "access-key"가 명시적으로 설정된 경우.

AWS SDK 기본 자격 증명 체인#

runner는 다음 경우에 AWS SDK 기본 자격 증명 체인을 사용합니다:

• ServerAddress, AccessKey, SecretKey 중 하나라도 생략되고 AuthenticationType이 제공되지 않은 경우.
• AuthenticationType = "iam"이 명시적으로 설정된 경우.

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

1. 환경 변수(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. 공유 자격 증명 파일(~/.aws/credentials)
3. IAM 인스턴스 프로필(EC2 인스턴스용)
4. SDK에서 지원하는 기타 AWS 자격 증명 소스

RoleARN이 지정되지 않은 경우 기본 자격 증명 체인은 빌드가 실행되는 머신과 반드시 동일하지 않은 runner 관리자에 의해 실행됩니다. 예를 들어 자동 스케일 구성에서 작업은 다른 머신에서 실행됩니다. 마찬가지로 Kubernetes executor를 사용하면 빌드 pod도 runner 관리자와 다른 노드에서 실행될 수 있습니다. 이 동작으로 버킷 수준 액세스만 runner 관리자에게 부여할 수 있습니다.

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

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

Amazon EKS의 runner의 경우 서비스 계정에 할당할 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 외에도 사용자 제공 키를 포함하는 헤더가 다운로드 요청에 제공되어야 합니다. 이는 키를 안전하게 유지할 수 없는 작업에 키 재료를 전달하는 것을 의미합니다. 이로 인해 암호화 해제 키가 누출될 가능성이 있습니다. 이 문제에 대한 논의는 이 MR에 있습니다.

S3 버킷에서 runner 캐시에 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으로 멀티파트 전송 활성화#

캐시에 대한 액세스를 제한하기 위해 runner 관리자는 작업이 캐시에서 다운로드하고 업로드하기 위한 시간 제한 사전 서명된 URL을 생성합니다. 그러나 AWS S3는 단일 PUT 요청을 5 GB로 제한합니다. 5 GB보다 큰 파일의 경우 멀티파트 업로드 API를 사용해야 합니다. 멀티파트 전송은 AWS S3에서만 지원되며 다른 S3 공급자에서는 지원되지 않습니다. runner 관리자는 다른 프로젝트에 대한 작업을 처리하기 때문에 버킷 전체 권한이 있는 S3 자격 증명을 전달할 수 없습니다. 대신 runner 관리자는 시간 제한 사전 서명된 URL과 좁은 범위의 자격 증명을 사용하여 하나의 특정 객체에 대한 액세스를 제한합니다.

AWS에서 S3 멀티파트 전송을 사용하려면 arn:aws:iam:::: 형식으로 RoleARN에 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이 있는 경우 runner가 캐시에 업로드할 때마다:

1. runner 관리자는 원래 S3 자격 증명(AuthenticationType, AccessKey, SecretKey를 통해 지정됨)을 검색합니다.

2. S3 자격 증명을 사용하여 runner 관리자는 RoleARN과 함께 AssumeRole을 위해 Amazon Security Token Service(STS)에 요청을 보냅니다. 정책 요청은 다음과 유사합니다:

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

3. 요청이 성공하면 runner 관리자는 제한된 세션으로 임시 AWS 자격 증명을 얻습니다.

4. runner 관리자는 이러한 자격 증명과 s3://<bucket name>/<filename> 형식의 URL을 파일을 업로드하는 캐시 아카이버에 전달합니다.

AssumeRole Prometheus 메트릭#

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

Kubernetes ServiceAccount 리소스에 IAM 역할 활성화#

서비스 계정에 IAM 역할을 사용하려면 클러스터에 대해 IAM OIDC 공급자가 존재해야 합니다. IAM OIDC 공급자가 클러스터와 연결된 후 runner의 서비스 계정에 연결할 IAM 역할을 만들 수 있습니다.

1. 역할 만들기 창의 신뢰할 수 있는 엔티티 유형 선택에서 Web Identity를 선택합니다.

2. 역할의 신뢰 관계 탭에서:

   • 신뢰할 수 있는 엔티티 섹션은 형식이어야 합니다: arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/. OIDC ID는 EKS 클러스터의 구성 탭에서 찾을 수 있습니다.

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

     조건	키	값
     StringEquals	oidc.eks..amazonaws.com/id/:sub	system:serviceaccount::

S3 Express One Zone 버킷 사용#

히스토리

• GitLab Runner 17.5.0에서 도입됨.

1. Amazon 자습서에 따라 S3 Express One Zone 버킷을 설정합니다.
2. BucketName과 BucketLocation으로 config.toml을 구성합니다.
3. 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의 메타데이터 서버에서 Application Default Credentials(ADC):

Google Cloud ADC와 함께 GitLab Runner를 사용하는 경우 일반적으로 기본 서비스 계정을 사용합니다. 그러면 인스턴스에 대한 자격 증명을 제공할 필요가 없습니다:

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

ADC를 사용하는 경우 사용하는 서비스 계정에 iam.serviceAccounts.signBlob 권한이 있는지 확인하십시오. 일반적으로 서비스 계정에 서비스 계정 토큰 생성자 역할을 부여하여 수행합니다.

GKE를 위한 Workload Identity Federation#

GKE를 위한 Workload Identity Federation은 애플리케이션 기본 자격 증명(ADC)으로 지원됩니다. 워크로드 ID가 작동하지 않는 문제가 있는 경우:

• ERROR: generating signed URL 메시지에 대한 runner pod 로그(빌드 로그 아님)를 확인하십시오. 이 오류는 다음과 같은 권한 문제를 나타낼 수 있습니다:

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

• runner pod 내에서 다음 curl 명령을 시도해 보십시오:

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

  이 명령은 올바른 Kubernetes 서비스 계정을 반환해야 합니다. 다음으로 액세스 토큰 획득을 시도하십시오:

  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는 blob 컬렉션을 나타내는 데 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 워크로드 및 관리 ID#

히스토리

• GitLab Runner v17.5.0에서 도입됨.

Azure 워크로드 또는 관리 ID를 사용하려면 구성에서 AccountKey를 생략하십시오. AccountKey가 비어 있으면 runner는 다음을 시도합니다:

1. DefaultAzureCredential을 사용하여 임시 자격 증명을 얻습니다.
2. 사용자 위임 키를 얻습니다.
3. 해당 키로 SAS 토큰을 생성하여 Storage Account blob에 액세스합니다.

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

Azure 워크로드 ID를 사용하려면 runner.kubernetes 섹션에서 ID와 관련된 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:  CLIENT ID HERE>

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

그러나 GitLab Runner 17.5 및 17.6의 경우 runner 관리자도 다음으로 구성해야 합니다:

• azure.workload.identity/use pod 레이블
• 워크로드 ID와 함께 사용할 서비스 계정

예를 들어 GitLab Runner Helm 차트 사용:

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

레이블이 필요한 이유는 자격 증명이 다른 소스에서 검색되기 때문입니다. 캐시 다운로드의 경우 자격 증명은 runner 관리자에서 검색됩니다. 캐시 업로드의 경우 자격 증명은 헬퍼 이미지를 실행하는 pod에서 검색됩니다.

자세한 내용은 이슈 38330을 참조하십시오.

[runners.kubernetes] 섹션#

다음 표는 Kubernetes executor에 사용할 수 있는 구성 파라미터를 나열합니다. 더 많은 파라미터는 Kubernetes 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"

헬퍼 이미지#

docker, docker+machine, 또는 kubernetes executor를 사용할 때 GitLab Runner는 특정 컨테이너를 사용하여 Git, 아티팩트, 캐시 작업을 처리합니다. 이 컨테이너는 helper image라는 이미지에서 생성됩니다.

헬퍼 이미지는 amd64, arm, arm64, s390x, ppc64le, riscv64 아키텍처에서 사용 가능합니다. GitLab Runner 바이너리의 특수 컴파일인 gitlab-runner-helper 바이너리가 포함되어 있습니다. 사용 가능한 명령의 서브셋과 Git, Git LFS, SSL 인증서 저장소만 포함합니다.

헬퍼 이미지에는 alpine, alpine3.21, alpine-latest, ubi-fips, ubuntu의 몇 가지 플레이버가 있습니다. alpine 이미지는 작은 크기로 인해 기본값입니다. helper_image_flavor = "ubuntu"를 사용하면 헬퍼 이미지의 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이 지정된 이미지 버전을 찾을 수 없으면 runner가 작업을 실행하기 전에 자동으로 다운로드합니다. docker와 docker+machine executor 모두 이런 방식으로 작동합니다.

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

kubernetes executor와 GitLab Runner의 수동 설치는 다르게 작동합니다.

• 수동 설치의 경우 gitlab-runner-helper 바이너리가 포함되지 않습니다.
• kubernetes executor의 경우 Kubernetes API는 gitlab-runner-helper 이미지가 로컬 아카이브에서 로드되는 것을 허용하지 않습니다.

두 경우 모두 GitLab Runner는 헬퍼 이미지를 다운로드합니다. GitLab Runner 리비전과 아키텍처가 다운로드할 태그를 정의합니다.

Arm의 Kubernetes를 위한 헬퍼 이미지 구성#

기본적으로 아키텍처에 맞는 올바른 헬퍼 이미지가 선택됩니다. arm64 Kubernetes 클러스터에서 arm64 헬퍼 이미지를 사용하기 위해 사용자 정의 helper_image 경로를 설정해야 하는 경우 구성 파일에서 다음 값을 설정하십시오:

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

이전 버전의 Alpine Linux를 사용하는 runner 이미지#

히스토리

• GitLab Runner 14.5에서 도입됨.

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

헬퍼 이미지의 경우 helper_image_flavor를 변경하거나 헬퍼 이미지 섹션을 읽으십시오.

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 헬퍼 이미지에는 pwsh 변형이 있습니다. 유일한 예외는 GitLab Runner 헬퍼 이미지의 기반이 되는 powershell Docker 이미지가 alpine:latest를 지원하지 않기 때문에 alpine-latest입니다.

예시:

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

헬퍼 이미지 레지스트리#

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

GitLab 15.1 이상에서는 헬퍼 이미지가 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에서 헬퍼 이미지를 가져옵니다. GitLab.com의 GitLab Container Registry 상태를 확인하려면 GitLab System Status를 참조하십시오.

헬퍼 이미지 재정의#

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

1. 작업 실행 속도 향상: 인터넷 연결이 느린 환경에서 동일한 이미지를 여러 번 다운로드하면 작업 실행에 걸리는 시간이 늘어날 수 있습니다. registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:XYZ의 정확한 복사본이 저장된 로컬 레지스트리에서 헬퍼 이미지를 다운로드하면 속도를 높일 수 있습니다.
2. 보안 우려: 이전에 확인되지 않은 외부 종속성을 다운로드하지 않으려는 경우가 있을 수 있습니다. 로컬 저장소에서 검토하고 저장한 종속성만 사용하는 비즈니스 규칙이 있을 수 있습니다.
3. 인터넷 액세스 없는 빌드 환경: 오프라인 환경에 Kubernetes 클러스터가 설치된 경우, 로컬 이미지 레지스트리 또는 패키지 저장소를 사용하여 CI/CD 작업에서 사용되는 이미지를 가져올 수 있습니다.
4. 추가 소프트웨어: git+http 대신 git+ssh로 액세스 가능한 서브모듈을 지원하기 위해 openssh와 같은 추가 소프트웨어를 헬퍼 이미지에 설치하려는 경우가 있을 수 있습니다.

이 경우 docker, docker+machine, kubernetes executor에 사용할 수 있는 helper_image 구성 필드를 사용하여 사용자 정의 이미지를 구성할 수 있습니다:

[[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} 버전의 이미지를 사용하도록 executor에 지시합니다. GitLab Runner를 새 버전으로 업데이트한 후 GitLab Runner는 적절한 이미지를 다운로드하려고 시도합니다. GitLab Runner를 업그레이드하기 전에 이미지를 레지스트리에 업로드해야 하며, 그렇지 않으면 작업이 "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] 섹션#

히스토리

• GitLab Runner 11.10에서 도입됨.

이 섹션은 사용자 정의 빌드 디렉토리 파라미터를 정의합니다.

이 기능은 명시적으로 구성하지 않으면 kubernetes, docker, docker+machine, docker autoscaler, instance executor에 대해 기본적으로 활성화됩니다. 다른 모든 executor의 경우 기본적으로 비활성화됩니다.

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

기본적으로 이 기능은 리소스를 잘 분리하는 방법을 제공하는 docker와 kubernetes executor에 대해서만 활성화됩니다. 이 기능은 모든 executor에 대해 명시적으로 활성화할 수 있지만, builds_dir를 공유하고 concurrent > 1인 executor와 함께 사용할 때는 주의하십시오.

예시:

[runners.custom_build_dir]
  enabled = true

기본 빌드 디렉토리#

GitLab Runner는 _Builds Directory_로 알려진 기본 경로 아래에 존재하는 경로에 저장소를 복제합니다. 이 기본 디렉토리의 기본 위치는 executor에 따라 다릅니다. 다음 executor의 경우:

• Kubernetes, Docker, Docker Machine executor는 컨테이너 내부의 /builds입니다.
• Instance는 대상 머신에 대한 SSH 또는 WinRM 연결을 처리하도록 구성된 사용자의 홈 디렉토리의 ~/builds입니다.
• Docker Autoscaler는 컨테이너 내부의 /builds입니다.
• Shell executor는 $PWD/builds입니다.
• SSH, VirtualBox, Parallels executor는 대상 머신에 대한 SSH 연결을 처리하도록 구성된 사용자의 홈 디렉토리의 ~/builds입니다.
• Custom executor는 기본값이 제공되지 않으며 명시적으로 구성해야 합니다. 그렇지 않으면 작업이 실패합니다.

사용된 _Builds Directory_는 사용자가 builds_dir 설정으로 명시적으로 정의할 수 있습니다.

GitLab Runner는 실행하는 모든 작업에 _Builds Directory_를 사용하지만 {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_PROJECT_ID/$NAMESPACE/$PROJECT_NAME이라는 특정 패턴을 사용하여 중첩합니다. 예: /builds/2mn-ncv-/0/user/playground.

GitLab Runner는 Builds Directory 내부에 항목을 저장하는 것을 막지 않습니다. 예를 들어 CI 실행 중에 사용할 수 있는 도구를 /builds/tools 내부에 저장할 수 있습니다. 이를 강력히 권장하지 않으며, Builds Directory 내부에는 아무것도 저장하지 말아야 합니다. GitLab Runner는 이에 대한 완전한 제어권을 가져야 하며 그런 경우에는 안정성을 제공하지 않습니다. CI에 필요한 종속성이 있는 경우 다른 곳에 설치해야 합니다.

Git 구성 정리#

히스토리

• 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 구성이 캐시되는 것을 방지합니다.

GitLab Runner 17.10 이전에는 정리가 다르게 동작했습니다:

• Git 잠금 파일과 Post-checkout 훅 정리는 작업 끝이 아닌 시작 시에만 발생했습니다.
• 다른 Git 구성(이제 clean_git_config로 제어됨)은 FF_ENABLE_JOB_CLEANUP이 설정되지 않으면 제거되지 않았습니다. 이 플래그를 설정하면 서브모듈 구성이 아닌 메인 저장소의 .git/config만 삭제되었습니다.

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

• Shell executor를 사용하는 경우.
• Git 전략이 none으로 설정된 경우.

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

[runners.referees] 섹션#

GitLab Runner 심판을 사용하여 추가 작업 모니터링 데이터를 GitLab에 전달하십시오. 심판은 runner 관리자의 워커로 작업과 관련된 추가 데이터를 쿼리하고 수집합니다. 결과는 나중에 분석에 사용할 수 있는 작업 아티팩트로 GitLab에 업로드됩니다.

Metrics Runner 심판 사용#

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

docker-machine executor만 심판을 지원합니다.

GitLab Runner에 대한 Metrics Runner 심판 구성#

[[runner]] 섹션의 config.toml 파일에 [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 형식입니다. 쿼리 문자열은 실행 중에 교체되는 두 가지 변수를 지원합니다: