러너 관리하기

러너 관리하기 (Manage runners)

GitLab Runner에는 누구에게 액세스를 허용할지에 따라 사용할 수 있는 다음 유형의 러너가 있어요:

  • 인스턴스 러너는 GitLab 인스턴스의 모든 그룹과 프로젝트에서 사용할 수 있어요.
  • 그룹 러너는 그룹의 모든 프로젝트와 하위 그룹에서 사용할 수 있어요.
  • 프로젝트 러너는 특정 프로젝트와 연결돼요. 보통 프로젝트 러너는 한 번에 하나의 프로젝트에서 사용돼요.

출처: 문서

본문

인스턴스 러너 (Instance runners)

인스턴스 러너는 GitLab 인스턴스의 모든 프로젝트에서 사용할 수 있어요.

비슷한 요구사항을 가진 여러 잡이 있을 때 인스턴스 러너를 사용하세요. 여러 프로젝트마다 러너를 두고 유휴 상태로 두는 대신, 소수의 러너가 여러 프로젝트를 처리하게 할 수 있어요.

GitLab Self-Managed를 사용한다면 관리자는:

GitLab.com을 사용한다면:

러너 인증 토큰으로 인스턴스 러너 만들기

전제 조건:

  • 관리자여야 해요.

러너를 만들면 등록에 사용할 러너 인증 토큰이 할당돼요. 러너는 잡 큐에서 잡을 가져올 때 이 토큰으로 GitLab에 인증해요.

인스턴스 러너를 만들려면:

  1. 오른쪽 위에서 Admin을 선택하세요.
  2. 왼쪽 사이드바에서 CI/CD > Runners를 선택하세요.
  3. Create instance runner를 선택하세요.
  4. GitLab Runner가 설치된 운영체제를 선택하세요.
  5. Tags 섹션의 Tags 필드에 러너가 실행할 수 있는 잡을 지정하는 잡 태그를 입력하세요. 이 러너의 잡 태그가 없다면 Run untagged를 선택하세요.
  6. 선택 사항. Runner description 필드에 GitLab에 표시될 러너 설명을 입력하세요.
  7. 선택 사항. Configuration 섹션에서 추가 구성을 추가하세요.
  8. Create runner를 선택하세요.
  9. 화면의 안내에 따라 명령줄에서 러너를 등록하세요. 명령줄에서 요청하면:GitLab instance URL에는 GitLab 인스턴스의 URL을 사용하세요. 예를 들어 프로젝트가 gitlab.example.com/yourname/yourproject에 호스팅되어 있다면 GitLab 인스턴스 URL은 https://gitlab.example.com이에요.executor에는 executor 유형을 입력하세요. executor는 러너가 잡을 실행하는 환경이에요.

API를 사용해 러너를 만들 수도 있어요.

러너 인증 토큰은 등록 중에 제한된 시간 동안만 UI에 표시돼요. 러너를 등록한 후에는 인증 토큰이 config.toml에 저장돼요.

등록 토큰으로 인스턴스 러너 만들기 (더 이상 사용되지 않음)

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

전제 조건:

  • 러너 등록 토큰이 Admin 영역에서 활성화되어 있어야 해요.
  • 관리자여야 해요.

인스턴스 러너를 만들려면:

  1. 오른쪽 위에서 Admin을 선택하세요.
  2. 왼쪽 사이드바에서 CI/CD > Runners를 선택하세요.
  3. Register an instance runner를 선택하세요.
  4. 등록 토큰을 복사하세요.
  5. 러너를 등록하세요.

인스턴스 러너 일시 중지 또는 재개하기

전제 조건:

  • 관리자여야 해요.

GitLab 인스턴스의 그룹과 프로젝트에서 잡을 받지 않도록 러너를 일시 중지할 수 있어요.

  1. 오른쪽 위에서 Admin을 선택하세요.
  2. 왼쪽 사이드바에서 CI/CD > Runners를 선택하세요.
  3. 검색 상자에 러너 설명을 입력하거나 러너 목록을 필터링하세요.
  4. 러너 목록에서 러너 오른쪽에:러너를 일시 중지하려면 Pause ( pause )를 선택하세요.러너를 재개하려면 Resume ( play )를 선택하세요.

인스턴스 러너 삭제하기

전제 조건:

  • 관리자여야 해요.

