• 최대 작업 시간 설정
  • 인스턴스 러너의 경우
  • 그룹 러너의 경우
  • 프로젝트 러너의 경우
• 최대 작업 시간 작동 방식
• script 및 after_script 시간 제한 설정
• 민감한 정보 보호
• 긴 폴링 구성
  • 포크된 프로젝트에서 인스턴스 러너 사용
  • 프로젝트의 러너 등록 토큰 재설정(지원 중단)
• 인증 토큰 보안
  • 러너 인증 토큰 재설정
  • Runner 인증 토큰 자동으로 회전
• 러너가 민감한 정보를 드러내지 못하게 하기
  • 인스턴스 러너용
  • 그룹 러너용
  • 프로젝트 러너용
• 러너가 실행할 수 있는 작업 제어
  • 인스턴스 러너용
  • 그룹 러너용
  • 프로젝트 러너용
  • 러너가 태그를 사용하는 방법
    • 러너는 태그가 지정된 작업만 실행합니다
    • 러너가 태그 없이도 실행할 수 있습니다
    • 러너와 작업에 여러 태그가 있는 경우
  • 태그를 사용하여 다른 플랫폼에서 작업 실행
  • 태그에서 CI/CD 변수 사용
• 변수를 사용하여 러너 동작 구성
  • Git 전략
  • Git 서브모듈 전략
  • Git 체크아웃
  • Git 청소 플래그
  • Git fetch extra flags
  • CI 작업에서 특정 서브모듈 동기화 또는 제외하기
  • Git 서브모듈 업데이트 플래그
  • HTTPS로 서브모듈 URL 재작성
  • 얕은 복제
  • Git 서브모듈 깊이
  • 사용자 정의 빌드 디렉터리
    • 동시성 처리
    • 중첩 경로
  • 작업 스테이지 시도
• GitLab.com 인스턴스 러너에서 사용할 수 없는 시스템 호출
• 아티팩트 및 캐시 설정
• 아티팩트 출처 메타데이터
  • 원산지 메타데이터 형식
  • 스테이징 디렉터리
  • fastzip 구성하여 성능 향상

러너 구성하기

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

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

최대 작업 시간 설정

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

인스턴스 러너의 경우

사전 조건:

• 관리자 권한이 있어야 합니다.

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

최대 작업 시간 설정 방법:

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

그룹 러너의 경우

사전 조건:

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

최대 작업 시간 설정 방법:

1. 왼쪽 사이드바에서 찾아보기 또는 이동하여 그룹을 찾습니다.
2. Build > 러너를 선택합니다.
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가 오래 실행되더라도 아티팩트와 캐시를 업로드할 수 있도록 빠르게 종료되도록 시간 제한을 지정할 수 있습니다.

• 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:
    - "15분 또는 남은 작업 시간 중 짧은 시간까지 실행할 수 있습니다."
  after_script:
    - "10분 또는 남은 작업 시간 중 짧은 시간까지 실행할 수 있습니다."

job-artifact-upload-on-timeout:
  timeout: 1시간                           # 작업 시간 제한을 1시간으로 설정
  variables:
     RUNNER_SCRIPT_TIMEOUT: 50m         # 스크립트가 50분 동안만 실행되도록 설정
  script:
    - long-running-process > output.txt # 50분 후에 종료됩니다.

  artifacts: # 아티팩트는 대략 10분내에 업로드됩니다
    paths:
      - output.txt
    when: on_failure # 시간 초과 후에 스크립트 종료는 실패로 처리됩니다

민감한 정보 보호

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

특정 실행자가 작업을 실행하면 파일 시스템, 러너가 실행하는 코드, 러너 인증 토큰이 노출될 수 있습니다. 즉, 인스턴스 러너에서 작업을 실행하는 사용자는 러너에서 실행된 다른 사용자의 코드에 액세스할 수 있습니다. 러너 인증 토큰에 액세스 권한이 있는 사용자는 해당 토큰을 사용하여 러너를 복제하고 벡터 공격에서 거짓 작업을 제출할 수 있습니다. 자세한 내용은 보안 고려 사항을 참조하십시오.

긴 폴링 구성

작업 대기 시간과 GitLab 서버 부하를 줄이기 위해 긴 폴링을 구성하십시오.

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

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

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

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

• 포크된 프로젝트에서 사용 중지로 설정된 경우, 새 네임스페이스에서도 사용 중지로 설정되어야 합니다.
• 포크된 프로젝트에서 사용 중으로 설정된 경우, 새 네임스페이스에서도 사용 중으로 설정되어야 합니다.

프로젝트의 러너 등록 토큰 재설정(지원 중단)

