• 최대 작업 시간 설정
  • 인스턴스 러너의 경우
  • 그룹 러너의 경우
  • 프로젝트 러너의 경우
• 최대 작업 시간 설정의 작동 방식
• script 및 after_script 시간 초과 설정
• 민감한 정보 보호
• 롱 폴링 구성
  • 포크된 프로젝트에서 인스턴스 러너 사용
  • 프로젝트의 러너 등록 토큰 재설정 (사용중지됨)
• 인증 토큰 보안
  • 러너 인증 토큰 재설정
  • 러너 인증 토큰 자동으로 회전시키기
• 러너가 민감한 정보 노출 방지
  • 인스턴스 러너의 경우
  • 그룹 러너의 경우
  • 프로젝트 러너의 경우
• 러너가 실행할 수 있는 작업 제어
  • 인스턴스 러너의 경우
  • 그룹 러너의 경우
  • 프로젝트 러너의 경우
  • 러너가 태그를 사용하는 방법
    • 러너가 태그가 지정된 작업만 실행
    • Runner는 태그가 없는 작업을 실행할 수 있습니다.
    • Runner와 작업에 여러 태그가 있는 경우
  • 태그를 사용하여 다양한 플랫폼에서 작업 실행
  • 태그에서 CI/CD 변수 사용
• 변수를 사용하여 Runner 동작 구성
  • Git Clean 플래그
  • Git Fetch 추가 플래그
  • CI 작업에서 특정 서브모듈 동기화 또는 제외
  • Git 서브모듈 업데이트 플래그
  • 서브모듈 URL을 HTTPS로 변경
  • 얕은 클론
  • Git 서브모듈 깊이
  • 사용자 정의 빌드 디렉터리
    • 동시성 처리
    • 중첩 경로
  • 작업 단계 시도
• GitLab.com 인스턴스 러너에서 사용할 수 없는 시스템 호출
• Artifact 및 캐시 설정
• 아티팩트 형태 검증 메타데이터
  • 형태 검증 메타데이터 형식
  • 스테이징 디렉터리
  • 성능 향상을 위해 fastzip 구성

러너 구성

자체 러너를 설치한 경우 GitLab에서 그들을 구성하고 보안 설정할 수 있습니다.

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

최대 작업 시간 설정

각 러너에 대해 최대 작업 시간을 지정하여 작업 시간이 긴 프로젝트가 러너를 사용하지 못하도록 할 수 있습니다. 최대 작업 시간은 프로젝트에서 정의된 작업 시간보다 짧을 경우에 사용됩니다.

인스턴스 러너의 경우

전제 조건:

• 관리자여야 합니다.

GitLab.com에서는 인스턴스 러너의 작업 시간을 재정의할 수 없으며 대신 프로젝트에서 정의된 제한을 사용해야 합니다.

최대 작업 시간 설정 방법:

1. 왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
2. CI/CD > 러너를 선택합니다.
3. 수정할 러너 오른쪽에서 편집()을 선택합니다.
4. 최대 작업 시간 필드에 초 단위로 값을 입력합니다. 최소량은 600초(10분)입니다.
5. 변경 사항 저장을 선택합니다.

그룹 러너의 경우

전제 조건:

• 그룹에 대한 소유자 권한이 있어야 합니다.

최대 작업 시간 설정 방법:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 그룹을 찾습니다.
2. 빌드 > 러너를 선택합니다.
3. 수정할 러너 오른쪽에서 편집()을 선택합니다.
4. 최대 작업 시간 필드에 초 단위로 값을 입력합니다. 최소량은 600초(10분)입니다.
5. 변경 사항 저장을 선택합니다.

프로젝트 러너의 경우

전제 조건:

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

최대 작업 시간 설정 방법:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
2. 설정 > CI/CD를 선택합니다.
3. 러너를 확장합니다.
4. 수정할 러너 오른쪽에서 편집()을 선택합니다.
5. 최대 작업 시간 필드에 초 단위로 값을 입력합니다. 최소량은 600초(10분)입니다. 정의되지 않은 경우 프로젝트의 작업 시간 제한이 대신 사용됩니다.
6. 변경 사항 저장을 선택합니다.

최대 작업 시간 설정의 작동 방식

예제 1 - 러너의 작업 시간이 프로젝트의 작업 시간보다 큰 경우

