러너(Runner) 구성하기

러너(Runner) 구성하기 (Configuring runners)

GitLab UI에서 러너를 어떻게 구성하는지 설명할게요. GitLab Runner를 설치한 머신에서 구성해야 한다면 GitLab Runner 문서를 참고하세요.

출처: 문서

본문

티어(Tier): Free, Premium, Ultimate
제공 방식(Offering): GitLab.com, GitLab Self-Managed, GitLab Dedicated

최대 job 타임아웃 설정하기

러너마다 최대 job 타임아웃을 지정하면, 긴 job 타임아웃을 가진 프로젝트가 그 러너를 사용하지 못하게 막을 수 있어요. 최대 job 타임아웃은 프로젝트에 정의된 job 타임아웃보다 짧을 때 적용됩니다:

러너 타임아웃	프로젝트 타임아웃	job이 타임아웃되는 시점
24시간	2시간	2시간
구성 안 됨	2시간	2시간
30분	2시간	30분

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

인스턴스 러너

전제 조건:

관리자여야 해요.

GitLab Self-Managed에서는 인스턴스 러너의 job 타임아웃을 재정의할 수 있어요.

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

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

오른쪽 위에서 Admin을 선택해요.
왼쪽 사이드바에서 CI/CD > Runners를 선택해요.
편집할 러너 오른쪽에서 Edit(연필)을 선택해요.
Maximum job timeout 필드에 초 단위 값을 입력해요. 최소값은 600초(10분)예요.
Save changes를 선택해요.

그룹 러너

전제 조건:

그룹의 Owner 역할이 있어야 해요.

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

상단 바에서 Search or go to를 선택하고 그룹을 찾아요.
왼쪽 사이드바에서 Build > Runners를 선택해요.
편집할 러너 오른쪽에서 Edit(연필)을 선택해요.
Maximum job timeout 필드에 초 단위 값을 입력해요. 최소값은 600초(10분)예요.
Save changes를 선택해요.

프로젝트 러너

전제 조건:

프로젝트의 Owner 역할이 있어야 해요.

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾아요.
왼쪽 사이드바에서 Settings > CI/CD를 선택해요.
Runners를 펼쳐요.
편집할 러너 오른쪽에서 Edit(연필)을 선택해요.
Maximum job timeout 필드에 초 단위 값을 입력해요. 최소값은 600초(10분)예요. 정의되지 않으면 프로젝트의 job 타임아웃이 대신 사용됩니다.
Save changes를 선택해요.

`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                           # set job timeout to 1 hour
  variables:
     RUNNER_SCRIPT_TIMEOUT: 50m         # only allow script to run for 50 minutes
  script:
    - long-running-process > output.txt # will be terminated after 50m

  artifacts: # artifacts will have roughly ~10m to upload
    paths:
      - output.txt
    when: on_failure # on_failure because script termination after a timeout is treated as a failure

`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 # Wait 2 minutes to trigger timeout. Script aborts after 1 minute due to RUNNER_SCRIPT_TIMEOUT.
    - echo "Build finished."
  after_script:
    - echo "Starting Clean-up..."
    - sleep 15 # Wait just a few seconds. Runs successfully because it's within RUNNER_AFTER_SCRIPT_TIMEOUT.
    - echo "Clean-up finished."

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

민감한 정보 보호하기

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

롱 폴링(long polling) 구성하기

job 대기열 시간과 GitLab 서버 부하를 줄이려면 long polling을 구성하세요.

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

프로젝트가 포크되면 job 설정이 복사돼요. 프로젝트에 인스턴스 러너가 구성되어 있고 사용자가 그 프로젝트를 포크하면, 인스턴스 러너가 그 프로젝트의 job을 처리합니다.

알려진 이슈 때문에, 포크된 프로젝트의 러너 설정이 새 프로젝트 네임스페이스와 일치하지 않으면 An error occurred while forking the project. Please try again. 메시지가 표시돼요.

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

포크된 프로젝트에서 인스턴스 러너가 활성화되어 있다면 새 네임스페이스에서도 활성화해야 해요.
포크된 프로젝트에서 인스턴스 러너가 비활성화되어 있다면 새 네임스페이스에서도 비활성화해야 해요.

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

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

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

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾아요.
왼쪽 사이드바에서 Settings > CI/CD를 선택해요.
Runners를 펼쳐요.
New project runner 오른쪽에서 세로 줄임표(ellipsis_v)를 선택해요.
Reset registration token을 선택해요.
Reset token을 선택해요.

등록 토큰을 초기화한 후에는 더 이상 유효하지 않으며 프로젝트에 새 러너를 등록하지 않아요. 새 값을 프로비저닝·등록하는 데 사용하는 도구의 등록 토큰도 업데이트해야 해요.

인증 토큰 보안

각 러너는 러너 인증 토큰으로 GitLab 인스턴스에 연결하고 인증해요.

토큰이 손상되는 것을 막기 위해 지정된 간격으로 토큰을 자동 회전하게 할 수 있어요. 토큰이 회전되면 러너의 상태(online 또는 offline)와 무관하게 각 러너에 대해 업데이트됩니다.

수동 개입이 필요하지 않아야 하고 실행 중인 job에 영향이 없어야 해요. 토큰 회전에 대한 자세한 내용은 러너 인증 토큰이 회전 시 업데이트되지 않음 문서를 참고하세요.

변수로 러너 동작 구성하기

러너는 다양한 환경 변수로 동작을 조정할 수 있어요. 주요 항목은 다음과 같아요:

Git strategy: job이 리포지토리를 가져오는 방식. git clone은 매 job마다 처음부터 복제하고, git fetch는 기존 작업 복사본을 재사용해서 더 빨라요.
Git submodule strategy: 서브모듈의 가져오기 방식을 제어.
Git checkout / clean flags / fetch extra flags / clone extra flags: Git 작업의 세부 동작 조정.
Shallow cloning / depth: 가져올 변경 수 제한.
Custom build directories: 사용자 지정 빌드 디렉터리.
Job stages attempts: 스테이지별 재시도 횟수.
Artifact and cache settings: 아티팩트와 캐시 동작 구성(예: 고지연 연결을 위한 TCP 설정).

이 외에도 GitLab 문서에는 아티팩트 출처 메타데이터, 스테이징 디렉터리, 성능 개선을 위한 fastzip 구성 등 더 많은 항목이 다뤄져요. 자세한 내용은 원문 문서를 참고하세요.

러너(Runner) 구성하기