인스턴스 러너를 삭제하면 GitLab 인스턴스에서 영구 삭제되며 그룹과 프로젝트가 더 이상 사용할 수 없어요. 러너가 잡을 받지 못하도록 일시적으로 멈추고 싶다면 러너를 일시 중지하면 돼요.

인스턴스 러너 하나 또는 여러 개를 삭제하려면:

  1. 오른쪽 위에서 Admin을 선택하세요.
  2. 왼쪽 사이드바에서 CI/CD > Runners를 선택하세요.
  3. 검색 상자에 러너 설명을 입력하거나 러너 목록을 필터링하세요.
  4. 인스턴스 러너를 삭제하세요:러너 하나를 삭제하려면 러너 옆에서 Delete runner ( remove )를 선택하세요.여러 인스턴스 러너를 삭제하려면 각 러너의 체크박스를 선택하고 Delete selected를 선택하세요.모든 러너를 삭제하려면 러너 목록 맨 위의 체크박스를 선택하고 Delete selected를 선택하세요.
  5. Permanently delete runner를 선택하세요.

프로젝트에서 인스턴스 러너 활성화하기

GitLab.com에서는 인스턴스 러너가 기본적으로 모든 프로젝트에서 활성화돼요.

GitLab Self-Managed에서 관리자는 모든 새 프로젝트에 대해 인스턴스 러너를 활성화할 수 있어요.

기존 프로젝트의 경우 관리자가 설치하고 등록해야 해요.

프로젝트에서 인스턴스 러너를 활성화하려면:

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Turn on instance runners for this project 토글을 활성화하세요.

그룹에서 인스턴스 러너 활성화하기

그룹에서 인스턴스 러너를 활성화하려면:

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Turn on instance runners for this group 토글을 활성화하세요.

프로젝트에서 인스턴스 러너 비활성화하기

개별 프로젝트나 그룹에 대해 인스턴스 러너를 비활성화할 수 있어요. 프로젝트나 그룹의 Owner 역할이 있어야 해요.

프로젝트에서 인스턴스 러너를 비활성화하려면:

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Instance runners 영역에서 Turn on runners for this project 토글을 끄세요.

인스턴스 러너는 다음과 같은 경우 프로젝트에서 자동으로 비활성화돼요:

  • 상위 그룹의 인스턴스 러너 설정이 비활성화되어 있고,
  • 프로젝트가 이 설정을 재정의하는 것이 허용되지 않는 경우.

그룹에서 인스턴스 러너 비활성화하기

그룹에서 인스턴스 러너를 비활성화하려면:

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Enable instance runners for this group 토글을 끄세요.
  5. 선택 사항. 개별 프로젝트나 하위 그룹이 인스턴스 러너를 활성화할 수 있게 하려면 Allow projects and subgroups to override the group setting을 선택하세요.

인스턴스 러너가 잡을 선택하는 방식

인스턴스 러너는 공정 사용 큐(fair usage queue)로 잡을 처리해요. 이 큐는 프로젝트가 수백 개의 잡을 만들어 인스턴스 러너 리소스를 모두 사용하는 것을 방지해요.

공정 사용 큐 알고리즘은 인스턴스 러너에서 이미 실행 중인 잡 수가 가장 적은 프로젝트를 기준으로 잡을 할당해요.

예를 들어 큐에 이 잡들이 있다면:

  • 프로젝트 1의 잡 1
  • 프로젝트 1의 잡 2
  • 프로젝트 1의 잡 3
  • 프로젝트 2의 잡 4
  • 프로젝트 2의 잡 5
  • 프로젝트 3의 잡 6

여러 CI/CD 잡이 동시에 실행될 때 공정 사용 알고리즘은 이 순서로 잡을 할당해요:

  1. 잡 1이 먼저예요. 실행 중인 잡이 없는 프로젝트(즉, 모든 프로젝트) 중에서 잡 번호가 가장 낮기 때문이에요.
  2. 잡 4가 다음이에요. 잡 1이 실행 중인 프로젝트를 제외하고, 실행 중인 잡이 없는 프로젝트 중에서 4가 이제 가장 낮은 잡 번호이기 때문이에요.
  3. 잡 6이 다음이에요. 잡 1·2가 실행 중인 프로젝트를 제외하면 6이 이제 실행 중인 잡이 없는 프로젝트 중에서 가장 낮은 잡 번호이기 때문이에요.
  4. 잡 2가 다음이에요. 실행 중인 잡 수가 가장 낮은 프로젝트(각각 1개) 중에서 가장 낮은 잡 번호이기 때문이에요.
  5. 잡 5가 다음이에요. 프로젝트 1은 이제 2개의 잡이 실행 중이고, 잡 5는 프로젝트 2와 3 사이에서 남은 가장 낮은 잡 번호이기 때문이에요.
  6. 마지막으로 잡 3이 다음이에요. 남은 유일한 잡이기 때문이에요.