1. 러너의 _최대 작업 시간_을 24시간으로 설정합니다.
2. 프로젝트의 _CI/CD 시간 제한_을 2시간으로 설정합니다.
3. 작업을 시작합니다.
4. 작업이 지속되면 2시간 후에 타임아웃됩니다.

예제 2 - 러너의 작업 시간이 설정되지 않은 경우

1. 러너에서 최대 작업 시간 구성을 제거합니다.
2. 프로젝트의 _CI/CD 시간 제한_을 2시간으로 설정합니다.
3. 작업을 시작합니다.
4. 작업이 지속되면 2시간 후에 타임아웃됩니다.

예제 3 - 러너의 작업 시간이 프로젝트의 작업 시간보다 작은 경우

1. 러너의 _최대 작업 시간_을 30분으로 설정합니다.
2. 프로젝트의 _CI/CD 시간 제한_을 2시간으로 설정합니다.
3. 작업을 시작합니다.
4. 작업이 지속되면 30분 후에 타임아웃됩니다.

script 및 after_script 시간 초과 설정

• GitLab Runner 16.4에서 소개.

script 및 after_script의 실행 시간을 제어하고 종료되기 전에 설정할 수 있습니다.

예를 들어, 긴 실행 시간의 script가 종료되기 전에 여전히 artefacts와 캐시를 업로드할 수 있도록 실행 시간을 설정할 수 있습니다.

• script에 대한 제한 시간을 설정하려면 작업 변수 RUNNER_SCRIPT_TIMEOUT를 사용합니다.
• after_script에 대한 제한 시간을 설정하려면 5분의 기본 시간을 재정의하려면 작업 변수 RUNNER_AFTER_SCRIPT_TIMEOUT를 사용합니다.

이러한 변수는 Go의 기간 형식을 받아들입니다 (예: 40s, 1h20m, 2h 4h30m30s).

예를 들어:

job-with-script-timeouts:
  variables:
    RUNNER_SCRIPT_TIMEOUT: 15m
    RUNNER_AFTER_SCRIPT_TIMEOUT: 10m
  script:
    - "15m 또는 남은 작업 시간 중 최소값 이내로 실행할 수 있습니다."
  after_script:
    - "10m 또는 남은 작업 시간 중 최소값 이내로 실행할 수 있습니다."

job-artifact-upload-on-timeout:
  timeout: 1h                           # 작업 타임아웃을 1시간으로 설정
  variables:
     RUNNER_SCRIPT_TIMEOUT: 50m         # 스크립트 실행을 50분으로 제한
  script:
    - long-running-process > output.txt # 50분 후에 종료될 것입니다.
  
  artefacts: # artefacts은 대략 ~10분 동안 업로드됩니다
    paths:
      - output.txt
    when: on_failure # 시간초과 후 스크립트 종료는 실패로 간주됩니다

민감한 정보 보호

민감한 정보 노출을 피하기 위해 대형 GitLab 인스턴스에서 인스턴스 러너의 사용을 제한할 수 있습니다. 이를 통해 GitLab 인스턴스에 대한 액세스를 제어하고 러너 실행자를 보호할 수 있습니다.

특정 실행자가 작업을 실행하면 파일 시스템, 러너가 실행하는 코드, 러너 인증 토큰이 노출될 수 있습니다. 이는 _인스턴스 러너_에서 작업을 실행하는 다른 사용자의 코드에 액세스할 수 있는 것을 의미합니다. 러너 인증 토큰에 액세스 권한이 있는 사용자는 해당 토큰을 사용하여 러너의 클론을 만들고 벡터 공격에서 거짓 작업을 제출할 수 있습니다. 자세한 정보는 보안 고려 사항을 참조하세요.

롱 폴링 구성

작업 대기 시간과 GitLab 서버의 부하를 줄이기 위해 롱 폴링을 구성할 수 있습니다.

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

프로젝트가 포크되면 작업과 관련된 작업 설정이 복사됩니다. 프로젝트에 인스턴스 러너가 구성되어 있고 사용자가 해당 프로젝트를 포크하는 경우, 인스턴스 러너가 해당 프로젝트의 작업을 수행합니다.

알려진 이슈에 따르면, 포크된 프로젝트의 러너 설정이 새 프로젝트 네임스페이스와 일치하지 않으면 다음 메시지가 표시됩니다: 프로젝트 포크 중 오류가 발생했습니다. 다시 시도하십시오..

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