경고: 러너 등록 토큰 전달 및 특정 구성 인수 지원이 GitLab 15.6에서 지원이 중단됐으며 GitLab 17.0에서 삭제될 예정입니다. 인증 토큰을 대신 사용해야 합니다. 자세한 내용은 새 러너 등록 워크플로로의 이전을 참조하십시오.

프로젝트의 등록 토큰이 노출된 것으로 생각하면 토큰을 재설정해야 합니다. 등록 토큰을 사용하여 프로젝트에 다른 러너를 등록할 수 있습니다. 그런 다음 새 러너를 사용하여 비밀 변수의 값 또는 프로젝트 코드를 복제할 수 있습니다.

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

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 인스턴스와 연결하기 위한 러너 인증 토큰이 있습니다.

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

수동 개입이 필요하지 않으며 실행 중인 작업에는 영향을 주지 않아야 합니다.

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

러너 인증 토큰 재설정

러너 인증 토큰이 노출된 경우 공격자가 해당 토큰을 사용하여 러너를 클론할 수 있습니다.

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

1. 러너를 삭제합니다:
   • 인스턴스 러너 삭제.
   • 그룹 러너 삭제.
   • 프로젝트 러너 삭제.
2. 새 러너를 생성하여 새 러너 인증 토큰이 할당되도록 합니다:
   • 인스턴스 러너 생성.
   • 그룹 러너 생성.
   • 프로젝트 러너 생성.
3. (옵션) 이전 러너 인증 토큰이 취소됐는지 확인하려면 러너 API를 사용하십시오.

Runner 인증 토큰 자동으로 회전

Runner 인증 토큰의 회전 주기를 지정할 수 있습니다. 이 회전은 당신의 러너에 할당된 토큰들의 보안을 보장하는 데 도움이 됩니다.

필수 조건:

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

러너 인증 토큰을 자동으로 회전하려면 다음을 수행하세요:

1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리자 영역을 선택합니다.
2. 설정 > CI/CD를 선택합니다.
3. 지속적 통합 및 배포(CI/CD)를 확장합니다.
4. 러너의 만료 시간을 설정하고, 만료 기간이 없을 경우에는 비워둡니다.
5. 변경사항 저장을 선택합니다.

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

러너가 민감한 정보를 드러내지 못하게 하기

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

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

인스턴스 러너용

필수 조건:

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

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

그룹 러너용

필수 조건:

• 당신은 그룹의 소유자 역할을 가져야 합니다.

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 그룹을 찾습니다.
2. Build > 러너를 선택합니다.
3. 보호하려는 러너 옆에 있는 편집 ()을 선택합니다.
4. 보호됨 확인란을 선택합니다.
5. 변경사항 저장을 선택합니다.

프로젝트 러너용

필수 조건:

• 당신은 프로젝트의 소유자 역할을 가져야 합니다.

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
2. 설정 > CI/CD를 선택합니다.
3. 런너를 확장합니다.
4. 보호하려는 러너 옆에 있는 편집 ()을 선택합니다.
5. 보호됨 확인란을 선택합니다.
6. 변경사항 저장을 선택합니다.

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

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

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

인스턴스 러너용

필수 조건:

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

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

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

그룹 러너용

필수 조건:

• 당신은 그룹의 소유자 역할을 가져야 합니다.

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

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 그룹을 찾습니다.
2. Build > 러너를 선택합니다.
3. 편집하려는 러너 옆에 있는 편집 ()을 선택합니다.
4. 러너를 태그가 지정된 작업이나 태그가 지정되지 않은 작업으로 실행하도록 설정하려면:
   • 태그가 지정된 작업을 실행하려면, 태그 필드에 쉼표로 구분된 작업 태그를 입력합니다. 예를 들어, macos, ruby.
   • 태그가 지정되지 않은 작업을 실행하려면, 태그가 지정되지 않은 작업 실행 확인란을 선택합니다.
5. 변경사항 저장을 선택합니다.

프로젝트 러너용

필수 조건:

• 당신은 프로젝트의 소유자 역할을 가져야 합니다.

태그가 지정된 작업으로 러너를 실행하도록 설정하려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
2. 설정 > CI/CD를 선택합니다.
3. 런너를 확장합니다.
4. 편집하려는 러너 옆에 있는 편집 ()을 선택합니다.
5. 러너를 태그가 지정된 작업이나 태그가 지정되지 않은 작업으로 실행하도록 설정하려면:
   • 태그가 지정된 작업을 실행하려면, 태그 필드에 쉼표로 구분된 작업 태그를 입력합니다. 예를 들어, macos, ruby.
   • 태그가 지정되지 않은 작업을 실행하려면, 태그가 지정되지 않은 작업 실행 확인란을 선택합니다.
6. 변경사항 저장을 선택합니다.

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

러너는 태그가 지정된 작업만 실행합니다

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

예시 1:

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

예시 2:

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

예시 3:

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