한 번에 하나의 잡만 실행될 때 공정 사용 알고리즘은 이 순서로 잡을 할당해요:

  1. 잡 1을 먼저 선택해요. 실행 중인 잡이 없는 프로젝트(즉, 모든 프로젝트) 중에서 잡 번호가 가장 낮기 때문이에요.
  2. 잡 1이 끝나요.
  3. 잡 2가 다음이에요. 잡 1이 끝나 모든 프로젝트가 다시 0개 잡을 실행하게 되었고, 2가 사용 가능한 가장 낮은 잡 번호이기 때문이에요.
  4. 잡 4가 다음이에요. 프로젝트 1이 잡 하나를 실행 중이므로, 4가 잡을 실행하지 않는 프로젝트(프로젝트 2, 3) 중에서 가장 낮은 번호이기 때문이에요.
  5. 잡 4가 끝나요.
  6. 잡 5가 다음이에요. 잡 4가 끝나 프로젝트 2가 다시 잡을 실행하지 않기 때문이에요.
  7. 잡 6이 다음이에요. 프로젝트 3이 실행 중인 잡이 없는 유일한 프로젝트이기 때문이에요.
  8. 마지막으로 잡 3이 다음이에요. 남은 유일한 잡이기 때문이에요.

그룹 러너 (Group runners)

그룹의 모든 프로젝트가 러너 세트에 액세스하길 원할 때 그룹 러너를 사용하세요.

그룹 러너는 선입선출(first in, first out) 큐로 잡을 처리해요.

러너 인증 토큰으로 그룹 러너 만들기

전제 조건:

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

GitLab Self-Managed 또는 GitLab.com용 그룹 러너를 만들 수 있어요. 러너를 만들면 등록에 사용할 러너 인증 토큰이 할당돼요. 러너는 잡 큐에서 잡을 가져올 때 이 토큰으로 GitLab에 인증해요.

그룹 러너를 만들려면:

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Build > Runners를 선택하세요.
  3. Create group runner를 선택하세요.
  4. Tags 섹션의 Tags 필드에 러너가 실행할 수 있는 잡을 지정하는 잡 태그를 입력하세요. 이 러너의 잡 태그가 없다면 Run untagged를 선택하세요.
  5. 선택 사항. Runner description 필드에 GitLab에 표시될 러너 설명을 추가하세요.
  6. 선택 사항. Configuration 섹션에서 추가 구성을 추가하세요.
  7. Create runner를 선택하세요.
  8. GitLab Runner가 설치된 플랫폼을 선택하세요.
  9. 화면의 안내를 완료하세요:Linux, macOS, Windows의 경우 명령줄에서 요청하면:GitLab instance URL에는 GitLab 인스턴스의 URL을 사용하세요. 예를 들어 프로젝트가 gitlab.example.com/yourname/yourproject에 호스팅되어 있다면 GitLab 인스턴스 URL은 https://gitlab.example.com이에요.executor에는 executor 유형을 입력하세요. executor는 러너가 잡을 실행하는 환경이에요.Google Cloud의 경우 Google Cloud에서 러너 프로비저닝을 참고하세요.

API를 사용해 러너를 만들 수도 있어요.

러너 인증 토큰은 등록 중에 잠시 동안만 UI에 표시돼요.

등록 토큰으로 그룹 러너 만들기 (더 이상 사용되지 않음)

  • 경로가 Settings > CI/CD > Runners에서 변경됐어요.

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

전제 조건:

  • 최상위 그룹에서 러너 등록 토큰이 활성화되어 있어야 해요.
  • 그룹의 Owner 역할이 있어야 해요.

