이 문서는 GitLab UI에서 러너를 구성하는 방법을 설명합니다.

GitLab Runner를 설치한 머신에서 러너를 구성해야 하는 경우에는 GitLab Runner 문서를 참조하세요.

최대 job 타임아웃 설정#

각 러너에 대한 최대 job 타임아웃을 지정하여 job 타임아웃이 더 긴 프로젝트가 러너를 사용하는 것을 방지할 수 있습니다. 최대 job 타임아웃은 프로젝트에 정의된 job 타임아웃보다 짧은 경우에 사용됩니다.

러너의 최대 타임아웃을 설정하려면 REST API 엔드포인트 PUT /runners/:id의 maximum_timeout 파라미터를 설정하세요.

인스턴스 러너의 경우#

필수 조건:

• 관리자여야 합니다.

GitLab Self-Managed에서 인스턴스 러너에 대한 job 타임아웃을 재정의할 수 있습니다.

GitLab.com에서는 GitLab 호스팅 인스턴스 러너의 job 타임아웃을 재정의할 수 없으며 대신 프로젝트에 정의된 타임아웃을 사용해야 합니다.

최대 job 타임아웃을 설정하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 CI/CD > Runners를 선택합니다.
3. 편집할 러너의 오른쪽에서 Edit을 선택합니다.
4. Maximum job timeout 필드에 초 단위 값을 입력합니다. 최솟값은 600초(10분)입니다.
5. Save changes를 선택합니다.

그룹 러너의 경우#

필수 조건:

• 그룹에 대한 Owner 권한이 있어야 합니다.

최대 job 타임아웃을 설정하려면:

1. 상단 표시줄에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Build > Runners를 선택합니다.
3. 편집할 러너의 오른쪽에서 Edit을 선택합니다.
4. Maximum job timeout 필드에 초 단위 값을 입력합니다. 최솟값은 600초(10분)입니다.
5. Save changes를 선택합니다.

프로젝트 러너의 경우#

필수 조건:

• 프로젝트에 대한 Owner 권한이 있어야 합니다.

최대 job 타임아웃을 설정하려면:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Runners를 펼칩니다.
4. 편집할 러너의 오른쪽에서 Edit을 선택합니다.
5. Maximum job timeout 필드에 초 단위 값을 입력합니다. 최솟값은 600초(10분)입니다. 정의되지 않은 경우 프로젝트의 job 타임아웃이 대신 사용됩니다.
6. Save changes를 선택합니다.

최대 job 타임아웃 동작 방식#

예시 1 - 러너 타임아웃이 프로젝트 타임아웃보다 큰 경우

1. 러너의 maximum_timeout 파라미터를 24시간으로 설정합니다.
2. 프로젝트의 Maximum job timeout을 2시간으로 설정합니다.
3. job을 시작합니다.
4. 더 오래 실행되면 job이 2시간 후에 타임아웃됩니다.

예시 2 - 러너 타임아웃이 구성되지 않은 경우

1. 러너에서 maximum_timeout 파라미터 구성을 제거합니다.
2. 프로젝트의 Maximum job timeout을 2시간으로 설정합니다.
3. job을 시작합니다.
4. 더 오래 실행되면 job이 2시간 후에 타임아웃됩니다.

예시 3 - 러너 타임아웃이 프로젝트 타임아웃보다 작은 경우

1. 러너의 maximum_timeout 파라미터를 30분으로 설정합니다.
2. 프로젝트의 Maximum job timeout을 2시간으로 설정합니다.
3. job을 시작합니다.
4. 더 오래 실행되면 job이 30분 후에 타임아웃됩니다.

script 및 after_script 타임아웃 설정#

script 및 after_script가 종료되기 전에 실행되는 시간을 제어하려면 .gitlab-ci.yml 파일에서 타임아웃 값을 지정하세요.

예를 들어 타임아웃을 지정하여 오래 실행되는 script를 조기에 종료할 수 있습니다. 이렇게 하면 job 타임아웃이 초과되기 전에 아티팩트 및 캐시를 업로드할 수 있습니다. script 및 after_script의 타임아웃 값은 job 타임아웃보다 작아야 합니다.

• script에 대한 타임아웃을 설정하려면 job 변수 RUNNER_SCRIPT_TIMEOUT을 사용합니다.
• after_script에 대한 타임아웃을 설정하고 기본값인 5분을 재정의하려면 job 변수 RUNNER_AFTER_SCRIPT_TIMEOUT을 사용합니다.

이 두 변수 모두 Go의 duration 포맷(예: 40s, 1h20m, 2h 4h30m30s)을 사용합니다.

예시:

job-with-script-timeouts:
  variables:
    RUNNER_SCRIPT_TIMEOUT: 15m
    RUNNER_AFTER_SCRIPT_TIMEOUT: 10m
  script:
    - "I am allowed to run for min(15m, remaining job timeout)."
  after_script:
    - "I am allowed to run for min(10m, remaining job timeout)."

job-artifact-upload-on-timeout:
  timeout: 1h                           # 작업 타임아웃을 1시간으로 설정
  variables:
     RUNNER_SCRIPT_TIMEOUT: 50m         # script가 50분 동안만 실행되도록 허용
  script:
    - long-running-process > output.txt # 50분 후에 종료됨

  artifacts: # 아티팩트에 약 ~10분이 남음
    paths:
      - output.txt
    when: on_failure # on_failure: 타임아웃 후 script 종료는 실패로 처리됨

after_script 실행 보장#

after_script가 성공적으로 실행되려면 RUNNER_SCRIPT_TIMEOUT + RUNNER_AFTER_SCRIPT_TIMEOUT의 합이 job에 구성된 타임아웃을 초과해서는 안 됩니다.

다음 예시는 메인 script가 타임아웃될 때에도 after_script가 실행되도록 타임아웃을 구성하는 방법을 보여줍니다:

job-with-script-timeouts:
  timeout: 5m
  variables:
    RUNNER_SCRIPT_TIMEOUT: 1m
    RUNNER_AFTER_SCRIPT_TIMEOUT: 1m
  script:
    - echo "Starting build..."
    - sleep 120 # 타임아웃을 트리거하기 위해 2분 대기. Script는 RUNNER_SCRIPT_TIMEOUT으로 인해 1분 후에 중단됨.
    - echo "Build finished."
  after_script:
    - echo "Starting Clean-up..."
    - sleep 15 # 잠시 대기. RUNNER_AFTER_SCRIPT_TIMEOUT 이내이므로 성공적으로 실행됨.
    - echo "Clean-up finished."