• 프로젝트에서 인스턴스 러너가 활성화되어 있으면 새 네임스페이스에서도 활성화되어 있어야 합니다.
• 프로젝트에서 인스턴스 러너가 비활성화되어 있으면 새 네임스페이스에서도 비활성화되어 있어야 합니다.

프로젝트의 러너 등록 토큰 재설정 (사용중지됨)

프로젝트의 러너 등록 토큰이 노출되었다고 생각되면 재설정해야 합니다. 등록 토큰을 사용하여 프로젝트에 다른 러너를 등록할 수 있습니다. 그 새로운 러너는 그 다음에 비밀 변수의 값을 얻거나 프로젝트 코드를 복제하는 데 사용될 수 있습니다.

등록 토큰을 재설정하려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
2. 설정 > CI/CD를 선택합니다.
3. 러너를 확장합니다.
4. 새 프로젝트 러너 오른쪽에서 수직 줄임표()를 선택합니다.
5. 등록 토큰 재설정을 선택합니다.
6. 토큰 재설정을 선택합니다.

등록 토큰을 재설정한 후에는 더 이상 유효하지 않으며 프로젝트에 새 러너를 등록하지 않습니다. 또한 새 값을 프로비저닝하고 등록하는 데 사용하는 도구를 업데이트해야 합니다.

인증 토큰 보안

• GitLab 15.3에 도입, 기본으로 비활성화된 enforce_runner_token_expires_at라는 플래그와 함께.
• GitLab 15.5에서 값이 설정됨. 피처 플래그 enforce_runner_token_expires_at가 제거됨.

각 러너에는 러너 인증 토큰이 있어 GitLab 인스턴스에 연결합니다.

토큰이 Compromise 되는 것을 방지하기 위해 특정 간격으로 토큰을 자동으로 회전시킬 수 있습니다. 토큰이 회전되면 각 러너에 대해 토큰이 업데이트되며 러너의 상태(online 또는 offline)에 관계없이 업데이트됩니다.

매뉴얼 개입이 필요하지 않으며 실행 중인 작업에 영향을 미치지 않아야 합니다.

러너 인증 토큰을 매뉴얼으로 업데이트해야 하는 경우 토큰을 재설정하는 명령을 실행할 수 있습니다.

러너 인증 토큰 재설정

러너 인증 토큰이 노출되면 공격자가 해당 토큰을 사용하여 러너를 복제할 수 있습니다.

러너 인증 토큰을 재설정하려면:

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

러너 인증 토큰 자동으로 회전시키기

러너 인증 토큰의 자동 회전 간격을 지정할 수 있습니다. 이 회전은 러너에 할당된 토큰의 보안을 보장하는 데 도움이 됩니다.

전제 조건:

• 러너는 GitLab 러너 15.3 이상을 사용해야 합니다.
• 당신이 관리자여야 합니다.

러너 인증 토큰을 자동으로 회전시키려면:

1. 왼쪽 사이드바 맨 아래에서 관리 영역을 선택합니다.
2. 설정 > CI/CD를 선택합니다.
3. Continuous Integration and Deployment를 확장합니다.
4. 러너 만료 시간 Runners expiration을 설정하고 만료하지 않으려면 비워 둡니다.
5. 변경 사항 저장을 선택합니다.

간격이 만료되기 전에 러너는 자동으로 새 러너 인증 토큰을 요청합니다.

러너가 민감한 정보 노출 방지

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

보호된 브랜치에서 작업을 실행하도록 구성된 러너는 Merge Request 파이프라인에서 작업을 실행할 수 없습니다.

인스턴스 러너의 경우

전제 조건:

• 당신이 관리자여야 합니다.

1. 왼쪽 사이드바 맨 아래에서 관리 영역을 선택합니다.
2. CI/CD > Runners를 선택합니다.
3. 보호하려는 러너 오른쪽에서 편집({연필})을 선택합니다.
4. 보호됨 확인란을 선택합니다.
5. 변경 사항 저장을 선택합니다.

그룹 러너의 경우

전제 조건:

• 그룹의 소유자 역할이 있어야 합니다.

1. 왼쪽 사이드바에서 검색 또는 포커스를 선택하고 그룹을 찾습니다.
2. 빌드 > Runners를 선택합니다.
3. 보호하려는 러너 오른쪽에서 편집({연필})을 선택합니다.
4. 보호됨 확인란을 선택합니다.
5. 변경 사항 저장을 선택합니다.

