• 구성 유효성 검사
• 전역 섹션
  • log_format 예시 (줄임)
    • runner
    • text
    • json
  • check_interval 작동 방식
• [session_server] 섹션
• [[runners]] 섹션
  • clone_url 작동 방법
  • unhealthy_requests_limit와 unhealthy_interval 작동 방법
• 실행자
• 쉘
  • POSIX 호환 쉘 사용
• [runners.docker] 섹션
  • [[runners.docker.services]] 섹션
  • [runners.docker] 섹션 내의 볼륨
    • 예제 1: 데이터 볼륨 추가
    • 예제 2: 호스트 디렉터리를 데이터 볼륨으로 마운트
  • 개인 컨테이너 레지스트리 사용
• [runners.virtualbox] 섹션
• 기본 VM 이미지 재정의
• [runners.ssh] 섹션
  • 기간 구문
• [runners.instance] 섹션
• [runners.autoscaler] 섹션
• [runners.autoscaler.plugin_config] 섹션
• [runners.autoscaler.connector_config] 섹션
• [[runners.autoscaler.policy]] 섹션들
  • Periods 구문
• [runners.custom] 섹션
• [runners.cache] 섹션
  • [runners.cache.s3] 섹션
    • 러너 캐시를위한 S3 버킷에서 KMS 키 암호화 사용
    • Kubernetes ServiceAccount 리소스에 대한 IAM 역할 활성화
  • [runners.cache.gcs] 섹션
  • [runners.cache.azure] 섹션
• [runners.kubernetes] 섹션
• 도우미 이미지
  • Arm의 Kubernetes용 도우미 이미지 구성
  • Alpine Linux 이전 버전을 사용하는 러너 이미지
  • Alpine pwsh 이미지
  • 도우미 이미지 레지스트리
  • 도우미 이미지 재정의
    • PowerShell Core를 사용하는 경우
• [runners.custom_build_dir] 섹션
  • 기본 빌드 디렉터리
• [runners.referees] 섹션
  • 메트릭스 Runner 리퍼리 사용

고급 구성

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

config.toml 파일은 다음 위치에 있습니다.

• 루트로 GitLab Runner를 실행할 때 *nix 시스템에서, /etc/gitlab-runner/입니다. 이 디렉터리는 서비스 구성의 경로입니다.
• 루트로 GitLab Runner를 실행하지 않을 때 *nix 시스템에서, ~/.gitlab-runner/입니다.
• 다른 시스템에서는 ./입니다.

대부분의 옵션을 변경할 때는 GitLab Runner를 다시 시작할 필요가 없습니다. 이에는 [[runners]] 섹션의 매개변수 및 전역 섹션의 대부분의 매개변수가 포함됩니다. listen_address를 제외한 대부분의 옵션을 변경할 때는 러너를 다시 등록할 필요가 없습니다.

GitLab Runner는 구성 수정을 3초마다 확인하고 필요에 따라 다시로드합니다. 또한 SIGHUP 신호에 응답하여 구성을 다시로드합니다.

구성 유효성 검사

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

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

구성 유효성 검사 프로세스는 정보 목적으로만 사용됩니다. 출력을 사용하여 러너 구성에 잠재적인 문제를 식별할 수 있습니다. 그러나 구성 유효성 검사는 모든 가능한 문제를 잡아내지 않을 수 있으며 메시지의 부재가 config.toml 파일이 완벽하다는 것을 보장하지 않습니다.

전역 섹션

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

구성 예시:

concurrent = 4
log_level = "warning"

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":"2020-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2020-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-1, runner-2).
3. 대기 간격 계산하기 (10s / 2 = 5s).
4. 무한 루프 시작:
   1. runner-1에 대한 작업 요청.
   2. 5초 동안 대기.
   3. runner-2에 대한 작업 요청.
   4. 5초 동안 대기.
   5. 반복.

이 예에서 각 러너의 프로세스는 5초마다 작업 요청을 합니다. 만약 runner-1 및 runner-2가 동일한 GitLab 인스턴스에 연결되어 있다면, 해당 GitLab 인스턴스는 이러한 러너에서 새 요청을 5초마다 받습니다.

runner-1에 대한 첫 번째 및 두 번째 요청 사이에 두 차례의 대기 기간이 있습니다. 각 기간은 5초가 걸리므로 runner-1에 대한 연이은 요청 사이에는 대략 10초가 걸립니다. runner-2에도 동일하게 적용됩니다.

만약 여러 러너를 정의하면, 대기 간격이 줄어듭니다. 그러나 러너에 대한 요청은 다른 모든 러너에 대한 모든 요청 및 대기 기간이 호출된 후에 반복됩니다.