script는 RUNNER_SCRIPT_TIMEOUT에 의해 취소되지만, after_script는 15초가 걸려 RUNNER_AFTER_SCRIPT_TIMEOUT과 job의 timeout 값 모두보다 작으므로 성공적으로 실행됩니다.

민감한 정보 보호#

인스턴스 러너는 GitLab 인스턴스의 모든 그룹 및 프로젝트에서 기본적으로 사용할 수 있으므로 보안 위험이 더 큽니다. 러너 실행기(executor) 및 파일 시스템 구성은 보안에 영향을 줍니다. 러너 호스트 환경에 대한 접근 권한이 있는 사용자는 러너가 실행한 코드와 러너 인증 정보를 볼 수 있습니다. 예를 들어 러너 인증 토큰에 대한 접근 권한이 있는 사용자는 러너를 복제하고 벡터 공격으로 허위 job을 제출할 수 있습니다. 자세한 내용은 보안 고려사항을 참조하세요.

롱 폴링 구성#

job 대기 시간과 GitLab 서버의 부하를 줄이려면 롱 폴링을 구성하세요.

포크된 프로젝트에서 인스턴스 러너 사용#

프로젝트가 포크될 때 job과 관련된 job 설정이 복사됩니다. 프로젝트에 인스턴스 러너가 구성되어 있고 사용자가 해당 프로젝트를 포크하면 인스턴스 러너가 이 프로젝트의 job을 처리합니다.

알려진 이슈로 인해 포크된 프로젝트의 러너 설정이 새 프로젝트 네임스페이스와 일치하지 않으면 다음 메시지가 표시됩니다: An error occurred while forking the project. Please try again.

이 문제를 해결하려면 포크된 프로젝트와 새 네임스페이스에서 인스턴스 러너 설정이 일관되도록 확인하세요.

• 인스턴스 러너가 포크된 프로젝트에서 활성화된 경우 새 네임스페이스에서도 활성화되어야 합니다.
• 인스턴스 러너가 포크된 프로젝트에서 비활성화된 경우 새 네임스페이스에서도 비활성화되어야 합니다.

프로젝트의 러너 등록 토큰 초기화(더 이상 사용되지 않음)#

러너 등록 토큰을 전달하는 옵션 및 특정 구성 인수에 대한 지원은 레거시로 간주되며 권장되지 않습니다. 러너를 등록하기 위한 인증 토큰을 생성하려면 러너 생성 워크플로를 사용하세요. 이 프로세스는 러너 소유권의 완전한 추적 가능성을 제공하고 러너 플릿의 보안을 강화합니다. 자세한 내용은 새 러너 등록 워크플로로 마이그레이션을 참조하세요.

프로젝트의 등록 토큰이 노출되었다고 생각되면 초기화해야 합니다. 등록 토큰은 프로젝트에 다른 러너를 등록하는 데 사용될 수 있습니다. 그런 다음 새 러너는 시크릿 변수의 값을 얻거나 프로젝트 코드를 복제하는 데 사용될 수 있습니다.

등록 토큰을 초기화하려면:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Runners를 펼칩니다.
4. New project runner의 오른쪽에서 수직 줄임표를 선택합니다.
5. Reset registration token을 선택합니다.
6. Reset token을 선택합니다.

등록 토큰을 초기화하면 더 이상 유효하지 않으며 프로젝트에 새 러너를 등록하지 않습니다. 새 값을 프로비저닝하고 등록하는 데 사용하는 도구에서도 등록 토큰을 업데이트해야 합니다.

인증 토큰 보안#

각 러너는 러너 인증 토큰을 사용하여 GitLab 인스턴스에 연결하고 인증합니다.

토큰이 노출되는 것을 방지하기 위해 지정된 간격으로 토큰이 자동으로 교체(rotate)되도록 설정할 수 있습니다. 토큰이 교체되면 러너의 상태(online 또는 offline)에 관계없이 각 러너에 대해 업데이트됩니다.

수동 개입은 필요 없으며 실행 중인 job에 영향을 주지 않아야 합니다. 토큰 교체에 대한 자세한 내용은 러너 인증 토큰이 교체 시 업데이트되지 않는 경우를 참조하세요.

러너 인증 토큰을 수동으로 업데이트해야 하는 경우 명령을 실행하여 토큰을 초기화할 수 있습니다.

러너 구성 인증 토큰 초기화#

러너의 인증 토큰이 노출된 경우 공격자가 이를 사용하여 러너를 복제할 수 있습니다.

러너 구성 인증 토큰을 초기화하려면:

1. 러너를 삭제합니다:
   • 인스턴스 러너 삭제.
   • 그룹 러너 삭제.
   • 프로젝트 러너 삭제.
2. 새 러너 인증 토큰이 할당되도록 새 러너를 생성합니다:
   • 인스턴스 러너 생성.
   • 그룹 러너 생성.
   • 프로젝트 러너 생성.
3. 선택 사항. 이전 러너 인증 토큰이 취소되었는지 확인하려면 Runners API를 사용합니다.

러너 구성 인증 토큰을 초기화하려면 Runners API를 사용할 수도 있습니다.

러너 인증 토큰 자동 교체#

러너 인증 토큰을 교체할 간격을 지정할 수 있습니다. 정기적으로 러너 인증 토큰을 교체하면 노출된 토큰을 통한 GitLab 인스턴스에 대한 무단 접근 위험을 최소화하는 데 도움이 됩니다.

필수 조건:

• 관리자여야 합니다.

러너 인증 토큰을 자동으로 교체하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Continuous Integration and Deployment를 펼칩니다.
4. 러너에 대한 Runners expiration 시간을 설정하거나, 만료 없음의 경우 비워 둡니다.
5. Save changes를 선택합니다.

간격이 만료되기 전에 러너는 자동으로 새 러너 인증 토큰을 요청합니다. 토큰 교체에 대한 자세한 내용은 러너 인증 토큰이 교체 시 업데이트되지 않는 경우를 참조하세요.

러너가 민감한 정보를 노출하지 않도록 방지#

러너가 민감한 정보를 노출하지 않도록 하려면 보호된 브랜치에서만 job을 실행하거나 보호된 태그가 있는 job만 실행하도록 구성할 수 있습니다.