그룹 러너를 만들려면:

  1. GitLab Runner 설치하기.
  2. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  3. 왼쪽 사이드바에서 Build > Runners를 선택하세요.
  4. 오른쪽 위에서 Register a group runner를 선택하세요.
  5. Show runner installation and registration instructions를 선택하세요. 이 지침에는 토큰, URL, 러너 등록 명령이 포함되어 있어요.

대신 등록 토큰을 복사하고 러너를 등록하는 방법 문서를 따라도 돼요.

그룹 러너 보기

전제 조건:

  • 그룹의 Maintainer 또는 Owner 역할이 있어야 해요.

그룹과 그 하위 그룹, 프로젝트의 모든 러너를 볼 수 있어요. GitLab Self-Managed와 GitLab.com 모두에서 가능해요.

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Build > Runners를 선택하세요.

상속된 그룹 러너만 표시하도록 필터링

목록의 모든 러너를 표시하거나 인스턴스나 다른 그룹에서 상속된 러너만 표시하도록 선택할 수 있어요.

기본적으로 상속된 러너만 표시돼요.

인스턴스 러너와 다른 그룹의 러너를 포함해 인스턴스에서 사용 가능한 모든 러너를 표시하려면:

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Build > Runners를 선택하세요.
  3. 목록 위에서 Show only inherited 토글을 끄세요.

그룹 러너 일시 중지 또는 재개하기

전제 조건:

  • 관리자이거나 그룹의 Owner 역할이 있어야 해요.

GitLab 인스턴스의 하위 그룹과 프로젝트에서 잡을 받지 않도록 러너를 일시 중지할 수 있어요. 여러 프로젝트가 사용하는 그룹 러너를 일시 중지하면 모든 프로젝트에 대해 러너가 일시 중지돼요.

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Build > Runners를 선택하세요.
  3. 검색 상자에 러너 설명을 입력하거나 러너 목록을 필터링하세요.
  4. 러너 목록에서 러너 오른쪽에:러너를 일시 중지하려면 Pause ( pause )를 선택하세요.러너를 재개하려면 Resume ( play )를 선택하세요.

그룹 러너 삭제하기

전제 조건:

  • 관리자이거나 그룹의 Owner 역할이 있어야 해요.

그룹 러너를 삭제하면 GitLab 인스턴스에서 영구 삭제되며 하위 그룹과 프로젝트가 더 이상 사용할 수 없어요. 러너가 잡을 받지 못하도록 일시적으로 멈추고 싶다면 러너를 일시 중지하면 돼요.

그룹 러너 하나 또는 여러 개를 삭제하려면:

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Build > Runners를 선택하세요.
  3. 검색 상자에 러너 설명을 입력하거나 러너 목록을 필터링하세요.
  4. 그룹 러너를 삭제하세요:러너 하나를 삭제하려면 러너 옆에서 Delete runner ( remove )를 선택하세요.여러 인스턴스 러너를 삭제하려면 각 러너의 체크박스를 선택하고 Delete selected를 선택하세요.모든 러너를 삭제하려면 러너 목록 맨 위의 체크박스를 선택하고 Delete selected를 선택하세요.
  5. Permanently delete runner를 선택하세요.

오래된 그룹 러너 정리하기

전제 조건:

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

7일 이상 비활성 상태인 그룹 러너를 정리할 수 있어요.

그룹 러너는 특정 그룹에서 생성된 러너를 말해요.

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Enable stale runner cleanup 토글을 켜세요.

오래된 러너 정리 로그 보기

정리 결과는 Sidekiq 로그에서 확인할 수 있어요. Kibana에서 다음 쿼리를 사용하세요:

{
  "query": {
    "match_phrase": {
      "json.class.keyword": "Ci::Runners::StaleGroupRunnersPruneCronWorker"
    }
  }
}

오래된 러너가 제거된 항목을 필터링하세요:

{
  "query": {
    "range": {
      "json.extra.ci_runners_stale_group_runners_prune_cron_worker.total_pruned": {
        "gte": 1,
        "lt": null
      }
    }
  }
}

프로젝트 러너 (Project runners)

특정 프로젝트에 러너를 사용하고 싶을 때 프로젝트 러너를 사용하세요. 예를 들어:

  • 자격 증명이 필요한 배포 잡처럼 특정 요구사항이 있는 잡.
  • CI 활동이 많아 다른 러너와 분리하는 게 유리한 프로젝트.