[session_server] 섹션

[session_server] 섹션을 사용하면 대화형 웹 터미널에서 작업을 상호 작용할 수 있습니다.

[session_server] 섹션은 루너마다가 아닌 루트 수준에서 지정되어야 합니다.

[session_server]
  listen_address = "[::]:8093" # 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)입니다. 러너는 안전한 연결을 위해 이 정보를 사용합니다.
• 웹 브라우저가 advertise_address에 연결할 수 있는지 확인합니다. 라이브 세션은 웹 브라우저에서 시작됩니다.
• advertise_address가 공개 IP 주소인지 확인하세요. allow_local_requests_from_web_hooks_and_services 응용 프로그램 설정을 활성화하지 않은 경우에도 GitLab Runner가 그에 노출됩니다.

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

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

[[runners]] 섹션

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

예시:

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

clone_url 작동 방법

GitLab 인스턴스가 러너가 사용할 수 없는 URL에 있는 경우 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을 생성합니다.

unhealthy_requests_limit와 unhealthy_interval 작동 방법

GitLab 인스턴스가 (예를 들어 버전 업그레이드 중에) 장기간 사용 불가능한 경우 해당 인스턴스에 구성된 러너는 유휴 상태가 되며 GitLab 인스턴스가 다시 사용 가능한 후 30-60분 동안 작업 처리를 재개하지 않습니다.

러너가 유휴 상태로 남아 있는 시간을 늘리거나 줄이려면 unhealthy_interval 설정을 변경하세요.

러너가 GitLab 서버에 연결을 시도하고 유효하지 않은 대기 시간을 받기 전에 시도할 횟수를 변경하려면 unhealthy_requests_limit 설정을 변경하세요. 더 많은 정보는 How check_interval works를 참조하세요.

실행자

다음 실행자가 사용 가능합니다.

쉘

사용 가능한 쉘은 다양한 플랫폼에서 실행할 수 있습니다.

shell 옵션이 bash 또는 sh로 설정된 경우 Bash의 ANSI-C quoting이 셸 이스케이핑에 사용됩니다.

POSIX 호환 쉘 사용

GitLab 러너 14.9 이상에서 특징 플래그인 FF_POSIXLY_CORRECT_ESCAPES를 활성화하여 POSIX 호환성 쉘(dash와 같은)을 사용하세요. 활성화된 경우, POSIX 호환성 쉘 이스케이핑 메커니즘인 “Double Quotes”가 사용됩니다.

[runners.docker] 섹션

다음 설정은 Docker 컨테이너 매개변수를 정의합니다.

Docker-in-Docker가 서비스로 구성되거나 작업 내부에 구성된 모든 컨테이너 런타임은 이러한 매개변수를 상속하지 않습니다.

[[runners.docker.services]] 섹션

작업과 함께 실행할 추가 서비스를 지정합니다. 사용 가능한 이미지 디렉터리은 도커 레지스트리를 참조하십시오. 각 서비스는 별도의 컨테이너에서 실행되며 작업과 연결됩니다.

예시:

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  memory = "128m"
  memory_swap = "256m"
  memory_reservation = "64m"
  oom_kill_disable = false
  cpuset_cpus = "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"]
  userns_mode = "host"
  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:*"]
  [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] 섹션 내의 볼륨

볼륨에 대한 자세한 정보는 도커 문서를 참조하십시오.

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

예제 1: 데이터 볼륨 추가

데이터 볼륨은 연합 파일 시스템을 우회하는 하나 이상의 컨테이너의 특별히 지정된 디렉터리로, 컨테이너의 수명 주기와 독립적으로 데이터를 유지하는 데 사용됩니다.

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

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

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

컨테이너 외부에 디렉터리를 저장하려면 도커 데몬의 호스트에서 디렉터리를 컨테이너에 마운트할 수 있습니다.