프로젝트 러너의 경우

전제 조건:

• 프로젝트의 소유자 역할이 있어야 합니다.

1. 왼쪽 사이드바에서 검색 또는 포커스를 선택하고 프로젝트를 찾습니다.
2. 설정 > CI/CD를 선택합니다.
3. Runners를 확장합니다.
4. 보호하려는 러너 오른쪽에서 편집({연필})을 선택합니다.
5. 보호됨 확인란을 선택합니다.
6. 변경 사항 저장을 선택합니다.

러너가 실행할 수 있는 작업 제어

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

GitLab CI/CD 태그는 Git 태그와 다릅니다. GitLab CI/CD 태그는 러너와 관련이 있습니다. Git 태그는 커밋과 관련이 있습니다.

인스턴스 러너의 경우

전제 조건:

• 당신이 관리자여야 합니다.

최대 작업 시간을 설정하려면:

1. 왼쪽 사이드바 맨 아래에서 관리 영역을 선택합니다.
2. CI/CD > Runners를 선택합니다.
3. 편집하려는 러너 오른쪽에서 편집({연필})을 선택합니다.
4. 러너를 태그가 있는 작업 또는 태그가 없는 작업으로 실행하도록 설정합니다:
   • 태그가 있는 작업을 실행하려면 태그 필드에 쉼표로 구분된 작업 태그를 입력합니다. 예: macos, rails.
   • 태그가 없는 작업을 실행하려면 태그 없는 작업 실행 확인란을 선택합니다.
5. 변경 사항 저장을 선택합니다.

그룹 러너의 경우

전제 조건:

• 그룹의 소유자 역할이 있어야 합니다.

최대 작업 시간을 설정하려면:

1. 왼쪽 사이드바에서 검색 또는 포커스를 선택하고 그룹을 찾습니다.
2. 빌드 > Runners를 선택합니다.
3. 편집하려는 러너 오른쪽에서 편집({연필})을 선택합니다.
4. 러너를 태그가 있는 작업 또는 태그가 없는 작업으로 실행하도록 설정합니다:
   • 태그가 있는 작업을 실행하려면 태그 필드에 쉼표로 구분된 작업 태그를 입력합니다. 예: macos, ruby.
   • 태그가 없는 작업을 실행하려면 태그 없는 작업 실행 확인란을 선택합니다.
5. 변경 사항 저장을 선택합니다.

프로젝트 러너의 경우

전제 조건:

• 프로젝트의 소유자 역할이 있어야 합니다.

태그가 있는 작업을 실행하도록 러너를 설정하려면:

1. 왼쪽 사이드바에서 검색 또는 포커스를 선택하고 프로젝트를 찾습니다.
2. 설정 > CI/CD를 선택합니다.
3. Runners를 확장합니다.
4. 편집하려는 러너 오른쪽에서 편집({연필})을 선택합니다.
5. 러너를 태그가 있는 작업 또는 태그가 없는 작업으로 실행하도록 설정합니다:
   • 태그가 있는 작업을 실행하려면 태그 필드에 쉼표로 구분된 작업 태그를 입력합니다. 예: macos, ruby.
   • 태그가 없는 작업을 실행하려면 태그 없는 작업 실행 확인란을 선택합니다.
6. 변경 사항 저장을 선택합니다.

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

러너가 태그가 지정된 작업만 실행

다음 예제는 러너가 태그가 지정된 작업만 실행하도록 설정된 경우의 잠재적인 영향을 설명합니다.

예제 1:

1. 러너는 태그가 지정된 작업만 실행하도록 구성되었으며 docker 태그가 있습니다.
2. hello 태그가 있는 작업이 실행되고 멈춥니다.

예제 2:

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

예제 3:

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

Runner는 태그가 없는 작업을 실행할 수 있습니다.

다음 예제는 Runner가 태그가 지정된 작업과 태그가 지정되지 않은 작업을 실행하도록 설정된 경우의 잠재적인 영향을 보여줍니다.

예제 1:

1. Runner는 태그가 정의되지 않은 작업을 실행하도록 구성되어 있으며 docker 태그를 가지고 있습니다.
2. 태그가 정의되지 않은 작업이 실행되고 실행됩니다.
3. 태그가 docker로 정의된 두 번째 작업이 실행되고 실행됩니다.

예제 2:

1. Runner는 태그가 정의되지 않은 작업을 실행하도록 구성되어 있으며 태그가 정의되지 않았습니다.
2. 태그가 정의되지 않은 작업이 실행되고 실행됩니다.
3. 태그가 docker로 정의된 두 번째 작업이 막혀 있습니다.

Runner와 작업에 여러 태그가 있는 경우

작업과 Runner를 일치시키는 선택 논리는 작업에서 정의된 tags 디렉터리에 기반합니다.

다음 예제는 Runner와 작업에 여러 태그가 있는 경우의 영향을 보여줍니다. Runner가 작업을 실행하기 위해 작업 스크립트 블록에 정의된 모든 태그를 가져야 합니다.

예제 1:

1. Runner는 [docker, shell, gpu] 태그로 구성되어 있습니다.
2. 작업에 [docker, shell, gpu] 태그가 있으며 실행되고 실행됩니다.

예제 2:

1. Runner는 [docker, shell, gpu] 태그로 구성되어 있습니다.
2. 작업에 [docker, shell] 태그가 있으며 실행되고 실행됩니다.

예제 3:

1. Runner는 [docker, shell] 태그로 구성되어 있습니다.
2. 작업에 [docker, shell, gpu] 태그가 있으며 실행되지 않습니다.

태그를 사용하여 다양한 플랫폼에서 작업 실행

태그를 사용하여 다른 플랫폼에서 다양한 작업을 실행할 수 있습니다. 예를 들어, osx를 태그로 가진 OS X Runner와 windows를 태그로 가진 Windows Runner가 있다면 각 플랫폼에서 작업을 실행할 수 있습니다.

.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 변수를 사용하여 동적 Runner를 선택하세요:

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

변수를 사용하여 Runner 동작 구성

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

• GIT_STRATEGY
• GIT_SUBMODULE_STRATEGY
• GIT_CHECKOUT
• GIT_CLEAN_FLAGS
• GIT_FETCH_EXTRA_FLAGS
• GIT_SUBMODULE_UPDATE_FLAGS
• GIT_SUBMODULE_FORCE_HTTPS
• GIT_DEPTH (shallow cloning)
• GIT_SUBMODULE_DEPTH
• GIT_CLONE_PATH (custom build directories)
• TRANSFER_METER_FREQUENCY (artifact/cache meter update frequency)
• ARTIFACT_COMPRESSION_LEVEL (artifact archiver compression level)
• CACHE_COMPRESSION_LEVEL (cache archiver compression level)
• CACHE_REQUEST_TIMEOUT (cache request timeout)

Kubernetes executor를 사용할 때 특정 단계를 실행하는 방법을 구성하기 위해 변수를 사용할 수도 있습니다.

Git Clean 플래그

GIT_CLEAN_FLAGS 변수는 소스를 확인한 후 git clean의 기본 동작을 제어하는 데 사용됩니다. 전역적으로 설정하거나 variables 섹션에서 작업별로 설정할 수 있습니다.

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 섹션에서 작업별로 설정할 수 있습니다.

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

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

• GIT_DEPTH.
• refspecc들의 디렉터리.
• 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 50  --prune

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

CI 작업에서 특정 서브모듈 동기화 또는 제외

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

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

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

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

   variables:
      GIT_SUBMODULE_PATHS: submoduleA submoduleB
  

• 특정 경로를 제외하는 경우:

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

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

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

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

• normal 또는 recursive로 설정된 경우 --init.
• recursive로 설정된 경우 --recursive.
• GIT_DEPTH. 아래의 기본값 참조.

Git은 인수 디렉터리에서 플래그의 마지막 발생을 존중하기 때문에 GIT_SUBMODULE_UPDATE_FLAGS에서 매뉴얼으로 제공하면 이러한 기본 플래그가 오버라이드됩니다.

이 변수를 사용하여 리포지터리에서 추적된 커밋 대신 최신 원격 HEAD를 가져오거나, 서브모듈을 여러 병렬 작업에서 가져와 체크아웃을 가속화할 수 있습니다:

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 50 --recursive --remote --jobs 4

서브모듈 URL을 HTTPS로 변경

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

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

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_FORCE_HTTPS: "true"

활성화되면, GitLab 러너는 작업을 실행하는 사용자의 권한을 사용하여 서브모듈을 복제하고 SSH 자격 증명이 필요하지 않습니다.

얕은 클론

