---

새로운 러너 등록 워크플로우로 마이그레이션#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

러너 생성 워크플로우는 러너 인증 토큰을 사용하여 러너를 등록합니다. 등록 토큰을 사용하는 레거시 워크플로우는 권장되지 않습니다. 대신 러너 생성 워크플로우를 사용하세요.

새로운 러너 등록 워크플로우#

새로운 러너 등록 워크플로우에서:

• GitLab UI에서 직접 또는 프로그래밍 방식으로 러너를 생성합니다.

• 러너 인증 토큰을 받습니다.

• 이 구성으로 러너를 등록할 때 등록 토큰 대신 러너 인증 토큰을 사용합니다. 여러 호스트에 등록된 러너 매니저는 GitLab UI에서 동일한 러너 아래에 나타나지만 식별 시스템 ID가 있습니다.

새로운 러너 등록 워크플로우의 이점은 다음과 같습니다:

• 러너에 대한 소유권 기록 보존 및 사용자에 대한 영향 최소화.

• 고유한 시스템 ID 추가로 여러 러너에서 동일한 인증 토큰을 재사용할 수 있습니다. 자세한 내용은 GitLab Runner 구성 재사용을 참조하세요.

러너 등록 워크플로우가 중단되는 것을 방지#

GitLab 17.0 이상에서는 인스턴스 관리자 또는 그룹 소유자가 레거시 러너 등록 워크플로우를 비활성화할 수 있습니다. 자세한 내용은 GitLab 17.0 이후 등록 토큰 사용을 참조하세요.

새 워크플로우로 마이그레이션하지 않고 러너를 등록하면 러너 등록이 중단되고 gitlab-runner register 명령은 410 Gone - runner registration disallowed 오류를 반환합니다.

끊어진 워크플로우를 방지하려면:

• 러너를 생성하고 인증 토큰을 얻습니다.

• 러너 등록 워크플로우에서 등록 토큰을 인증 토큰으로 교체합니다.

GitLab 17.0 이후 등록 토큰 사용#

GitLab 17.0 이후 등록 토큰을 계속 사용하려면:

• GitLab.com에서 최상위 그룹 설정에서 레거시 러너 등록 프로세스를 수동으로 활성화할 수 있습니다.

• GitLab Self-Managed에서 Admin 영역 설정에서 레거시 러너 등록 프로세스를 수동으로 활성화할 수 있습니다.

기존 러너에 대한 영향#

기존 러너는 GitLab 17.0으로 업그레이드한 후에도 정상적으로 계속 작동합니다. 이 변경 사항은 새 러너 등록에만 영향을 미칩니다.

GitLab Runner Helm 차트는 job이 실행될 때마다 새 러너 포드를 생성합니다. 이러한 러너의 경우 등록 토큰을 사용하려면 레거시 러너 등록을 활성화하세요.

gitlab-runner register 명령 구문 변경#

gitlab-runner register 명령은 등록 토큰 대신 러너 인증 토큰을 허용합니다. Admin 영역의 러너 페이지에서 토큰을 생성할 수 있습니다. 러너 인증 토큰은 glrt- 접두사로 식별됩니다.

GitLab UI에서 러너를 만들 때 이전에 gitlab-runner register 명령으로 프롬프트된 명령줄 옵션이었던 구성 값을 지정합니다.

다음과 함께 러너 인증 토큰을 지정하는 경우:

• --token 명령줄 옵션을 사용하면 gitlab-runner register 명령은 구성 값을 허용하지 않습니다.

• --registration-token 명령줄 옵션을 사용하면 gitlab-runner register 명령은 구성 값을 무시합니다.

인증 토큰에는 glrt- 접두사가 있습니다.

자동화 워크플로우의 중단을 최소화하기 위해, 레거시 호환 등록 처리는 러너 인증 토큰이 레거시 매개변수 --registration-token에 지정된 경우 트리거됩니다.

이전에는 등록 명령에 추가 구성 인수가 필요했습니다:

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --tag-list "shell,mac,gdk,test" \
    --run-untagged "false" \
    --locked "false" \
    --access-level "not_protected" \
    --registration-token "REDACTED"

러너 인증 토큰을 사용하면 UI에서 러너를 만들 때 이러한 속성을 설정하고, 등록 명령에는 토큰만 필요합니다:

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --token "REDACTED"