[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:2.7"
  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 및 이후 버전은 정의된 서비스를 위해 호스트 디렉터리를 마운트합니다.

개인 컨테이너 레지스트리 사용

작업을 위한 이미지의 소스로 개인 레지스트리를 사용하려면 CI/CD 변수 DOCKER_AUTH_CONFIG를 사용하여 인증을 구성하세요. 변수를 다음 중 하나에 설정할 수 있습니다:

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

if-not-present 풀 정책을 사용하여 개인 레지스트리를 사용하면 보안 문제가 발생할 수 있습니다. 풀 정책의 작동 방식에 대한 자세한 내용은 러너(runner)가 이미지를 끌어오는 방법 구성을 참조하십시오.

개인 컨테이너 레지스트리 사용에 대한 자세한 정보는 다음을 참조하십시오:

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

러너(runner)가 수행하는 단계를 요약하면:

1. 이미지 이름에서 레지스트리 이름을 찾습니다.
2. 값이 비어 있지 않으면 실행기는이 레지스트리에 대한 인증 구성을 찾습니다.
3. 마지막으로 지정된 레지스트리에 해당하는 인증이 있는 경우 후속 풀은 이를 사용합니다.

#### GitLab 통합 레지스트리 지원

GitLab은 작업 데이터와 함께 통합된 레지스트리의 자격 증명을 전송합니다. 이러한 자격 증명은 자동으로 레지스트리의 권한 부여 매개변수 디렉터리에 추가됩니다.

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

작업에서는 GitLab 통합 레지스트리에서 이미지를 사용할 수 있으며, 해당 이미지가 비공개 또는 보호되었더라도 사용할 수 있습니다. 작업이 액세스할 수 있는 이미지에 대한 정보는 [CI/CD 작업 토큰 문서](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html)를 참조하세요.

#### Docker 권한 부여 해결 우선 순위

이전에 설명한 대로 GitLab 러너는 여러 방식으로 Docker를 레지스트리에 대해 인가할 수 있습니다. 적절한 레지스트리를 찾기 위해 다음과 같은 우선 순위가 고려됩니다.

1. `DOCKER_AUTH_CONFIG`로 구성된 자격 증명.
1. `~/.docker/config.json` 또는 `~/.dockercfg` 파일(예: 호스트에서 `docker login` 실행)에 로컬로 구성된 자격 증명(호스트에서 `docker login` 실행 등).
1. 작업의 페이로드로 기본적으로 전송된 자격 증명 (예: 이전에 설명한 *통합 레지스트리*의 자격 증명).

레지스트리에 대해 찾은 첫 번째 자격 증명이 사용됩니다. 예를 들어, `DOCKER_AUTH_CONFIG` 변수로 *통합 레지스트리*의 자격 증명을 추가하면 기본 자격 증명이 재정의됩니다.

## `[runners.parallels]` 섹션

다음은 Parallels을 위한 매개변수입니다.

| 매개변수 | 설명 |
| ------- | ---- |
| `base_name`         | 복제된 Parallels VM의 이름. |
| `template_name`     | Parallels VM 링크된 템플릿의 사용자 정의 이름. 선택 사항. |
| `disable_snapshots` | 비활성화되면, 작업이 완료될 때 VM이 파괴됩니다. |
| `allowed_images`    | 정규 표현식으로 표시된 허용된 `image`/`base_name` 값 디렉터리. 자세한 내용은 [기본 VM 이미지 재정의](#overriding-the-base-vm-image) 섹션을 참조하세요. |

예시:

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

[runners.virtualbox] 섹션

다음은 VirtualBox를 위한 매개변수입니다. 이 실행기는 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 이미지 재정의

• GitLab Runner 14.2에서 도입됨.

Parallels 및 VirtualBox 실행기 모두 .gitlab-ci.yml 파일의 image 매개변수를 사용하여 base_name으로 지정된 기본 VM 이름을 재정의할 수 있습니다.

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

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

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

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

allowed_images 매개변수는 정규 표현식의 디렉터리입니다. 구성은 필요에 따라 정교해질 수 있습니다. 예를 들어, 특정 VM 이미지만 허용하려면 다음과 같이 regex를 사용할 수 있습니다:

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

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

[runners.ssh] 섹션

다음 매개변수는 SSH 연결을 정의합니다.

예시:

[runners.ssh]
  host = "내-프로덕션-서버"
  port = "22"
  user = "root"
  password = "프로덕션-서버-비밀번호"
  identity_file = ""

## `[runners.machine]` 섹션

다음 매개변수는 Docker Machine 기반 오토스케일링 기능을 정의합니다. 자세한 정보는 [Docker Machine Executor autoscale configuration](autoscale.md)을 참조하세요.

| 매개변수           | 설명 |
|---------------------|-------------|
| `MaxGrowthRate`     | 한 번에 러너에 추가할 수 있는 최대 머신 수. 기본값은 `0` (제한 없음)입니다. |
| `IdleCount`         | _Idle_ 상태에서 생성되어 대기해야 하는 머신 수입니다. |
| `IdleScaleFactor`   | (실험적) 현재 사용 중인 머신 수의 팩터로 _Idle_ 머신의 수를 나타냅니다. 부동 소수점 숫자 형식이어야 합니다. 자세한 내용은 [오토스케일 문서](autoscale.md#the-idlescalefactor-strategy)를 참조하세요. 기본값은 `0.0`입니다. |
| `IdleCountMin`      | `IdleScaleFactor`를 사용할 때 _Idle_ 상태에서 생성되어 대기해야 하는 최소 머신 수입니다. 기본값은 1입니다. |
| `IdleTime`          | 머신이 제거되기 전에 _Idle_ 상태에 있어야 하는 시간(초)입니다. |
| `[[runners.machine.autoscaling]]` | 현재 시간과 일치하는 표현식이 있는 마지막 섹션을 선택하는 여러 섹션을 포함합니다. |
| `OffPeakPeriods`    | (폐기 예정됨) 스케줄러가 OffPeak 모드인 시간대입니다. 크론 스타일 패턴(아래 참조)의 배열입니다. |
| `OffPeakTimezone`   | (폐기 예정됨) OffPeakPeriods에서 주어진 시간대입니다. `Europe/Berlin`과 같은 시간대 문자열입니다. 지정되지 않았거나 비어 있으면 호스트의 로캘 시스템 설정을 기본값으로 합니다. GitLab Runner는 `ZONEINFO` 환경 변수로 지정된 디렉터리나 압축 푼 zip 파일의 시간대 데이터베이스를 찾은 후, Unix 시스템의 알려진 설치 위치에서 찾은 후, 마지막으로 `$GOROOT/lib/time/zoneinfo.zip`에서 찾습니다. |
| `OffPeakIdleCount`  | _Off Peak_ 시간대에 대기해야 하는 머신의 수입니다. |
| `OffPeakIdleTime`   | _Off Peak_ 시간대에 제거되기 전에 _Idle_ 상태에 있어야 하는 시간(초)입니다. |
| `MaxBuilds`         | 머신이 제거되기 전의 최대 작업(빌드) 수입니다. |
| `MachineName`       | 머신의 이름입니다. 고유한 머신 식별자로 대체되어야 합니다. |
| `MachineDriver`     | Docker Machine `driver`입니다. 자세한 정보는 [Docker Machine configuration section](autoscale.md#supported-cloud-providers)을 참조하세요. |
| `MachineOptions`    | Docker Machine 옵션입니다. 자세한 정보는 [Docker Machine configuration section](autoscale.md#supported-cloud-providers)을 참조하세요. |

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

| 매개변수           | 설명 |
|---------------------|-------------|
| `Periods`           | 이 스케줄이 활성화되는 시간대입니다. 크론 스타일 패턴(아래 참조)의 배열입니다. |
| `IdleCount`         | _Idle_ 상태에서 생성되어 대기해야 하는 머신 수입니다. |
| `IdleScaleFactor`   | (실험적) 현재 사용 중인 머신 수의 팩터로 _Idle_ 머신의 수를 나타냅니다. 부동 소수점 숫자 형식이어야 합니다. 자세한 내용은 [오토스케일 문서](autoscale.md#the-idlescalefactor-strategy)를 참조하세요. 기본값은 `0.0`입니다. |
| `IdleCountMin`      | `IdleScaleFactor`를 사용할 때 _Idle_ 상태에서 생성되어 대기해야 하는 최소 머신 수입니다. 기본값은 1입니다. |
| `IdleTime`          | 머신이 제거되기 전에 _Idle_ 상태에 있어야 하는 시간(초)입니다. |
| `Timezone`   | `Periods`에서 주어진 시간대입니다. `Europe/Berlin`과 같은 시간대 문자열입니다. 지정되지 않았거나 비어 있으면 호스트의 로캘 시스템 설정을 기본값으로 합니다. GitLab Runner는 `ZONEINFO` 환경 변수로 지정된 디렉터리나 압축 푼 zip 파일의 시간대 데이터베이스를 찾은 후, Unix 시스템의 알려진 설치 위치에서 찾은 후, 마지막으로 `$GOROOT/lib/time/zoneinfo.zip`에서 찾습니다. |

예시:

```toml
[runners.machine]
  IdleCount = 5
  IdleTime = 600
  MaxBuilds = 100
  MachineName = "auto-scale-%s"
  MachineDriver = "google" # 인증 방법은 Docker Machine 문서를 참조하세요: https://docs.docker.com/machine/drivers/gce/#credentials
  MachineOptions = [
      # Google Compute Engine 드라이버를 이용한 추가 머신 옵션.
      # 호스트에 연결할 수 없는 문제가 발생하면 (예: "SSH 대기 중"),
      # 디버깅을 돕기 위해 선택적 매개변수를 제거해야 합니다.
      # https://docs.docker.com/machine/drivers/gce/
      "google-project=GOOGLE-PROJECT-ID",
      "google-zone=GOOGLE-ZONE", # 예: 'us-central1-a', 전체 디렉터리은 https://cloud.google.com/compute/docs/regions-zones/에 있습니다.
  ]
  [[runners.machine.autoscaling]]
    Periods = ["* * 9-17 * * mon-fri *"]
    IdleCount = 50
    IdleCountMin = 5
    IdleScaleFactor = 1.5 # 현재 Idle 머신 수는 사용 중 머신 수의 1.5배로 설정됩니다.
                          # 최대 50 (IdleCount의 값)이고 최소 5 (IdleCountMin의 값)보다 적게 설정되지는 않습니다.
    IdleTime = 3600
    Timezone = "UTC"
  [[runners.machine.autoscaling]]
    Periods = ["* * * * * sat,sun *"]
    IdleCount = 5
    IdleTime = 60
    Timezone = "UTC"

기간 구문

Periods 설정에는 cron 스타일 형식으로 나타낸 시간대의 문자열 패턴 배열이 포함되어 있습니다. 이 줄에는 다음 필드가 포함되어 있습니다.

[초] [분] [시] [월의 날짜] [월] [요일] [년]

일반적인 cron 구성 파일과 마찬가지로, 이 필드에는 단일 값, 범위, 디렉터리, 별표가 포함될 수 있습니다. 구문의 자세한 설명은 구현에 대한 자세한 설명을 참조하세요.

[runners.instance] 섹션

다음 파라미터는 인스턴스 실행자 구성을 정의합니다. 인스턴스 실행자는 Beta 상태입니다.

[runners.autoscaler] 섹션

• GitLab Runner v15.10.0에서 소개되었습니다.

다음 파라미터는 오토스케일러 기능을 구성합니다. 이러한 파라미터는 인스턴스 및 도커 오토스케일러 실행자와 함께 사용할 수 있습니다. 이 실행자들은 Beta 상태입니다.

[runners.autoscaler.plugin_config] 섹션

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

fleeting 플러그인들은 일반적으로 지원되는 구성에 대한 문서를 가지고 있습니다.

[runners.autoscaler.connector_config] 섹션

fleeting 플러그인들은 일반적으로 지원되는 연결 옵션에 대한 문서를 가지고 있습니다.

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

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

참고 - 이 컨텍스트에서의 idle_count는 레거시 오토스케일링 방법과 달리 작업 수가 아닌 오토스케일된 기계 수를 나타냅니다.

scale_factor가 설정되면 idle_count가 최소 idle 용량이 되고 scale_factor_limit가 최대 idle 용량이 됩니다.

Periods 구문

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

 ┌────────── 분 (0 - 59)
 │ ┌──────── 시간 (0 - 23)
 │ │ ┌────── 월의 날짜 (1 - 31)
 │ │ │ ┌──── 월 (1 - 12)
 │ │ │ │ ┌── 요일 (1 - 7 또는 MON-SUN, 0은 일요일의 별칭)
 * * * * *

• -은 두 숫자 사이에 사용되어 범위를 지정할 수 있습니다.
• *은 해당 필드의 유효한 값의 전체 범위를 나타낼 때 사용됩니다.
• / 뒤에 숫자가 올 수 있으며, 범위 뒤에 사용하여 해당 범위에서 해당 숫자를 건너뛸 수 있습니다. 예를 들어 시간 필드의 경우 0-12/2는 00:00부터 00:12까지 2시간마다 기간을 활성화합니다.
• ,은 필드의 유효한 숫자나 범위를 구분하는 데 사용될 수 있습니다. 예를 들어 1,2,6-9입니다.

이 크론 작업은 시간 범위를 나타냅니다. 예를 들면:

[runners.custom] 섹션

다음 매개변수는 사용자 정의 실행자 구성을 정의합니다.

[runners.cache] 섹션

다음 매개변수는 분산 캐시 기능을 정의합니다. 자세한 내용은 러너 오토 스케일 문서를 참조하십시오.

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

S3 캐시 어댑터가 IAM 인스턴스 프로필을 사용하도록 구성되면, 어댑터는 GitLab 러너 머신에 연결된 프로필을 사용합니다. 마찬가지로 GCS 캐시 어댑터도 CredentialsFile을 사용하도록 구성되면 파일은 GitLab 러너 머신에 있어야 합니다.

이 표는 register를위한 config.toml, CLI 옵션 및 ENV 변수를 나열합니다.

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

만약 ServerAddress, AccessKey, 또는 SecretKey 중 하나라도 지정되지 않고 AuthenticationType이 제공되지 않으면, S3 클라이언트는 gitlab-runner 인스턴스에 사용 가능한 IAM 인스턴스 프로필을 사용합니다. 자동 스케일 구성에서는 작업이 실행되는 온디맨드 머신이 아닙니다. ServerAddress, AccessKey, SecretKey가 모두 지정되지만 AuthenticationType이 제공되지 않는 경우 access-key가 인증 유형으로 사용됩니다.

GitLab Runner를 설치할 때 Helm 차트를 사용하고 values.yaml 파일에서 rbac.create를 true로 설정하면 ServiceAccount가 생성됩니다. 이 ServiceAccount의 주석은 rbac.serviceAccountAnnotations 섹션에서 검색됩니다.

Amazon EKS에서 실행 중인 러너에 대해 서비스 계정에 할당할 IAM 역할을 지정할 수 있습니다. 필요한 구체적인 주석은 다음과 같습니다: eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>.

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

• s3:PutObject
• s3:GetObjectVersion
• s3:GetObject
• s3:DeleteObject

S3의 ServerSideEncryption을 사용하는 경우, 이 역할은 지정된 KMS 키에 대해 다음 작업을 수행 할 수 있어야합니다:

• kms:Encrypt
• kms:Decrypt
• kms:ReEncrypt*
• kms:GenerateDataKey*
• kms:DescribeKey

::SSE-C:: 타입의 ServerSideEncryption은 지원되지 않습니다. SSE-C는 사용자 제공 키가 포함 된 헤더가 다운로드 요청에 대해 제공되어야하며, 사전 서명 된 URL에 대해 키가 전달되어야합니다. 이는 키가 안전하게 보관 될 수 없는 작업으로 키 자체가 노출 될 수 있음을 의미합니다. 이 문제에 대한 논의는 이 MR에서 확인할 수 있습니다.

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

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

rbac.serviceAccountName에 정의된 Service Account에 할당 된 역할을위한 IAM 정책은 KMS 키에 대해 다음 작업을 수행 할 수있어야합니다:

• kms:GetPublicKey
• kms:Decrypt
• kms:Encrypt
• kms:DescribeKey
• kms:GenerateDataKey

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

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

1. 역할 생성 창에서 신뢰 할 수있는 엔터티 유형 선택에서 웹 신원을 선택합니다.

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

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

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

     조건	키	값
     StringEquals	oidc.eks.<AWS_REGION>.amazonaws.com/id/<OIDC_ID>:sub	system:serviceaccount:<GITLAB_RUNNER_NAMESPACE>:<GITLAB_RUNNER_SERVICE_ACCOUNT>

[runners.cache.gcs] 섹션

다음 매개변수는 Google Cloud Storage의 네이티브 지원을 정의합니다. 이러한 값에 대한 자세한 정보는 Google Cloud Storage (GCS) 인증 문서를 참조하십시오.

예시:

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

[runners.cache]
  Type = "gcs"
  Path = "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"

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

[runners.cache]
  Type = "gcs"
  Path = "prefix/경로"
  Shared = false
  [runners.cache.gcs]
    CredentialsFile = "/etc/gitlab-runner/service-account.json"
    BucketName = "runners-cache"

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

Google Cloud ADC(애플리케이션 기본 자격 증명)를 사용할 때 일반적으로 기본 서비스 계정을 사용합니다. 그런 다음 인스턴스에 자격 증명을 제공할 필요가 없습니다:

[runners.cache]
  Type = "gcs"
  Path = "prefix/경로"
  Shared = false
  [runners.cache.gcs]
    BucketName = "runners-cache"

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

[runners.cache.azure] 섹션

• GitLab Runner 13.4.0에서 소개되었습니다.

다음 매개변수는 Azure Blob Storage의 네이티브 지원을 정의합니다. 자세한 내용은 Azure Blob Storage 문서를 참조하십시오. S3 및 GCS는 개체 모음을 나타내는 데 버킷이라는 단어를 사용하는 반면 Azure는 블롭 모음을 나타내는 데 컨테이너라는 단어를 사용합니다.

예시:

[runners.cache]
  Type = "azure"
  Path = "prefix/경로"
  Shared = false
  [runners.cache.azure]
    AccountName = "<AZURE STORAGE ACCOUNT NAME>"
    AccountKey = "<AZURE STORAGE ACCOUNT KEY>"
    ContainerName = "runners-cache"
    StorageDomain = "blob.core.windows.net"

[runners.kubernetes] 섹션

• GitLab Runner v1.6.0에서 소개되었습니다.

다음 매개변수는 Kubernetes 동작을 정의합니다. 더 많은 매개변수에 대한 자세한 내용은 Kubernetes 실행기 문서를 참조하십시오.

예시:

[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"]
  [runners.kubernetes.node_selector]
    gitlab = "true"

도우미 이미지

docker, docker+machine, 또는 kubernetes executor를 사용할 때 GitLab Runner는 Git, artifacts, cache 작업을 처리하기 위한 특정 컨테이너를 사용합니다. 이 컨테이너는 도우미 이미지(helper image)라는 이름의 이미지에서 생성됩니다.

도우미 이미지는 amd64, arm, arm64, s390x, ppc64le 아키텍처에서 사용할 수 있습니다. 이 이미지에는 gitlab-runner-helper 이라는 이진 파일이 포함되어 있으며, GitLab Runner 이진 파일의 특별한 컴파일입니다. 이 파일에는 사용 가능한 명령어 중 일부만 포함되어 있으며, Git, Git LFS 및 SSL 인증서 리포지터리도 포함되어 있습니다.

도우미 이미지에는 몇 가지 버전이 있습니다: alpine, alpine3.16, alpine3.17, alpine3.18, alpine3.19, alpine-latest, ubi-fips, ubuntu. alpine 이미지는 현재 footprint가 작아 기본값이지만, 일부 환경에서 DNS 문제가 발생할 수 있습니다. helper_image_flavor = "ubuntu"를 사용하면 ubuntu 버전의 도우미 이미지를 선택할 수 있습니다.

GitLab Runner 16.1 이상에서 alpine 버전은 alpine3.18의 별칭입니다.

alpine-latest 버전은 alpine:latest를 기본 이미지로 사용하며, 이는 더 불안정할 수 있다는 의미일 수 있습니다.

DEB/RPM 패키지에서 GitLab 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 도우미 이미지를 사용하려면 구성 파일에서 다음 값을 설정하세요.

[runners.kubernetes]
        helper_image = "gitlab/gitlab-runner-helper:arm64-latest"

Alpine Linux 이전 버전을 사용하는 러너 이미지

• GitLab Runner 14.5에서 도입됨.

이미지는 여러 버전의 Alpine Linux로 빌드되므로 새로운 버전뿐만 아니라 이전 버전도 사용할 수 있습니다.

도우미 이미지의 경우, helper_image_flavor를 변경하거나 도우미 이미지 섹션을 참조하세요.

GitLab Runner 이미지의 경우, 동일한 논리를 따르며 alpine, alpine3.16, alpine3.17, alpine3.18, alpine3.19 또는 alpine-latest가 버전의 접두어로 사용됩니다:

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

Alpine pwsh 이미지

GitLab Runner 16.1 이상에서 모든 alpine 도우미 이미지에는 pwsh 변형이 포함되어 있습니다. 유일한 예외는 alpine-latest이며, GitLab Runner 도우미 이미지가 기반으로 하는 pwsh Docker 이미지에서 alpine:latest을 지원하지 않기 때문입니다.

예시:

docker pull gitlab/gitlab-runner-helper:alpine3.18-x86_64-v16.1.0-pwsh

도우미 이미지 레지스트리

GitLab 15.0 이상에서 도우미 이미지는 GitLab Container Registry에서 가져옵니다.

GitLab 15.0 이전에는 도우미 이미지를 Docker Hub의 이미지를 사용하도록 구성합니다. GitLab 레지스트리에서 기본 gitlab-runner-helper 이미지를 검색하려면 helper-image 값인 registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}를 사용하세요.

Self-managed 인스턴스는 GitLab.com의 GitLab Container Registry에서 도우미 이미지를 가져옵니다. GitLab Container Registry의 상태를 확인하려면 GitLab System Status를 참조하세요.

도우미 이미지 재정의

어떤 경우에는 도우미 이미지를 재정의해야 할 수 있습니다. 이를 수행하는 몇 가지 이유는 다음과 같습니다:

1. 작업 실행 속도 향상: 느린 인터넷 연결 환경에서 동일한 이미지를 여러 번 다운로드하면 작업 실행 시간이 증가할 수 있습니다. gitlab/gitlab-runner-helper:XYZ의 정확한 복사본이 저장된 로컬 레지스트리에서 도우미 이미지를 다운로드하면 속도를 향상시킬 수 있습니다.

2. 보안 문제: 검토되지 않은 외부 의존성을 다운로드하고 싶지 않을 수 있습니다. 로컬 리포지터리에 저장되어 검토된 의존성만 사용하도록 비즈니스 규칙이 있을 수 있습니다.

3. 인터넷 액세스가 불가능한 빌드 환경: 경우에 따라 작업은 전용 폐쇄 네트워크 환경에서 실행됩니다. 이는 kubernetes executor에는 해당되지 않으며, 이미지는 여전히 Kubernetes 클러스터에서 사용 가능한 외부 레지스트리에서 다운로드해야 합니다.

4. 추가 소프트웨어: openssh와 같은 추가 소프트웨어를 도우미 이미지에 설치하여 git+http 대신 git+ssh를 통해 액세스할 수 있는 서브모듈을 지원해야 할 수 있습니다.

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

[[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는 GitLab Runner 아키텍처 및 Git revision을 기반으로 한 gitlab/gitlab-runner-helper:XYZ 이미지를 참조합니다. GitLab Runner 11.3 이상에서는 다음과 같은 버전 변수 중 하나를 사용하여 이미지 버전을 정의할 수 있습니다:

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

이 구성을 사용하면 GitLab Runner가 executor에게 컴파일 데이터에 기반한 버전 x86_64-v${CI_RUNNER_VERSION} 이미지를 사용하도록 지시합니다. GitLab Runner를 새 버전으로 업데이트한 후에 이미지를 레지스트리에 업로드해야 하며, 그렇지 않으면 작업이 “이미지 없음” 오류로 시작하여 실패합니다.

GitLab Runner 13.2 이상에서, 도우미 이미지는 $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를 사용하는 경우

• GitLab 13.9에 도입되었습니다.

Linux용 추가 헬퍼 이미지의 다른 버전으로, PowerShell Core를 포함하고 있는 이미지가 gitlab/gitlab-runner-helper:XYZ-pwsh 태그와 함께 출판됩니다.

[runners.custom_build_dir] 섹션

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

이 섹션은 사용자 정의 빌드 디렉터리 매개변수를 정의합니다.

이 기능은 명시적으로 구성되지 않은 경우, kubernetes, docker 및 docker+machine 실행기에 대해 기본적으로 활성화됩니다. 다른 실행기에 대해서는 기본적으로 비활성화됩니다.

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

기본적으로, 이 기능은 docker 및 kubernetes 실행기에만 활성화되어 있습니다. 왜냐하면 이러한 실행기는 리소스를 분리하는 좋은 방법을 제공하기 때문입니다. 그러나 모든 실행기에 대해 명시적으로 이 기능을 활성화할 수 있지만, ‘concurrent > 1’과 함께 사용할 때 주의해야 합니다.

예시:

[runners.custom_build_dir]
  enabled = true

기본 빌드 디렉터리

GitLab Runner는 리파지토리를 _빌드 디렉터리_라고도 알려진 기본 경로 아래에 복제합니다. 이 기본 디렉터리의 기본 위치는 실행기에 따라 다릅니다. 예를 들어:

• Kubernetes, Docker 및 Docker Machine 실행기의 경우, 컨테이너 내부의 /builds입니다.
• Shell 실행기의 경우, $PWD/builds입니다.
• SSH, VirtualBox 및 Parallels 실행기의 경우, SSH 연결을 처리하기 위해 구성된 사용자의 홈 디렉터리 안의 ~/builds입니다.
• Custom 실행기의 경우, 기본값이 제공되지 않으며 명시적으로 구성해야 합니다. 그렇지 않으면 작업이 실패합니다.

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

GitLab Runner는 모든 작업에 대해 _빌드 디렉터리_를 사용하지만, 특정 패턴을 사용하여 중첩합니다. {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_ID/$NAMESPACE/$PROJECT_NAME. 예시: /builds/2mn-ncv-/0/user/playground.

GitLab Runner는 빌드 디렉터리 내부에 저장하는 것을 막지 않습니다. 예를 들어, CI 실행 중에 사용할 수 있는 도구를 /builds/tools 안에 저장할 수 있습니다. 그러나 이러한 방식은 강하게 권장하지 않습니다. 빌드 디렉터리 내에 아무 것도 저장하지 않아야 하며, CI에 필요한 의존성이 있다면 다른 위치에 설치하는 것을 권장합니다.

[runners.referees] 섹션

• GitLab Runner 12.7에 도입되었습니다.
• GitLab v12.6 이상이 필요합니다.

GitLab Runner 리퍼리를 사용하여 추가 작업 모니터링 데이터를 GitLab에 전달하세요. 리퍼리는 작업과 관련된 추가 데이터를 쿼리하고 수집하는 실행기 관리자 내의 워커입니다. 결과는 작업 artifact로 GitLab에 업로드됩니다.

메트릭스 Runner 리퍼리 사용

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

리퍼리는 docker-machine 실행자만 지원합니다.

GitLab Runner용 메트릭스 Runner 리퍼리 구성

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와 유사하게 가질 것입니다.