GIT_DEPTH를 사용하여 가져오고 복제의 깊이를 지정할 수 있습니다. GIT_DEPTH는 리포지터리의 얕은 클론을 수행하며 클론을 크게 가속화할 수 있습니다. 큰 수의 커밋이나 오래된 대형 이진 파일이 있는 리포지터리에 유용합니다. 이 값은 git fetch 및 git clone으로 전달됩니다.

새롭게 생성된 프로젝트는 자동으로 기본 git depth 값이 50으로 설정됩니다.

depth가 1이고 작업 또는 재시도 작업이 대기 중인 경우에는 작업이 실패할 수 있습니다.

Git 가져오기 및 복제는 브랜치 이름과 같이 참조에 의해 기반을 둡니다. 따라서 러너는 특정 커밋 SHA를 클론할 수 없습니다. 대기중인 여러 작업이 있거나 이전 작업을 다시 시도하는 경우 테스트할 커밋은 클론된 Git 히스토리 내에 있어야 합니다. GIT_DEPTH 값을 너무 작게 설정하면 옛날 커밋을 실행할 수 없게 되어 작업 로그에 unresolved reference가 표시됩니다. 그렇다면 GIT_DEPTH 값을 다시 고려해야 합니다.

git describe에 의존하는 작업은 GIT_DEPTH가 설정된 경우 올바르게 작동하지 않을 수 있습니다. Git 히스토리의 일부만 있기 때문입니다.

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

variables:
  GIT_DEPTH: "3"

이것은 전역적으로 설정하거나 variables 섹션에서 작업별로 설정할 수 있습니다.

Git 서브모듈 깊이

• GitLab Runner 15.5에서 도입됨.

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

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 설정 및 실행자에 따라 달라집니다.

이는 runner의 구성에서 custom_build_dir가 활성화된 경우에만 사용할 수 있습니다.

동시성 처리

동시성이 1보다 큰 실행자는 실패로 이어질 수 있습니다. 작업 사이에 공유된다면 여러 작업이 동일한 디렉터리에서 작업할 수 있습니다.

Runner는 이러한 상황을 방지하지는 않습니다. 실행자 구성 요구 사항을 준수하는 것은 관리자 및 개발자에게 달려 있습니다.

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

• $CI_CONCURRENT_ID: 실행자 내에서 실행되는 모든 작업에 대한 고유 ID입니다.
• $CI_CONCURRENT_PROJECT_ID: 실행자 및 프로젝트 내에서 실행되는 모든 작업에 대한 고유 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가 확장되지 않기 때문에 실패로 이어집니다.

작업 단계 시도

실행 중인 작업이 다음 단계를 실행하려 시도하는 횟수를 설정할 수 있습니다.

기본값은 하나의 시도입니다.

예시:

variables:
  GET_SOURCES_ATTEMPTS: 3

이러한 값을 전역적으로 설정하거나 variables 섹션에서 작업별로 설정할 수 있습니다.

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

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

Artifact 및 캐시 설정

Artifact 및 캐시 설정은 artifact 및 캐시의 압축률을 제어합니다. 이러한 설정을 사용하여 작업에서 생성된 아카이브의 크기를 지정할 수 있습니다.

• 느린 네트워크에서는 작은 아카이브로 업로드하는 것이 빠를 수 있습니다.
• 대역폭과 저장 공간에 신경 쓰지 않는 빠른 네트워크에서는 아카이브가 더 크더라도 최고의 압축률을 사용하는 것이 더 빠를 수 있습니다.

GitLab Pages에서 HTTP Range requests를 제공하려면, artifact는 ARTIFACT_COMPRESSION_LEVEL: fastest 설정을 사용해야 하며, 이는 압축되지 않은 zip 아카이브만이 해당 기능을 지원하기 때문입니다.

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

단일 작업에 대한 캐시 업로드 및 다운로드의 최대 시간을 CACHE_REQUEST_TIMEOUT 설정으로 설정할 수 있습니다. 이 설정은 작업의 지속 시간을 상당히 늘리는 느린 캐시 업로드에 유용할 수 있습니다.

variables:
  # 2초마다 출력 업로드 및 다운로드 진행
  TRANSFER_METER_FREQUENCY: "2s"
  
  # 더 큰 아카이브를 생성하는 빠른 압축 사용
  ARTIFACT_COMPRESSION_LEVEL: "fast"
  
  # 압축하지 않은 캐시 사용
  CACHE_COMPRESSION_LEVEL: "fastest"
  
  # 캐시 업로드 및 다운로드의 최대 지속 시간 설정
  CACHE_REQUEST_TIMEOUT: 5