보호된 브랜치에서 job을 실행하도록 구성된 러너는 선택적으로 머지 리퀘스트 파이프라인에서 job을 실행할 수 있습니다.

인스턴스 러너의 경우#

필수 조건:

• 관리자여야 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 CI/CD > Runners를 선택합니다.
3. 보호할 러너의 오른쪽에서 Edit을 선택합니다.
4. Protected 체크박스를 선택합니다.
5. Save changes를 선택합니다.

그룹 러너의 경우#

필수 조건:

• 그룹에 대한 Owner 권한이 있어야 합니다.

1. 상단 표시줄에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Build > Runners를 선택합니다.
3. 보호할 러너의 오른쪽에서 Edit을 선택합니다.
4. Protected 체크박스를 선택합니다.
5. Save changes를 선택합니다.

프로젝트 러너의 경우#

필수 조건:

• 프로젝트에 대한 Owner 권한이 있어야 합니다.

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Runners를 펼칩니다.
4. 보호할 러너의 오른쪽에서 Edit을 선택합니다.
5. Protected 체크박스를 선택합니다.
6. Save changes를 선택합니다.

러너가 실행할 수 있는 job 제어#

태그를 사용하여 러너가 실행할 수 있는 job을 제어할 수 있습니다. 예를 들어 Rails 테스트 스위트를 실행하는 데 필요한 의존성이 있는 러너에 rails 태그를 지정할 수 있습니다.

GitLab CI/CD 태그는 Git 태그와 다릅니다. GitLab CI/CD 태그는 러너와 연결됩니다. Git 태그는 커밋과 연결됩니다.

인스턴스 러너의 경우#

필수 조건:

• 관리자여야 합니다.

인스턴스 러너가 실행할 수 있는 job을 제어하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 CI/CD > Runners를 선택합니다.
3. 편집할 러너의 오른쪽에서 Edit을 선택합니다.
4. 태그가 있는 job 또는 태그가 없는 job을 실행하도록 러너를 설정합니다:
   • 태그가 있는 job을 실행하려면 Tags 필드에 쉼표로 구분된 job 태그를 입력합니다. 예: macos, rails.
   • 태그가 없는 job을 실행하려면 Run untagged jobs 체크박스를 선택합니다.
5. Save changes를 선택합니다.

그룹 러너의 경우#

필수 조건:

• 그룹에 대한 Owner 권한이 있어야 합니다.

그룹 러너가 실행할 수 있는 job을 제어하려면:

1. 상단 표시줄에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Build > Runners를 선택합니다.
3. 편집할 러너의 오른쪽에서 Edit을 선택합니다.
4. 태그가 있는 job 또는 태그가 없는 job을 실행하도록 러너를 설정합니다:
   • 태그가 있는 job을 실행하려면 Tags 필드에 쉼표로 구분된 job 태그를 입력합니다. 예: macos, ruby.
   • 태그가 없는 job을 실행하려면 Run untagged jobs 체크박스를 선택합니다.
5. Save changes를 선택합니다.

프로젝트 러너의 경우#

필수 조건:

• 프로젝트에 대한 Owner 권한이 있어야 합니다.

프로젝트 러너가 실행할 수 있는 job을 제어하려면:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Runners를 펼칩니다.
4. 편집할 러너의 오른쪽에서 Edit을 선택합니다.
5. 태그가 있는 job 또는 태그가 없는 job을 실행하도록 러너를 설정합니다:
   • 태그가 있는 job을 실행하려면 Tags 필드에 쉼표로 구분된 job 태그를 입력합니다. 예: macos, ruby.
   • 태그가 없는 job을 실행하려면 Run untagged jobs 체크박스를 선택합니다.
6. Save changes를 선택합니다.

러너가 태그를 사용하는 방법#

러너가 태그가 있는 job만 실행하는 경우#

다음 예시는 태그가 있는 job만 실행하도록 설정된 러너의 잠재적 영향을 보여줍니다.

예시 1:

1. 러너가 태그가 있는 job만 실행하도록 구성되었으며 docker 태그가 있습니다.
2. hello 태그가 있는 job이 실행되어 멈춥니다.

예시 2:

1. 러너가 태그가 있는 job만 실행하도록 구성되었으며 docker 태그가 있습니다.
2. docker 태그가 있는 job이 실행됩니다.

예시 3:

1. 러너가 태그가 있는 job만 실행하도록 구성되었으며 docker 태그가 있습니다.
2. 태그가 정의되지 않은 job이 실행되어 멈춥니다.

러너가 태그 없는 job도 실행하도록 허용된 경우#

다음 예시는 태그가 있는 job과 없는 job 모두 실행하도록 설정된 러너의 잠재적 영향을 보여줍니다.

예시 1:

1. 러너가 태그 없는 job을 실행하도록 구성되었으며 docker 태그가 있습니다.
2. 태그가 정의되지 않은 job이 실행됩니다.
3. docker 태그가 정의된 두 번째 job이 실행됩니다.

예시 2:

1. 러너가 태그 없는 job을 실행하도록 구성되었으며 태그가 정의되지 않았습니다.
2. 태그가 정의되지 않은 job이 실행됩니다.
3. docker 태그가 정의된 두 번째 job이 멈춥니다.

러너와 job 모두 여러 태그를 가진 경우#

job과 러너를 매칭하는 선택 로직은 job에 정의된 tags 목록을 기반으로 합니다.

다음 예시는 러너와 job 모두 여러 태그를 가질 때의 영향을 보여줍니다. 러너가 job을 실행하도록 선택되려면, job의 script 블록에 정의된 모든 태그를 가지고 있어야 합니다.

예시 1:

1. 러너가 태그 [docker, shell, gpu]로 구성되었습니다.
2. job에 태그 [docker, shell, gpu]가 있으며 실행됩니다.

예시 2:

1. 러너가 태그 [docker, shell, gpu]로 구성되었습니다.
2. job에 태그 [docker, shell,]이 있으며 실행됩니다.

예시 3:

1. 러너가 태그 [docker, shell]로 구성되었습니다.
2. job에 태그 [docker, shell, gpu]가 있으며 실행되지 않습니다.

태그를 사용하여 다른 플랫폼에서 job 실행#

태그를 사용하여 다른 플랫폼에서 다른 job을 실행할 수 있습니다. 예를 들어 osx 태그의 OS X 러너와 windows 태그의 Windows 러너가 있으면 각 플랫폼에서 job을 실행할 수 있습니다.