프로젝트 러너를 여러 프로젝트가 사용하도록 설정할 수 있어요. 프로젝트 러너는 각 프로젝트에서 명시적으로 활성화해야 해요.

프로젝트 러너는 선입선출(FIFO) 큐로 잡을 처리해요.

프로젝트 러너는 포크된 프로젝트에 자동으로 활성화되지 않아요. 포크는 클론된 저장소의 CI/CD 설정을 복사하기는 해요.

프로젝트 러너 소유권

러너가 처음 프로젝트에 연결되면 그 프로젝트가 러너의 소유자가 돼요.

소유자 프로젝트를 삭제하면:

  1. GitLab이 러너를 공유하는 다른 모든 프로젝트를 찾아요.
  2. GitLab이 가장 오래된 연결을 가진 프로젝트에 소유권을 할당해요.
  3. 다른 프로젝트가 러너를 공유하지 않는다면 GitLab이 러너를 자동으로 삭제해요.

소유자 프로젝트에서 러너를 할당 해제할 수는 없어요. 대신 러너를 삭제하세요.

러너 인증 토큰으로 프로젝트 러너 만들기

전제 조건:

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

GitLab Self-Managed 또는 GitLab.com용 프로젝트 러너를 만들 수 있어요. 러너를 만들면 등록에 사용할 러너 인증 토큰이 할당돼요. 러너는 잡 큐에서 잡을 가져올 때 이 토큰으로 GitLab에 인증해요.

프로젝트 러너를 만들려면:

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners 섹션을 확장하세요.
  4. Create project runner를 선택하세요.
  5. GitLab Runner가 설치된 운영체제를 선택하세요.
  6. Tags 섹션의 Tags 필드에 러너가 실행할 수 있는 잡을 지정하는 잡 태그를 입력하세요. 이 러너의 잡 태그가 없다면 Run untagged를 선택하세요.
  7. 선택 사항. Runner description 필드에 GitLab에 표시될 러너 설명을 추가하세요.
  8. 선택 사항. Configuration 섹션에서 추가 구성을 추가하세요.
  9. Create runner를 선택하세요.
  10. GitLab Runner가 설치된 플랫폼을 선택하세요.
  11. 화면의 안내를 완료하세요:Linux, macOS, Windows의 경우 명령줄에서 요청하면:GitLab instance URL에는 GitLab 인스턴스의 URL을 사용하세요. 예를 들어 프로젝트가 gitlab.example.com/yourname/yourproject에 호스팅되어 있다면 GitLab 인스턴스 URL은 https://gitlab.example.com이에요.executor에는 executor 유형을 입력하세요. executor는 러너가 잡을 실행하는 환경이에요.Google Cloud의 경우 Google Cloud에서 러너 프로비저닝을 참고하세요.

API를 사용해 러너를 만들 수도 있어요.

러너 인증 토큰은 등록 중에 잠시 동안만 UI에 표시돼요.

등록 토큰으로 프로젝트 러너 만들기 (더 이상 사용되지 않음)

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

전제 조건:

  • 최상위 그룹에서 러너 등록 토큰이 활성화되어 있어야 해요.
  • 프로젝트의 Maintainer 또는 Owner 역할이 있어야 해요.

프로젝트 러너를 만들려면:

  1. GitLab Runner 설치하기.
  2. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  3. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  4. Runners를 확장하세요.
  5. Project runners 섹션에서 URL과 토큰을 확인하세요.
  6. 러너를 등록하세요.

이제 러너가 프로젝트에 활성화됐어요.

프로젝트 러너 일시 중지 또는 재개하기

전제 조건:

  • 관리자이거나 프로젝트의 Maintainer 역할이 있어야 해요.

GitLab 인스턴스에서 할당된 프로젝트의 잡을 받지 않도록 프로젝트 러너를 일시 중지할 수 있어요.

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Assigned project runners 섹션에서 러너를 찾으세요.
  5. 러너 오른쪽에:러너를 일시 중지하려면 Pause ( pause )를 선택한 다음 Pause를 선택하세요.러너를 재개하려면 Resume ( play )을 선택하세요.

프로젝트 러너 삭제하기