자동 확장에 대한 영향#

GitLab Runner Operator 또는 GitLab Runner Helm 차트와 같은 자동 확장 시나리오에서, UI에서 생성된 러너 인증 토큰이 등록 토큰을 대체합니다. 이는 각 job에 대해 러너를 생성하는 대신 동일한 러너 구성이 job 전반에 걸쳐 재사용된다는 것을 의미합니다. 특정 러너는 러너 프로세스가 시작될 때 생성되는 고유한 시스템 ID로 식별될 수 있습니다.

프로그래밍 방식으로 러너 생성#

POST /user/runners REST API를 사용하여 인증된 사용자로 러너를 만들 수 있습니다. 러너 구성이 동적이거나 재사용 불가능한 경우에만 사용해야 합니다. 러너 구성이 정적인 경우 기존 러너의 러너 인증 토큰을 재사용해야 합니다.

러너 생성 및 등록 자동화 방법에 대한 지침은 튜토리얼 러너 생성 및 등록 자동화를 참조하세요.

Helm 차트로 GitLab Runner 설치#

러너 등록 토큰이 비활성화된 경우 러너 등록 중에 일부 러너 구성 옵션을 설정할 수 없습니다. 이러한 옵션은 다음에서만 구성할 수 있습니다:

• UI에서 러너를 만들 때.

• user/runners REST API 엔드포인트를 사용하여.

다음 구성 옵션은 해당 시나리오에서 values.yaml에서 지원되지 않습니다:

## 러너 인증 토큰이 runnerRegistrationToken에 지정된 경우 등록은 성공하지만
## 다른 값은 무시됩니다.
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true

Kubernetes의 GitLab Runner의 경우, Helm 배포는 러너 인증 토큰을 러너 워커 포드에 전달하고 러너 구성을 만듭니다. GitLab 17.0 이상에서 GitLab.com에 연결된 Kubernetes 호스팅 러너에서 runnerRegistrationToken 토큰 필드를 사용하면 러너 워커 포드가 생성 중에 레거시 등록 API 방법을 사용하려고 합니다.

유효하지 않은 runnerRegistrationToken 필드를 runnerToken 필드로 교체하세요. secrets에 저장된 러너 인증 토큰도 수정해야 합니다.

레거시 러너 등록 워크플로우에서 필드는 다음과 같이 지정되었습니다:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "REDACTED" # DEPRECATED, set to ""
  runner-token: ""

새 러너 등록 워크플로우에서는 대신 runner-token을 사용해야 합니다:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "" # need to leave as an empty string for compatibility reasons
  runner-token: "REDACTED"

비밀 관리 솔루션이 `runner-registration-token`에 빈 문자열을 설정할 수 없는 경우

임의의 문자열로 설정할 수 있습니다. runner-token이 존재할 때 이 값은 무시됩니다.

알려진 문제#

러너 세부 정보 페이지에 포드 이름이 표시되지 않음#

Helm 차트로 새 등록 워크플로우를 사용하여 러너를 등록하면 러너 세부 정보 페이지에 포드 이름이 표시되지 않습니다. 자세한 내용은 이슈 423523을 참조하세요.

교체 시 러너 인증 토큰이 업데이트되지 않음#

여러 러너 매니저에 등록된 동일한 러너의 토큰 교체#

새 워크플로우로 자동 토큰 교체와 함께 여러 호스트 시스템에 러너를 등록하면 첫 번째 러너 매니저만 새 토큰을 받습니다. 나머지 러너 매니저는 유효하지 않은 토큰을 계속 사용하여 연결이 끊깁니다. 새 토큰을 사용하도록 이러한 매니저를 수동으로 업데이트해야 합니다.

GitLab Operator에서 토큰 교체#

새 워크플로우를 통해 GitLab Operator로 러너를 등록하는 동안, Custom Resource Definition의 러너 인증 토큰이 토큰 교체 중에 업데이트되지 않습니다. 이는 다음과 같은 경우에 발생합니다:

• Custom Resource Definition에서 참조되는 비밀에서 러너 인증 토큰(glrt-로 시작)을 사용하는 경우.

• 러너 인증 토큰이 만료될 예정인 경우. 러너 인증 토큰 만료에 대한 자세한 내용은 인증 토큰 보안을 참조하세요.

자세한 내용은 이슈 186을 참조하세요.