.gitlab-ci.yml의 tags 필드를 업데이트합니다:

windows job:
  stage: build
  tags:
    - windows
  script:
    - echo Hello, %USERNAME%!

osx job:
  stage: build
  tags:
    - osx
  script:
    - echo "Hello, $USER!"

태그에 CI/CD 변수 사용#

.gitlab-ci.yml 파일에서 tags와 함께 CI/CD 변수를 사용하여 동적 러너 선택을 할 수 있습니다:

variables:
  KUBERNETES_RUNNER: kubernetes

  job:
    tags:
      - docker
      - $KUBERNETES_RUNNER
    script:
      - echo "Hello runner selector feature"

변수로 러너 동작 구성#

CI/CD 변수를 사용하여 러너 Git 동작을 전역적으로 또는 개별 job에 대해 구성할 수 있습니다:

• GIT_STRATEGY
• GIT_SUBMODULE_STRATEGY
• GIT_CHECKOUT
• GIT_CLEAN_FLAGS
• GIT_FETCH_EXTRA_FLAGS
• GIT_CLONE_EXTRA_FLAGS
• GIT_SUBMODULE_UPDATE_FLAGS
• GIT_SUBMODULE_FORCE_HTTPS
• GIT_DEPTH (얕은 복제)
• GIT_SUBMODULE_DEPTH
• GIT_CLONE_PATH (사용자 정의 빌드 디렉터리)
• TRANSFER_METER_FREQUENCY (아티팩트/캐시 미터 업데이트 빈도)
• ARTIFACT_COMPRESSION_LEVEL (아티팩트 아카이버 압축 레벨)
• CACHE_COMPRESSION_LEVEL (캐시 아카이버 압축 레벨)
• CACHE_REQUEST_TIMEOUT (캐시 요청 타임아웃)
• RUNNER_SCRIPT_TIMEOUT
• RUNNER_AFTER_SCRIPT_TIMEOUT
• AFTER_SCRIPT_IGNORE_ERRORS

변수를 사용하여 러너가 job 실행의 특정 Stage를 시도하는 횟수를 구성할 수도 있습니다.

쿠버네티스 실행기를 사용하는 경우 변수를 사용하여 요청 및 제한에 대한 쿠버네티스 CPU 및 메모리 할당을 재정의할 수 있습니다.

러너 기능 플래그는 job 및 파이프라인 변수로도 허용됩니다.

Git 전략#

GIT_STRATEGY 변수는 빌드 디렉터리가 준비되고 리포지터리 콘텐츠를 가져오는 방법을 구성합니다. 이 변수를 variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

variables:
  GIT_STRATEGY: clone

가능한 값은 clone, fetch, none, empty입니다. 값을 지정하지 않으면 job은 프로젝트의 파이프라인 설정을 사용합니다.

clone은 가장 느린 옵션입니다. 매 job마다 처음부터 리포지터리를 복제하여 로컬 작업 복사본이 항상 깨끗한 상태를 유지합니다. 기존 워크트리가 발견되면 복제하기 전에 제거됩니다.

fetch는 로컬 작업 복사본을 재사용하므로 더 빠릅니다(존재하지 않는 경우 clone으로 폴백). 마지막 job이 수행한 변경 사항을 되돌리기 위해 git clean이 사용되고, 마지막 job이 실행된 후 이루어진 커밋을 검색하기 위해 git fetch가 사용됩니다.

그러나 fetch는 이전 워크트리에 대한 접근이 필요합니다. shell 또는 docker 실행기를 사용할 때는 이러한 실행기가 워크트리를 유지하고 기본적으로 재사용하려 하므로 잘 동작합니다.

Docker Machine 실행기를 사용할 때는 제한이 있습니다.

none의 Git 전략은 로컬 작업 복사본도 재사용하지만, GitLab이 일반적으로 수행하는 모든 Git 작업을 건너뜁니다. GitLab Runner의 사전 복제(pre-clone) 스크립트도 있으면 건너뜁니다. 이 전략을 사용하면 .gitlab-ci.yml script에 fetch 및 checkout 명령을 추가해야 할 수 있습니다.

배포 job과 같이 아티팩트에서만 작동하는 job에 사용할 수 있습니다. Git 리포지터리 데이터가 있을 수 있지만 최신 상태가 아닐 수 있습니다. 캐시나 아티팩트에서 로컬 작업 복사본으로 가져온 파일에만 의존해야 합니다. 이전 파이프라인의 캐시 및 아티팩트 파일이 여전히 존재할 수 있다는 점에 유의하세요.

none과 달리 empty Git 전략은 캐시나 아티팩트 파일을 다운로드하기 전에 전용 빌드 디렉터리를 삭제한 다음 다시 생성합니다. 이 전략을 사용하면 GitLab Runner 훅 스크립트가 여전히 실행됩니다(있는 경우)하여 추가적인 동작 사용자 정의를 허용합니다. 다음의 경우에 empty Git 전략을 사용하세요:

• 리포지터리 데이터가 필요하지 않을 때.
• job이 실행될 때마다 깨끗하고 제어되거나 사용자 정의된 시작 상태를 원할 때.

Git 서브모듈 전략#

GIT_SUBMODULE_STRATEGY 변수는 빌드 전에 코드를 가져올 때 Git 서브모듈이 포함되는지 여부와 방법을 제어하는 데 사용됩니다. variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

가능한 세 가지 값은 none, normal, recursive입니다:

• none은 프로젝트 코드를 가져올 때 서브모듈이 포함되지 않음을 의미합니다. 이 설정은 버전 1.10 이전의 기본 동작과 일치합니다.

• normal은 최상위 서브모듈만 포함됩니다. 다음과 동일합니다:

  git submodule sync
  git submodule update --init
  

• recursive는 모든 서브모듈(서브모듈의 서브모듈 포함)이 포함됩니다. 이 기능에는 Git v1.8.1 이상이 필요합니다. Docker 기반이 아닌 실행기가 있는 GitLab Runner를 사용할 때는 Git 버전이 해당 요구사항을 충족하는지 확인하세요. 다음과 동일합니다:

  git submodule sync --recursive
  git submodule update --init --recursive
  

이 기능이 올바르게 작동하려면 서브모듈이 (.gitmodules에서) 다음 중 하나로 구성되어야 합니다:

• 공개적으로 접근 가능한 리포지터리의 HTTP(S) URL, 또는
• 동일한 GitLab 서버의 다른 리포지터리에 대한 상대 경로. Git 서브모듈 문서를 참조하세요.

GIT_SUBMODULE_UPDATE_FLAGS를 사용하여 고급 동작을 제어하는 추가 플래그를 제공할 수 있습니다.

Git checkout#

GIT_CHECKOUT 변수는 GIT_STRATEGY가 clone 또는 fetch로 설정된 경우 git checkout을 실행할지 여부를 지정하는 데 사용할 수 있습니다. 지정하지 않으면 기본값은 true입니다. variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

false로 설정하면 러너는:

• fetch를 수행할 때 - 리포지터리를 업데이트하고 현재 리비전의 작업 복사본을 그대로 유지합니다.
• clone을 수행할 때 - 리포지터리를 복제하고 기본 브랜치의 작업 복사본을 그대로 유지합니다.

GIT_CHECKOUT이 true로 설정되면 clone과 fetch 모두 동일하게 동작합니다. 러너는 CI 파이프라인과 관련된 리비전의 작업 복사본을 체크아웃합니다:

variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: "false"
script:
  - git checkout -B master origin/master
  - git merge $CI_COMMIT_SHA

Git clean 플래그#

GIT_CLEAN_FLAGS 변수는 소스를 체크아웃한 후 git clean의 기본 동작을 제어하는 데 사용됩니다. variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

GIT_CLEAN_FLAGS는 git clean 명령의 모든 가능한 옵션을 허용합니다.

GIT_CHECKOUT: "false"가 지정된 경우 git clean은 비활성화됩니다.

GIT_CLEAN_FLAGS가:

• 지정되지 않은 경우 git clean 플래그는 기본적으로 -ffdx입니다.
• none 값이 주어진 경우 git clean이 실행되지 않습니다.

예시:

variables:
  GIT_CLEAN_FLAGS: -ffdx -e cache/
script:
  - ls -al cache/

Git fetch 추가 플래그#

GIT_FETCH_EXTRA_FLAGS 변수를 사용하여 git fetch의 동작을 제어합니다. variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

GIT_FETCH_EXTRA_FLAGS는 git fetch 명령의 모든 옵션을 허용합니다. 그러나 GIT_FETCH_EXTRA_FLAGS 플래그는 수정할 수 없는 기본 플래그 이후에 추가됩니다.

기본 플래그는 다음과 같습니다:

• GIT_DEPTH.
• refspec 목록.
• origin이라는 원격 저장소.

GIT_FETCH_EXTRA_FLAGS가:

• 지정되지 않으면, git fetch 플래그는 기본 플래그와 함께 기본적으로 --prune --quiet입니다.
• none 값이 주어지면, git fetch는 기본 플래그만으로 실행됩니다.

예를 들어, 기본 플래그가 --prune --quiet이므로 --prune만으로 재정의하여 git fetch를 더 자세하게 만들 수 있습니다:

variables:
  GIT_FETCH_EXTRA_FLAGS: --prune
script:
  - ls -al cache/

이전 구성은 다음과 같이 git fetch가 호출되는 결과를 낳습니다:

git fetch origin $REFSPECS --depth 20  --prune

여기서 $REFSPECS는 GitLab이 내부적으로 러너에 제공하는 값입니다.

Git clone 추가 플래그#

GIT_CLONE_EXTRA_FLAGS 변수를 사용하여 네이티브 git clone 작업에 추가 인수를 전달합니다. variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

GIT_CLONE_EXTRA_FLAGS를 사용하려면:

• 네이티브 git clone 기능을 활성화하려면 FF_USE_GIT_NATIVE_CLONE을 true로 설정합니다.
• fetch 대신 clone 전략을 사용하려면 GIT_STRATEGY를 clone으로 설정합니다.
• Git 클라이언트는 최소 버전 2.49여야 합니다. 이 조건은 헬퍼 이미지가 버전 18.1 이상의 Linux 기반 이미지인 경우 자동으로 충족됩니다.

GIT_CLONE_EXTRA_FLAGS는 git clone 명령의 모든 옵션을 허용합니다. 플래그는 네이티브 git clone 명령에 추가되어 대체 리포지터리를 참조하거나 clone 성능을 최적화하는 등의 고급 사용 사례를 위한 유연성을 제공합니다.

예를 들어, 참조 리포지터리를 사용하여 clone 성능을 최적화할 수 있습니다:

variables:
  FF_USE_GIT_NATIVE_CLONE: true
  GIT_STRATEGY: clone
  GIT_CLONE_EXTRA_FLAGS: "--reference-if-available /tmp/test"

GIT_CLONE_EXTRA_FLAGS가 지정되지 않으면 git clone은 기본 플래그만 사용합니다.

CI job에서 특정 서브모듈 동기화 또는 제외#

GIT_SUBMODULE_PATHS 변수를 사용하여 어떤 서브모듈을 동기화하거나 업데이트해야 하는지 제어합니다. variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

경로 구문은 git submodule과 동일합니다:

• 특정 경로를 동기화하고 업데이트하려면:

  variables:
     GIT_SUBMODULE_PATHS: submoduleA submoduleB
  

• 특정 경로를 제외하려면:

  variables:
     GIT_SUBMODULE_PATHS: ":(exclude)submoduleA :(exclude)submoduleB"
  

Git은 중첩된 경로를 무시합니다. 중첩된 서브모듈을 무시하려면 상위 서브모듈을 제외하고 job의 script에서 수동으로 복제하세요. 예: git clone <repo> --recurse-submodules=':(exclude)nested-submodule'. YAML이 성공적으로 파싱될 수 있도록 문자열을 작은따옴표로 감싸세요.

Git 서브모듈 업데이트 플래그#

GIT_SUBMODULE_UPDATE_FLAGS 변수를 사용하여 GIT_SUBMODULE_STRATEGY가 normal 또는 recursive로 설정된 경우 git submodule update의 동작을 제어합니다. variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

GIT_SUBMODULE_UPDATE_FLAGS는 git submodule update 하위 명령의 모든 옵션을 허용합니다. 그러나 GIT_SUBMODULE_UPDATE_FLAGS 플래그는 몇 가지 기본 플래그 이후에 추가됩니다:

• --init, GIT_SUBMODULE_STRATEGY가 normal 또는 recursive로 설정된 경우.
• --recursive, GIT_SUBMODULE_STRATEGY가 recursive로 설정된 경우.
• GIT_DEPTH. 기본값은 얕은 복제 섹션을 참조하세요.

Git은 인수 목록의 마지막 플래그를 적용하므로, GIT_SUBMODULE_UPDATE_FLAGS에서 수동으로 제공하면 이러한 기본 플래그를 재정의합니다.

예를 들어, 이 변수를 다음과 같이 사용할 수 있습니다:

• 리포지터리에서 추적된 커밋(기본값) 대신 최신 원격 HEAD를 가져와 --remote 플래그로 모든 서브모듈을 자동으로 업데이트합니다.
• --jobs 4 플래그로 여러 병렬 job에서 서브모듈을 가져와 체크아웃 속도를 높입니다.

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_UPDATE_FLAGS: --remote --jobs 4
script:
  - ls -al .git/modules/

이전 구성은 다음과 같이 git submodule update가 호출되는 결과를 낳습니다:

git submodule update --init --depth 20 --recursive --remote --jobs 4

--remote 플래그를 사용할 때는 빌드의 보안, 안정성, 재현성에 대한 영향을 인지해야 합니다. 대부분의 경우, 설계된 대로 서브모듈 커밋을 명시적으로 추적하고 자동 수정/의존성 봇을 사용하여 업데이트하는 것이 더 좋습니다.

--remote 플래그는 커밋된 리비전에서 서브모듈을 체크아웃하는 데 필요하지 않습니다. 서브모듈을 최신 원격 버전으로 자동 업데이트하려는 경우에만 이 플래그를 사용하세요.

--remote의 동작은 Git 버전에 따라 다릅니다. 슈퍼프로젝트의 .gitmodules 파일에 지정된 브랜치가 서브모듈 리포지터리의 기본 브랜치와 다른 경우, 일부 Git 버전은 다음 오류와 함께 실패합니다:

fatal: Unable to find refs/remotes/origin/<branch> revision in submodule path '<submodule-path>'

러너는 서브모듈 업데이트가 실패할 때 원격 refs를 풀링(pull)하려는 "최선의 노력(best effort)" 폴백을 구현합니다.

이 폴백이 사용 중인 Git 버전에서 작동하지 않는 경우 다음 해결 방법 중 하나를 시도하세요:

• 서브모듈 리포지터리의 기본 브랜치를 슈퍼프로젝트의 .gitmodules에 설정된 브랜치와 일치하도록 업데이트합니다.
• GIT_SUBMODULE_DEPTH를 0으로 설정합니다.
• 서브모듈을 별도로 업데이트하고 GIT_SUBMODULE_UPDATE_FLAGS에서 --remote 플래그를 제거합니다.

서브모듈 URL을 HTTPS로 재작성#

GIT_SUBMODULE_FORCE_HTTPS 변수를 사용하여 모든 Git 및 SSH 서브모듈 URL을 HTTPS로 강제 재작성합니다. Git 또는 SSH 프로토콜로 구성된 경우에도 동일한 GitLab 인스턴스에서 절대 URL을 사용하는 서브모듈을 복제할 수 있습니다.

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_FORCE_HTTPS: "true"

활성화하면 GitLab Runner는 CI/CD job 토큰을 사용하여 서브모듈을 복제합니다. 토큰은 job을 실행하는 사용자의 권한을 사용하며 SSH 자격 증명이 필요하지 않습니다.

얕은 복제#

GIT_DEPTH를 사용하여 가져오기 및 복제의 깊이를 지정할 수 있습니다. GIT_DEPTH는 리포지터리의 얕은 복제를 수행하여 복제 속도를 크게 높일 수 있습니다. 커밋 수가 많거나 오래되고 큰 바이너리가 있는 리포지터리에 유용합니다. 값은 git fetch와 git clone에 전달됩니다.

새로 생성된 프로젝트는 자동으로 기본 git depth 값 20을 갖습니다.

깊이 1을 사용하고 job 대기열이 있거나 job을 재시도하면 job이 실패할 수 있습니다.

Git 가져오기 및 복제는 브랜치 이름과 같은 ref를 기반으로 하므로, 러너는 특정 커밋 SHA를 복제할 수 없습니다. 여러 job이 대기열에 있거나 오래된 job을 재시도하는 경우, 테스트할 커밋이 복제된 Git 기록에 있어야 합니다. GIT_DEPTH에 너무 작은 값을 설정하면 이러한 오래된 커밋을 실행하는 것이 불가능해질 수 있으며, job 로그에 unresolved reference가 표시됩니다. 그러면 GIT_DEPTH를 더 높은 값으로 변경하는 것을 고려해야 합니다.

GIT_DEPTH가 설정된 경우 Git 기록의 일부만 존재하기 때문에 git describe에 의존하는 job이 올바르게 작동하지 않을 수 있습니다.

마지막 3개의 커밋만 가져오거나 복제하려면:

variables:
  GIT_DEPTH: "3"

variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

Git 서브모듈 깊이#

GIT_SUBMODULE_STRATEGY가 normal 또는 recursive로 설정된 경우 GIT_SUBMODULE_DEPTH 변수를 사용하여 서브모듈의 가져오기 및 복제 깊이를 지정합니다. variables 섹션에서 전역적으로 또는 특정 job에 대해 설정할 수 있습니다.

GIT_SUBMODULE_DEPTH 변수를 설정하면 서브모듈에 대해서만 GIT_DEPTH 설정을 덮어씁니다.

마지막 3개의 커밋만 가져오거나 복제하려면:

variables:
  GIT_SUBMODULE_DEPTH: 3

사용자 정의 빌드 디렉터리#

기본적으로 GitLab Runner는 $CI_BUILDS_DIR 디렉터리의 고유한 하위 경로에 리포지터리를 복제합니다. 그러나 프로젝트가 특정 디렉터리(예: Go 프로젝트)에 코드가 필요할 수 있습니다. 이 경우 GIT_CLONE_PATH 변수를 지정하여 러너에게 리포지터리를 복제할 디렉터리를 알려줄 수 있습니다:

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name

test:
  script:
    - pwd

GIT_CLONE_PATH는 항상 $CI_BUILDS_DIR 내에 있어야 합니다. $CI_BUILDS_DIR에 설정된 디렉터리는 실행기와 runners.builds_dir 설정 구성에 따라 다릅니다.