전제 조건:

  • 관리자이거나 프로젝트의 Maintainer 역할이 있어야 해요.
  • 둘 이상의 프로젝트에 할당된 프로젝트 러너는 삭제할 수 없어요. 러너를 삭제하려면 활성화된 모든 프로젝트에서 먼저 비활성화해야 해요.

프로젝트 러너를 삭제하면 GitLab 인스턴스에서 영구 삭제되며 프로젝트가 더 이상 사용할 수 없어요. 러너가 잡을 받지 못하도록 일시적으로 멈추고 싶다면 러너를 일시 중지하면 돼요.

러너를 삭제해도 러너 호스트의 config.toml 파일에는 해당 구성이 여전히 존재해요. 삭제된 러너의 구성이 이 파일에 여전히 있다면 러너 호스트는 계속 GitLab에 연락해요. 불필요한 API 트래픽을 막으려면 삭제된 러너를 등록 해제해야 해요.

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Assigned project runners 섹션에서 러너를 찾으세요.
  5. 러너 오른쪽에서 Remove runner를 선택하세요.
  6. 러너를 삭제하려면 Remove를 선택하세요.

다른 프로젝트에서 프로젝트 러너 활성화하기

프로젝트 러너를 만든 후 다른 프로젝트에서 활성화할 수 있어요.

전제 조건: 다음에 대해 Maintainer 또는 Owner 역할이 있어야 해요:

  • 러너가 이미 활성화된 프로젝트.
  • 러너를 활성화할 프로젝트.
  • 프로젝트 러너가 잠겨(locked)있지 않아야 해요.

프로젝트에서 프로젝트 러너를 활성화하려면:

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Project runners 영역에서 원하는 러너 옆의 Enable for this project를 선택하세요.

활성화된 프로젝트 중 아무 곳에서나 프로젝트 러너를 편집할 수 있어요. 잠금 해제, 태그·설명 편집을 포함한 수정 사항은 러너를 사용하는 모든 프로젝트에 영향을 줘요.

관리자는 여러 프로젝트에서 러너를 활성화할 수 있어요.

프로젝트 러너가 다른 프로젝트에 활성화되는 것 방지하기

프로젝트 러너가 "잠겨" 다른 프로젝트에서 활성화될 수 없도록 구성할 수 있어요. 이 설정은 러너를 처음 등록할 때 활성화할 수 있고, 나중에 바꿀 수도 있어요.

프로젝트 러너를 잠그거나 잠금 해제하려면:

  1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. 잠그거나 잠금 해제할 프로젝트 러너를 찾으세요. 러너가 활성화되어 있는지 확인하세요. 인스턴스나 그룹 러너는 잠글 수 없어요.
  5. Edit ( pencil )을 선택하세요.
  6. Lock to current projects 체크박스를 선택하세요.
  7. Save changes를 선택하세요.

러너 상태 (Runner statuses)

러너는 다음 상태 중 하나를 가질 수 있어요.

Status Description
online 러너가 지난 2시간 안에 GitLab에 연락했고 잡을 실행할 수 있는 상태.
offline 러너가 2시간 이상 GitLab에 연락하지 않았고 잡을 실행할 수 없는 상태. 러너를 확인해 온라인으로 되돌릴 수 있는지 보세요.
stale 러너가 7일 이상 GitLab에 연락하지 않은 상태. 러너가 7일 전에 생성됐지만 인스턴스에 한 번도 연락하지 않았다면 stale로 간주돼요.
never_contacted 러너가 GitLab에 한 번도 연락하지 않은 상태. 러너가 GitLab에 연락하게 하려면 gitlab-runner run을 실행하세요.

오래된 러너 관리자 정리

GitLab은 가벼운 데이터베이스를 유지하기 위해 주기적으로 오래된 러너 관리자를 삭제해요. 러너가 GitLab 인스턴스에 연락하면 연결이 다시 생성돼요.

러너 성능 통계 보기

관리자는 러너 통계를 보고 러너 플릿의 성능을 파악할 수 있어요.

Median job queued time 값은 인스턴스 러너가 실행한 가장 최근 100개 잡의 큐 시간을 표본으로 계산해요. 최근 5000개 러너의 잡만 고려돼요.

중앙값(median)은 50번째 백분위수에 해당하는 값이에요. 잡의 절반은 중앙값보다 더 오래 큐에 있고, 절반은 중앙값보다 짧게 큐에 있어요.