아티팩트 형태 검증 메타데이터

• GitLab Runner 15.1에서 도입됨.

러너(runner)는 모든 빌드 아티팩트에 대해 형태 검증 메타데이터를 생성하고 생성할 수 있습니다.

아티팩트 형태 검증 데이터를 활성화하려면 RUNNER_GENERATE_ARTIFACTS_METADATA 환경 변수를 true로 설정하세요. 이 변수를 전역 또는 개별 작업으로 설정할 수 있습니다:

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 attestation format의 spec 버전 0.1으로 생성됩니다. 러너는 또한 기본적으로 SLSA v0.2를 준수하는 명세를 생성합니다.

SLSA v1.0 명세에 참여하려면 .gitlab-ci.yml 파일에서 SLSA_PROVENANCE_SCHEMA_VERSION=v1 변수를 설정하세요. v0.2 명세는 폐기되며 GitLab 17.0에서 제거할 예정이며, v1.0 명세는 새로운 기본 형식이 될 예정입니다.

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

GitLab Runner가 생성할 수 있는 형태 검증 메타데이터의 예는 다음과 같습니다:

{
    "_type": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/v15.1.0/PROVENANCE.md",
    "subject": [
        {
            "name": "script.sh",
            "digest": {
                "sha256": "f5ae5ced234922eebe6461d32228ba8ab9c3d0c0f3983a3bef707e6e1a1ab52a"
            }
        }
    ],
    "predicateType": "https://slsa.dev/provenance/v0.2",
    "predicate": {
        "buildType": "https://gitlab.com/gitlab-org/gitlab-runner/-/blob/v15.1.0/PROVENANCE.md",
        "builder": {
            "id": "https://gitlab.com/ggeorgiev_gitlab/playground/-/runners/14811533"
        },
        "invocation": {
            "configSource": {
                "uri": "https://gitlab.com/ggeorgiev_gitlab/playground",
                "digest": {
                    "sha256": "f0582e2c9a16b5cc2cde90e8be8f1b50fd67c631"
                },
                "entryPoint": "whoami shell"
            },
            "environment": {
                "name": "local",
                "executor": "shell",
                "architecture": "amd64"
            },
            "parameters": {
                "CI_PIPELINE_ID": "",
                "CI_PIPELINE_URL": "",
                // 다른 모든 CI 변수 이름은 여기에 나열됩니다. 값은 비밀을 누설하지 않도록 항상 빈 문자열로 표시됩니다.
            }
        },
        "metadata": {
            "buildStartedOn": "2022-06-17T00:47:27+03:00",
            "buildFinishedOn": "2022-06-17T00:47:28+03:00",
            "completeness": {
                "parameters": true,
                "environment": true,
                "materials": false
            },
            "reproducible": false
        },
        "materials": []
    }
}

스테이징 디렉터리

• GitLab Runner 15.0에서 도입됨.

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

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

디렉터리를 변경하려면 CI 작업에서 변수로 ARCHIVER_STAGING_DIR를 설정하거나 러너 등록 시 러너 변수를 사용하세요 (gitlab register --env ARCHIVER_STAGING_DIR=<dir>).

지정한 디렉터리는 추출 전 아티팩트를 다운로드하는 위치로 사용됩니다. fastzip 아카이버를 사용하는 경우 이 위치는 아카이브를 만들 때도 스크래치 공간으로 사용됩니다.

성능 향상을 위해 fastzip 구성

• GitLab Runner 15.0에서 도입됨.

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

zip 아카이브의 파일은 순차적으로 추가됩니다. 이로 인해 동시 압축이 어려워집니다. fastzip은 이 제한을 우회하기 위해 파일을 먼저 디스크에 동시에 압축하고 그 결과를 순차적으로 zip 아카이브에 복사합니다.

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

FASTZIP_ARCHIVER_CONCURRENCY는 동시에 압축되는 파일 수를 제어합니다. 위에서 언급한 대로 이 설정은 사용되는 메모리와 임시 데이터의 양을 증가시킬 수 있지만 메모리 부담이 크므로 항상 최선의 설정이 아닐 수 있습니다. 기본값은 사용 가능한 CPU 수이지만, 메모리의 효과를 고려하면 항상 최선의 설정이 아닐 수 있습니다.

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