이 기능은 러너의 구성에서 custom_build_dir이 활성화된 경우에만 사용할 수 있습니다.

동시성 처리#

동시성이 1보다 큰 실행기를 사용하면 실패를 야기할 수 있습니다. builds_dir이 job 간에 공유되면 여러 job이 동일한 디렉터리에서 작업할 수 있습니다.

러너는 이 상황을 방지하려 하지 않습니다. 러너 구성 요구 사항을 준수하는 것은 관리자와 개발자의 책임입니다.

이 시나리오를 피하려면, 러너가 동시성의 고유한 ID를 제공하는 두 가지 추가 변수를 노출하기 때문에 $CI_BUILDS_DIR에서 고유한 경로를 사용할 수 있습니다:

• $CI_CONCURRENT_ID: 주어진 실행기에서 실행 중인 모든 job에 대한 고유 ID.
• $CI_CONCURRENT_PROJECT_ID: 주어진 실행기 및 프로젝트에서 실행 중인 모든 job에 대한 고유 ID.

어떤 시나리오와 어떤 실행기에서도 잘 작동해야 하는 가장 안정적인 구성은 GIT_CLONE_PATH에서 $CI_CONCURRENT_ID를 사용하는 것입니다. 예:

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name

test:
  script:
    - pwd -P

$CI_CONCURRENT_PROJECT_ID는 $CI_PROJECT_PATH와 함께 사용해야 합니다. $CI_PROJECT_PATH는 group/subgroup/project 형식의 리포지터리 경로를 제공합니다. 예:

variables:
  GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH

test:
  script:
    - pwd -P

중첩된 경로#

GIT_CLONE_PATH의 값은 한 번만 확장됩니다. 이 값에 변수를 중첩할 수 없습니다.

예를 들어, .gitlab-ci.yml 파일에서 다음 변수를 정의한 경우:

variables:
  GOPATH: $CI_BUILDS_DIR/go
  GIT_CLONE_PATH: $GOPATH/src/namespace/project

GIT_CLONE_PATH의 값은 $CI_BUILDS_DIR/go/src/namespace/project로 한 번 확장되고, $CI_BUILDS_DIR이 확장되지 않기 때문에 실패합니다.

after_script에서 오류 무시#

job의 before_script와 script 섹션 이후에 실행해야 하는 명령 배열을 정의하기 위해 job에서 after_script를 사용할 수 있습니다. after_script 명령은 script 종료 상태(실패 또는 성공)에 관계없이 실행됩니다.

기본적으로 GitLab Runner는 after_script 실행 중 발생하는 오류를 무시합니다. after_script 실행 중 오류 발생 시 job이 즉시 실패하도록 설정하려면, AFTER_SCRIPT_IGNORE_ERRORS CI/CD 변수를 false로 설정합니다. 예:

variables:
  AFTER_SCRIPT_IGNORE_ERRORS: false

Job Stage 시도 횟수#

실행 중인 job이 다음 Stage를 실행하려는 시도 횟수를 설정할 수 있습니다:

기본값은 한 번의 시도입니다.

예시:

variables:
  GET_SOURCES_ATTEMPTS: 3

variables 섹션에서 전역적으로 또는 job별로 설정할 수 있습니다.

GitLab.com 인스턴스 러너에서 사용할 수 없는 시스템 호출#

GitLab.com 인스턴스 러너는 CoreOS에서 실행됩니다. 즉, C 표준 라이브러리에서 getlogin과 같은 일부 시스템 호출을 사용할 수 없습니다.

아티팩트 및 캐시 설정#

아티팩트 및 캐시 설정은 아티팩트와 캐시의 압축 비율을 제어합니다. 이 설정을 사용하여 job이 생성하는 아카이브의 크기를 지정합니다.

• 느린 네트워크에서는 더 작은 아카이브의 업로드가 더 빠를 수 있습니다.
• 대역폭과 스토리지가 문제가 되지 않는 빠른 네트워크에서는 생성된 아카이브가 더 크더라도 가장 빠른 압축 비율을 사용하면 업로드가 더 빠를 수 있습니다.

HTTP Range 요청을 제공하기 위해 GitLab Pages의 경우, 아티팩트는 ARTIFACT_COMPRESSION_LEVEL: fastest 설정을 사용해야 합니다. 이 기능은 압축되지 않은 zip 아카이브만 지원합니다.

미터를 활성화하여 업로드 및 다운로드의 전송 속도를 제공할 수 있습니다.

CACHE_REQUEST_TIMEOUT 설정으로 캐시 업로드 및 다운로드의 최대 시간을 설정할 수 있습니다. 느린 캐시 업로드로 인해 job 시간이 크게 증가하는 경우 이 설정을 사용하세요.

variables:
  # output upload and download progress every 2 seconds
  TRANSFER_METER_FREQUENCY: "2s"

  # Use fast compression for artifacts, resulting in larger archives
  ARTIFACT_COMPRESSION_LEVEL: "fast"

  # Use no compression for caches
  CACHE_COMPRESSION_LEVEL: "fastest"

  # Set maximum duration of cache upload and download
  CACHE_REQUEST_TIMEOUT: 5

고지연 연결을 위한 TCP 설정 튜닝#

러너와 GitLab 인스턴스 사이에 상당한 네트워크 지연이 있는 경우, 기본 TCP 윈도우 크기가 처리량을 제한할 수 있습니다. 러너 호스트에서 TCP 윈도우 크기를 늘려 더 많은 데이터를 전송 중 상태로 허용하세요.

예를 들어, Linux에서 최대 TCP 버퍼 크기를 늘리려면:

sudo sysctl -w net.core.rmem_max=16777216
sudo sysctl -w net.core.wmem_max=16777216
sudo sysctl -w net.ipv4.tcp_rmem="4096 87380 16777216"
sudo sysctl -w net.ipv4.tcp_wmem="4096 65536 16777216"

재부팅 시에도 이러한 변경 사항이 지속되도록 하려면 /etc/sysctl.conf에 추가합니다.

TCP 튜닝은 러너 머신의 모든 네트워크 연결에 영향을 미치는 호스트 수준 변경 사항입니다. 먼저 비프로덕션 환경에서 변경 사항을 테스트하세요.

아티팩트 출처 메타데이터#