러너 통계를 보려면:

  1. 오른쪽 위에서 Admin을 선택하세요.
  2. 왼쪽 사이드바에서 CI/CD > Runners를 선택하세요.
  3. View metrics를 선택하세요.

업그레이드해야 하는 러너 확인하기

전제 조건:

  • 인스턴스 러너를 보려면 관리자 액세스.
  • 그룹 러너를 보려면 Maintainer 또는 Owner 역할.

러너가 사용하는 GitLab Runner 버전은 최신 상태로 유지해야 해요.

업그레이드해야 하는 러너를 확인하려면:

  1. 러너 목록을 보세요:그룹의 경우:상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.Build > Runners를 선택하세요.인스턴스의 경우:오른쪽 위에서 Admin을 선택하세요.CI/CD > Runners를 선택하세요.
  2. 러너 목록 위에서 상태를 보세요:Outdated - recommended: 러너가 최신 PATCH 버전이 아니라 보안 또는 높은 심각도의 버그에 취약할 수 있는 상태. 또는 러너가 GitLab 인스턴스보다 하나 이상의 MAJOR 버전 뒤처져 일부 기능을 사용할 수 없거나 제대로 동작하지 않을 수 있는 상태.Outdated - available: 새 버전이 있지만 업그레이드가 중요하지 않은 상태.
  3. 상태별로 목록을 필터링해 업그레이드해야 하는 개별 러너를 확인하세요.

러너의 IP 주소 확인하기

러너 문제를 해결할 때 러너의 IP 주소가 필요할 수 있어요. GitLab은 러너가 잡을 폴링할 때 HTTP 요청의 소스를 보고 IP 주소를 저장하고 표시해요. GitLab은 IP 주소가 갱신될 때마다 자동으로 업데이트해요.

인스턴스 러너와 프로젝트 러너의 IP 주소는 서로 다른 위치에서 찾을 수 있어요.

인스턴스 러너의 IP 주소 확인하기

전제 조건:

  • 인스턴스에 관리자 액세스 권한이 있어야 해요.

인스턴스 러너의 IP 주소를 확인하려면:

  1. 오른쪽 위에서 Admin을 선택하세요.
  2. 왼쪽 사이드바에서 CI/CD > Runners를 선택하세요.
  3. 표에서 러너를 찾고 IP Address 열을 보세요.

Admin area showing the IP address column for an instance runner

프로젝트 러너의 IP 주소 확인하기

프로젝트의 러너 IP 주소를 찾으려면 프로젝트의 Owner 역할이 있어야 해요.

  1. 프로젝트의 Settings > CI/CD로 가서 Runners 섹션을 확장하세요.
  2. 러너 이름을 선택하고 IP Address 행을 찾으세요.

Runner details page showing the IP address field for a project runner

러너 구성에 유지보수 메모 추가하기

  • GitLab 18.2에서 그룹과 프로젝트에 대해 도입됐어요.

러너를 문서화하는 유지보수 메모를 추가할 수 있어요. 러너를 편집할 수 있는 사용자는 러너 상세 정보를 볼 때 메모를 볼 수 있어요.

이 기능을 사용해 러너 구성 변경과 관련된 영향이나 문제를 다른 사람에게 알리세요.

프로젝트와 그룹에서 러너 등록 토큰 사용 활성화하기

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

GitLab 17.0에서 러너 등록 토큰 사용은 모든 GitLab 인스턴스에서 비활성화됐어요.

전제 조건:

  • 러너 등록 토큰이 Admin 영역에서 활성화되어 있어야 해요.

프로젝트와 그룹에서 러너 등록 토큰 사용을 활성화하려면:

  1. 상단 바에서 Search or go to를 선택하고 그룹을 찾으세요.
  2. 왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
  3. Runners를 확장하세요.
  4. Allow members of projects and groups to create runners with runner registration tokens 토글을 켜세요.

더 알아보기

다음으로는 러너 등록과 GitLab Runner 설치 문서를 함께 보면, 인스턴스·그룹·프로젝트 러너를 상황에 맞게 설치하고 등록하는 방법을 익힐 수 있어요. 인스턴스 러너의 공정 사용 큐 동작을 이해하면 리소스 배분을 예측하기 좋아요.