러너가 태그 없이도 실행할 수 있습니다

다음 예시는 러너가 태그가 지정된 작업과 태그가 지정되지 않은 작업을 실행할 수 있는 경우의 잠재적인 영향을 보여줍니다.

예시 1:

1. 러너는 태그가 지정되지 않은 작업만 실행할 수 있도록 설정되어 있으며 docker 태그를 가지고 있습니다.
2. 태그가 정의되지 않은 작업이 실행되고 실행됩니다.
3. 두 번째 작업은 docker 태그가 정의되어 있어 실행되고 실행됩니다.

예시 2:

1. 러너는 태그가 지정되지 않은 작업만 실행할 수 있도록 설정되어 있으며 태그가 정의되어 있지 않습니다.
2. 태그가 정의되지 않은 작업이 실행되고 실행됩니다.
3. 두 번째 작업은 docker 태그가 정의되어 있어 멈춥니다.

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

작업과 러너를 일치시키는 선택 로직은 작업에 정의된 tags 목록을 기반으로 합니다.

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

예시 1:

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

예시 2:

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

예시 3:

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

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

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

config.toml의 tags 필드를 업데이트하세요:

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

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

태그에서 CI/CD 변수 사용

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

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

variables:
  KUBERNETES_RUNNER: kubernetes

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

변수를 사용하여 러너 동작 구성

전역적이거나 개별 작업을 위해 CI/CD 변수를 사용하여 러너 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를 사용할 때, 변수를 사용하여 요청 및 제한을 위한 Kubernetes CPU 및 메모리 할당을 덮어쓸 수 있습니다.

Git 전략

리포지토리 컨텐츠를 가져오는 데 사용되는 GIT_STRATEGY를 전역적으로 설정하거나 variables 섹션에서 작업별로 설정할 수 있습니다:

variables:
  GIT_STRATEGY: clone

가능한 값은 clone, fetch, none 세 가지입니다. 지정되지 않은 경우 작업은 프로젝트의 파이프라인 설정을 사용합니다.

clone은 가장 느린 옵션입니다. 매 작업마다 리포지토리를 클론하여 로컬 작업 복사본이 항상 원래 그대로 유지되도록 합니다. 기존의 작업트리가 발견되면 클론하기 전에 제거됩니다.

fetch는 로컬 작업 복사본을 재사용하여 빠릅니다 (clone이 존재하지 않는 경우 clone으로 되돌립니다). git clean은 마지막 작업에 의해 생긴 모든 변경을 되돌리는 데 사용되고, git fetch는 마지막 작업 이후에 만들어진 커밋을 검색하는 데 사용됩니다.

그러나 fetch는 이전 작업트리에 액세스를 필요로 합니다. 이 작업은 shell 또는 docker 실행자를 사용할 때 잘 작동합니다. 이 실행자들은 작업트리를 보존하려고 시도하고 기본적으로 재사용합니다.

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

none의 Git 전략은 로컬 작업 복사본을 재사용하지만 GitLab이 보통 하는 모든 Git 작업을 건너뜁니다. GitLab Runner 사전 클론 스크립트도 제거됩니다. 이 전략은 당신의 .gitlab-ci.yml 스크립트에 fetch와 checkout 명령어를 추가해야 할 수 있음을 의미할 수 있습니다.

이 기능은 배포 작업과 같이 오로지 아티팩트에 작용하는 작업에 사용될 수 있습니다. Git 리포지토리 데이터는 존재할 수 있지만 가능한 오래된 상태일 것입니다. 로컬 작업 복사본으로부터 가져온 파일에만 의존해야 합니다.

Git 서브모듈 전략

GIT_SUBMODULE_STRATEGY 변수는 빌드 전 코드를 가져올 때 Git 서브모듈을 포함할지 어떻게 제어할지를 설정하는 데 사용됩니다. 전역적으로 설정하거나 variables 섹션에서 작업별로 설정할 수 있습니다.

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

• none은 프로젝트 코드를 가져올 때 서브모듈을 포함하지 않는다는 것을 의미합니다. 이것이 기본값으로 v1.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
  

이 기능이 올바른 동작을 위해서는 서브모듈이 공개적으로 접근 가능한 리포지토리의 HTTP(S) URL 또는 GitLab 서버의 다른 리포지토리로의 상대경로로 (.gitmodules에서) 구성되어야 합니다. 자세한 내용은 Git 서브모듈 문서를 참조하세요.

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

Git 체크아웃

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

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 청소 플래그

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

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

만약 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 extra flags

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

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

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

• GIT_DEPTH.
• refspecs 목록.
• 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 clone <repo> --recurse-submodules=':(exclude)nested-submodule'과 같이 수행합니다. YAML이 성공적으로 구문 분석될 수 있도록 문자열을 반드시 작은따옴표로 감싸야 합니다.

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 플래그는 몇 가지 기본 플래그 뒤에 추가됩니다:

• --init, 만약 GIT_SUBMODULE_STRATEGY가 normal 또는 recursive로 설정되었을 경우.
• --recursive, 만약 GIT_SUBMODULE_STRATEGY가 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

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

HTTPS로 서브모듈 URL 재작성

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

GIT_SUBMODULE_FORCE_HTTPS 변수를 사용하여 모든 Git 및 SSH 서브모듈 URL을 HTTPS로 재작성할 수 있습니다. 그렇게 함으로써 동일한 GitLab 인스턴스에서 절대 URL을 사용하는 서브모듈을 복제할 수 있게 되며, 이는 서브모듈이 Git 또는 SSH 프로토콜로 구성되었더라도 가능해집니다.

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_FORCE_HTTPS: "true"

활성화된 경우, GitLab Runner는 CI/CD 작업 토큰을 사용하여 작업을 실행하는 사용자의 권한으로 서브모듈을 복제하며 SSH 자격 증명이 필요하지 않습니다.

얕은 복제

GIT_DEPTH를 사용하여 가져오고 복제하는 깊이를 지정할 수 있습니다. GIT_DEPTH는 저장소의 얕은 복제를 수행하며 복제 속도를 크게 향상시킬 수 있습니다. 커밋 수가 많거나 오래된 대형 이진 파일이 있는 저장소의 경우 유용할 수 있습니다. 해당 값은 git fetch와 git clone로 전달됩니다.

새로 생성된 프로젝트에는 기본 git depth 값으로 50이 설정됩니다(../pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone).

1의 깊이를 사용하고 작업 대기열이나 재시도 작업이 있는 경우 작업이 실패할 수 있습니다.

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

GIT_DEPTH가 설정된 경우 git describe에 의존하는 작업이 올바르게 작동하지 않을 수 있습니다.

마지막 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 변수를 지정하여 runner에게 저장소를 복제할 디렉토리를 알려줄 수 있습니다:

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보다 큰 실행자는 실패로 이어질 수 있습니다. builds_dir가 작업 간에 공유되는 경우 여러 작업이 동일한 디렉토리에서 작동할 수 있습니다.

러너는 이러한 상황을 방지하려고 시도하지 않습니다. 실행자 구성 요구 사항을 준수하는 것은 운영자 및 개발자의 책임입니다.

이러한 시나리오를 피하려면 고유한 경로를 $CI_BUILDS_DIR 내에 사용할 수 있으며, 이는 실행자 내에서 모든 작업에 대한 고유한 ID를 제공하는 두 가지 추가 변수를 러너가 노출합니다:

• $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이 확장되지 않아 실패합니다.

작업 스테이지 시도

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

기본값은 1회 시도입니다.

예시:

variables:
  GET_SOURCES_ATTEMPTS: 3

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

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

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

아티팩트 및 캐시 설정

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

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

GitLab Pages에서 HTTP Range requests을 제공하려면 아티팩트는 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에서 소개됨.

참고: zip 아카이브가 유일하게 지원되는 아티팩트 유형입니다. 자세한 내용은 이슈를 참조하세요.

러너는 모든 빌드 아티팩트에 대한 출처 메타데이터를 생성하고 제공할 수 있습니다.

아티팩트 출처 데이터를 활성화하려면 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 version 0.1으로 생성됩니다. 러너는 기본적으로 SLSA v0.2를 준수하는 문을 생성합니다.

SLSA v1.0 문을 선택하려면 .gitlab-ci.yml 파일에서 SLSA_PROVENANCE_SCHEMA_VERSION=v1 변수를 설정하세요. v0.2 문은 폐기되었으며 GitLab 17.0에서 제거될 예정이며 v1.0 문은 새로운 기본 형식이 될 예정입니다.

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

GitLab 러너가 생성할 원산지 메타데이터의 예는 다음과 같습니다:

{
    "_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로 제어할 수 있습니다. 이 버퍼의 기본 크기는 2MiB이며, 따라서 16개의 동시성은 32MiB를 할당합니다. 버퍼 크기를 초과하는 데이터는 디스크에 쓰여서 다시 읽혀집니다. 그러므로 버퍼 없이, FASTZIP_ARCHIVER_BUFFER_SIZE: 0를 사용하고 오직 스크래치 공간만 사용하는 것도 유효한 옵션입니다.

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

FASTZIP_EXTRACTOR_CONCURRENCY는 동시에 한 번에 압축을 해제할 파일 수를 제어합니다. zip 아카이브의 파일은 기본적으로 동시에 읽을 수 있으므로, 이를 위해 더 많은 메모리가 필요하지 않습니다. 이것은 기본적으로 사용 가능한 CPU 수로 설정됩니다.