러너는 SLSA Provenance를 생성하고 모든 빌드 아티팩트에 출처를 바인딩하는 SLSA Statement를 생성할 수 있습니다. 이 statement를 아티팩트 출처 메타데이터라고 합니다.

아티팩트 출처 메타데이터를 활성화하려면 RUNNER_GENERATE_ARTIFACTS_METADATA 환경 변수를 true로 설정합니다. 전역적으로 또는 개별 job에 대해 변수를 설정할 수 있습니다:

variables:
  RUNNER_GENERATE_ARTIFACTS_METADATA: "true"

job1:
  variables:
    RUNNER_GENERATE_ARTIFACTS_METADATA: "true"

메타데이터는 아티팩트와 함께 저장되는 일반 텍스트 .json 파일에 렌더링됩니다. 파일 이름은 {ARTIFACT_NAME}-metadata.json입니다. ARTIFACT_NAME은 .gitlab-ci.yml 파일에 정의된 아티팩트 이름입니다. 이름이 정의되지 않은 경우 기본 파일 이름은 artifacts-metadata.json입니다.

출처 메타데이터 형식#

아티팩트 출처 메타데이터는 in-toto v0.1 Statement 형식으로 생성됩니다. SLSA 1.0 Provenance 형식으로 생성된 출처 predicate를 포함합니다.

기본적으로 다음 필드가 채워집니다:

출처 statement는 다음 예시와 유사해야 합니다:

{
 "_type": "https://in-toto.io/Statement/v0.1",
 "predicateType": "https://slsa.dev/provenance/v1",
 "subject": [
  {
   "name": "x.txt",
   "digest": {
    "sha256": "ac097997b6ec7de591d4f11315e4aa112e515bb5d3c52160d0c571298196ea8b"
   }
  },
  {
   "name": "y.txt",
   "digest": {
    "sha256": "9eb634f80da849d828fcf42740d823568c49e8d7b532886134f9086246b1fdf3"
   }
  }
 ],
 "predicate": {
  "buildDefinition": {
   "buildType": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/2147fb44/PROVENANCE.md",
   "externalParameters": {
    "CI": "",
    "CI_API_GRAPHQL_URL": "",
    "CI_API_V4_URL": "",
    "CI_COMMIT_AUTHOR": "",
    "CI_COMMIT_BEFORE_SHA": "",
    "CI_COMMIT_BRANCH": "",
    "CI_COMMIT_DESCRIPTION": "",
    "CI_COMMIT_MESSAGE": "",
    [... additional environmental variables ...]
    "entryPoint": "build-job",
    "source": "https://gitlab.com/my-group/my-project/test-runner-generated-slsa-statement"
   },
   "internalParameters": {
    "architecture": "amd64",
    "executor": "docker+machine",
    "job": "10340684631",
    "name": "green-4.saas-linux-small-amd64.runners-manager.gitlab.com/default"
   },
   "resolvedDependencies": [
    {
     "uri": "https://gitlab.com/my-group/my-project/test-runner-generated-slsa-statement",
     "digest": {
      "sha256": "bdd2ecda9ef57b129c88617a0215afc9fb223521"
     }
    }
   ]
  },
  "runDetails": {
   "builder": {
    "id": "https://gitlab.com/my-group/my-project/test-runner-generated-slsa-statement/-/runners/12270857",
    "version": {
     "gitlab-runner": "2147fb44"
    }
   },
   "metadata": {
    "invocationId": "10340684631",
    "startedOn": "2025-06-13T07:25:13Z",
    "finishedOn": "2025-06-13T07:25:40Z"
   }
  }
 }
}

스테이징 디렉터리#

캐시와 아티팩트를 시스템의 기본 임시 디렉터리에 아카이브하지 않으려면 다른 디렉터리를 지정할 수 있습니다.

시스템의 기본 임시 경로에 제약이 있는 경우 디렉터리를 변경해야 할 수 있습니다. 디렉터리 위치에 빠른 디스크를 사용하면 성능이 향상될 수 있습니다.

디렉터리를 변경하려면 CI job에서 ARCHIVER_STAGING_DIR을 변수로 설정하거나, 러너를 등록할 때 러너 변수를 사용합니다(gitlab register --env ARCHIVER_STAGING_DIR=<dir>).

지정한 디렉터리는 압축 해제 전에 아티팩트를 다운로드하는 위치로 사용됩니다. fastzip 아카이버가 사용되면, 이 위치는 아카이브 시 스크래치 공간으로도 사용됩니다.

fastzip 성능 향상 구성#

fastzip을 튜닝하려면 FF_USE_FASTZIP 플래그가 활성화되어 있는지 확인하세요. 그런 다음 다음 환경 변수 중 하나를 사용합니다.

zip 아카이브의 파일은 순차적으로 추가됩니다. 이로 인해 동시 압축이 어렵습니다. fastzip은 파일을 먼저 디스크에 동시에 압축한 다음 결과를 순차적으로 zip 아카이브에 복사하여 이 제한을 해결합니다.

작은 파일에 대해 디스크에 쓰고 다시 내용을 읽는 것을 피하기 위해, 동시성당 작은 버퍼가 사용됩니다. 이 설정은 FASTZIP_ARCHIVER_BUFFER_SIZE로 제어할 수 있습니다. 이 버퍼의 기본 크기는 2MiB이므로, 동시성 16에서는 32MiB를 할당합니다. 버퍼 크기를 초과하는 데이터는 디스크에 쓰이고 디스크에서 읽힙니다. 따라서 버퍼 없이(FASTZIP_ARCHIVER_BUFFER_SIZE: 0) 스크래치 공간만 사용하는 것도 유효한 옵션입니다.

FASTZIP_ARCHIVER_CONCURRENCY는 동시에 압축되는 파일 수를 제어합니다. 앞서 언급했듯이, 이 설정은 사용 중인 메모리 양을 증가시킬 수 있습니다. 또한 스크래치 공간에 쓰인 임시 데이터도 증가시킬 수 있습니다. 기본값은 사용 가능한 CPU 수이지만, 메모리 영향을 고려할 때 이것이 항상 최선의 설정은 아닐 수 있습니다.

FASTZIP_EXTRACTOR_CONCURRENCY는 한 번에 압축 해제되는 파일 수를 제어합니다. zip 아카이브의 파일은 기본적으로 동시에 읽을 수 있으므로, 추출기에 필요한 메모리 외에 추가 메모리가 할당되지 않습니다. 기본값은 사용 가능한 CPU 수입니다.