러너 등록

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed

GitLab Runner 15.0에서 소개된 변경으로, 레지스트레이션 요청 형식이 변경되어 GitLab Runner가 GitLab 14.7 및 이전 버전과 통신하지 못하게 되었습니다. GitLab 버전에 적합한 GitLab Runner 버전을 사용하거나 GitLab 애플리케이션을 업그레이드해야 합니다.

러너 등록은 러너를 하나 이상의 GitLab 인스턴스에 연결하는 프로세스입니다. 러너를 등록하여 GitLab 인스턴스에서 작업을 가져올 수 있어야 합니다.

요구 사항

러너를 등록하기 전에:

GitLab Runner를 GitLab이 설치된 서버와 분리된 서버에 설치합니다.
Docker를 사용하여 러너를 등록하려면 도커 컨테이너에 GitLab Runner를 설치합니다.

러너 인증 토큰으로 등록

GitLab 15.10에서 소개되었습니다.

사전 요구 사항:

러너 인증 토큰을 획득합니다. 다음 중 하나를 선택할 수 있습니다:
- 공유, 그룹, 또는 프로젝트 러너를 생성합니다.
- config.toml 파일에서 러너 인증 토큰을 찾습니다. 러너 인증 토큰은 glrt- 접두사가 있습니다.

러너를 등록한 후에 구성이 config.toml에 저장됩니다.

러너를 러너 인증 토큰으로 등록하려면:

register 명령을 실행합니다:
Linux
```
sudo gitlab-runner register
```
프록시 뒤에 있으면 환경 변수를 추가한 다음 등록 명령을 실행합니다:
```
export HTTP_PROXY=http://yourproxyurl:3128
export HTTPS_PROXY=http://yourproxyurl:3128
   
sudo -E gitlab-runner register
```
macOS
```
gitlab-runner register
```
Windows
```
.\gitlab-runner.exe register
```
FreeBSD
```
sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
```
Docker

컨테이너로 등록하려면 다음 중 하나를 사용할 수 있습니다:
- 올바른 구성 볼륨을 사용하여 일시적인 gitlab-runner 컨테이너를 사용합니다:
  - 로컬 시스템 볼륨 마운트용:
    docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
    설치 중 /srv/gitlab-runner/config 외의 구성 볼륨을 사용했다면 명령을 올바른 볼륨으로 업데이트합니다.
  - Docker 볼륨 마운트용:
    docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
- 활성 러너 컨테이너 내에서 실행 파일을 사용합니다:
  docker exec -it gitlab-runner gitlab-runner register
GitLab URL을 입력합니다:
- GitLab Self-managed의 경우 GitLab 인스턴스의 URL을 사용합니다. 예를 들어, 프로젝트가 gitlab.example.com/yourname/yourproject에 호스팅된 경우, GitLab 인스턴스 URL은 https://gitlab.example.com입니다.
- GitLab.com의 경우 gitlab-ci coordinator URL은 https://gitlab.com입니다.
러너 인증 토큰을 입력합니다.
러너의 이름을 입력합니다.
Executor 유형을 입력합니다.

동일한 호스트 머신에 여러 러너를 등록하려면 각각 다른 구성으로 register 명령을 반복합니다.
여러 호스트 머신에서 동일한 구성을 등록하려면 각 러너 등록에 동일한 러너 인증 토큰을 사용합니다. 자세한 내용은 러너 구성 재사용을 참조하세요.

비대화식 모드를 사용하여 러너를 등록하기 위해 추가 인수를 사용할 수도 있습니다:

Linux

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

macOS

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

Windows

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner"

FreeBSD

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

Docker

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

레거시 러너 등록 토큰으로 등록하기(누락됨)

러너 등록 토큰을 전달하고 특정 구성 인수를 지원하는 기능은 GitLab 15.6에서 누락되었으며 GitLab 18.0에서 제거될 예정입니다. 러너 인증 토큰을 대신 사용해야 합니다. 자세한 내용은 새 러너 등록 작업으로 마이그레이션을 참조하세요.

필수 조건:

러너 등록 토큰 획득 공유, 그룹, 또는 프로젝트 러너용.

러너를 등록한 후, 설정이 config.toml에 저장됩니다.

러너 등록 토큰으로 러너를 등록하려면:

등록 명령어 실행:

리눅스

sudo gitlab-runner register

프록시 뒤에 있다면 환경 변수를 추가한 다음 등록 몤령어를 실행하세요:

export HTTP_PROXY=http://yourproxyurl:3128
export HTTPS_PROXY=http://yourproxyurl:3128
   
sudo -E gitlab-runner register

macOS

gitlab-runner register

Windows

.\gitlab-runner.exe register

FreeBSD

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register

도커

설치 중에 생성한 컨테이너를 등록하기 위해 잠시 사용되는 gitlab-runner 컨테이너를 시작하려면:

로컬 시스템 볼륨 마운트용:
```
docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
```
설치 중에 /srv/gitlab-runner/config가 아닌 다른 구성 볼륨을 사용했다면 올바른 볼륨으로 명령을 업데이트하세요.

도커 볼륨 마운트용:

docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register

GitLab URL을 입력하세요:
- GitLab Self-managed 러너의 경우 GitLab 인스턴스의 URL을 사용하세요. 예를 들어, 프로젝트가 gitlab.example.com/yourname/yourproject에 호스팅된 경우 GitLab 인스턴스 URL은 https://gitlab.example.com입니다.
- GitLab.com의 경우 gitlab-ci coordinator URL은 https://gitlab.com입니다.
등록한 러너용 토큰을 입력하세요.
러너 설명을 입력하세요.
쉼표로 구분된 작업 태그를 입력하세요.
러너에 대한 선택적 유지 관리 노트를 입력하세요.
실행자 유형을 입력하세요.

같은 호스트 머신에 여러 러너를 다른 구성으로 등록하려면 register 명령어를 반복하세요.

러너를 등록하는 추가적인 인수로 비대화식 모드를 사용할 수도 있습니다:

리눅스

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "러너에 대한 자유로운 유지 관리 노트" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

macOS

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "러너에 대한 자유로운 유지 관리 노트" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

Windows

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner" \
  --maintenance-note "러너에 대한 자유로운 유지 관리 노트" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

FreeBSD

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "러너에 대한 자유로운 유지 관리 노트" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

도커

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "러너에 대한 자유로운 유지 관리 노트" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

--access-level은 보호된 러너를 생성합니다.
- 보호된 러너의 경우 --access-level="ref_protected" 매개변수를 사용하세요.
- 보호되지 않은 러너의 경우 --access-level="not_protected"를 사용하거나 값을 미정의 상태로 두세요.
--maintenance-note은 러너 유지 관리와 관련된 정보를 추가합니다. 최대 길이는 255자입니다.

레거시 호환 등록 프로세스

GitLab 16.2에 도입되었습니다.

GitLab 15.6에서 러너 등록 토큰 및 여러 러너 구성 인수가 폐기 예정되었으며, GitLab 18.0에서 제거될 예정입니다. 자동화 워크플로에 최소한의 중단을 보장하기 위해 레거시 호환 등록 프로세스는 레거시 파라미터 --registration-token에 러너 인증 토큰이 지정된 경우 트리거됩니다.

레거시 호환 등록 프로세스는 다음 명령줄 매개변수를 무시합니다. 이러한 매개변수는 UI에서 러너가 생성되거나 API로 구성될 때만 구성할 수 있습니다.

--locked
--access-level
--run-untagged
--maximum-timeout
--paused
--tag-list
--maintenance-note

구성 템플릿으로 등록

register 명령어에서 지원되지 않는 설정으로 러너를 등록하기 위해 구성 템플릿을 사용할 수 있습니다.

필수 컴포넌트:

템플릿 파일의 위치에 대한 볼륨은 GitLab 러너 컨테이너에 마운트되어야 합니다.
러너 인증 또는 등록 토큰:
- 러너 인증 토큰 획득(권장사항). 다음 방법 중 하나를 사용할 수 있습니다:
  - 공유, 그룹, 또는 프로젝트 러너 생성.
  - config.toml 파일에서 러너 인증 토큰 위치 찾기. 러너 인증 토큰 앞에는 접두사 glrt-가 있습니다.
- 러너 등록 토큰 획득(폐기예정). 공유, 그룹, 또는 프로젝트 러너용 러너 등록 토큰 획득.

구성 템플릿은 register 명령에서 일부 매개변수가 지원되지 않는 자동화 환경에 사용할 수 있습니다.

환경에 따라 환경 변수 크기 제한.
Kubernetes용 실행자 볼륨에서 사용할 수 없는 명령줄 옵션.

구성 템플릿은 단일 [[runners]] 섹션만 지원하며 전역 옵션을 지원하지 않습니다.

러너를 등록하려면:

.toml 형식의 구성 템플릿 파일을 만들고 사양을 추가하세요. 예:

[[runners]]
  [runners.kubernetes]
  [runners.kubernetes.volumes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty_dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"

파일 경로를 추가하세요. 두 가지 방법 중 하나를 사용할 수 있습니다:

명령줄에서 비대화식 모드 사용:

$ sudo gitlab-runner register \
--template-config /tmp/test-config.template.toml \
--non-interactive \
--url "https://gitlab.com" \
--token <TOKEN> \ "# 폐기 예정 러너 등록 토큰 사용 시 --registration-token"
--name test-runner \
--executor kubernetes
--host = "http://localhost:9876/"

.gitlab.yaml 파일의 환경 변수 사용:

variables:
  TEMPLATE_CONFIG_FILE = <file_path>

환경 변수를 업데이트하면 매번 register 명령에서 파일 경로를 추가할 필요가 없습니다.

러너를 등록한 후, 구성 템플릿의 설정이 config.toml에 생성된 [[runners]] 항목과 Merge됩니다:

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://gitlab.com"
  token = glrt-<TOKEN>
  executor = "kubernetes"
  [runners.kubernetes]
    host = "http://localhost:9876/"
    bearer_token_overwrite_allowed = false
    image = ""
    namespace = ""
    namespace_overwrite_allowed = ""
    privileged = false
    service_account_overwrite_allowed = ""
    pod_labels_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    [runners.kubernetes.volumes]
       
       [[runners.kubernetes.volumes.empty_dir]]
         name = "empty_dir"
         mount_path = "/path/to/empty_dir"
         medium = "Memory"

템플릿 설정은 다음과 같은 옵션에 대해서만 Merge됩니다:

빈 문자열
Null 또는 존재하지 않는 항목
제로

명령줄 매개변수 또는 환경 변수가 구성 템플릿의 설정보다 우선합니다. 예를 들어, 템플릿이 docker 실행자를 지정하지만 명령줄이 shell을 지정하는 경우, 구성된 실행자는 shell입니다.

GitLab Community Edition 통합 테스트용 러너 등록

GitLab Community Edition 통합을 테스트하려면 환송된 Docker 실행자를 사용하여 러너를 등록할 수 있습니다.

프로젝트 러너를 만듭니다.

[[runners.docker.services]] 섹션을 가진 템플릿을 만드세요:

$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
[runners.docker]
[[runners.docker.services]]
name = "mysql:latest"
[[runners.docker.services]]
name = "redis:latest"
   
EOF

러너를 등록합니다:

Linux

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

macOS

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

Windows

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

FreeBSD

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

Docker

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

더 많은 구성 옵션은 고급 구성을 참조하세요.

Docker로 실행 중인 러너 등록

Docker 컨테이너로 러너를 등록한 후:

구성이 구성 볼륨에 작성됩니다. 예: /srv/gitlab-runner/config.
컨테이너는 러너를 로드하기 위해 구성 볼륨을 사용합니다.

만약 gitlab-runner restart가 Docker 컨테이너에서 실행되면, 기존 프로세스를 재시작하는 대신 GitLab Runner는 새 프로세스를 시작합니다. 구성 변경을 적용하려면 Docker 컨테이너를 다시 시작하면 됩니다.

문제 해결

`registration token 확인` 오류

registration token 확인 오류 메시지는 GitLab 인스턴스가 등록 중에 입력된 러너 등록 토큰을 인식하지 못할 때 표시됩니다. 이 문제는 다음 중 하나가 발생할 수 있습니다:

인스턴스, 그룹 또는 프로젝트 러너 등록 토큰이 GitLab에서 변경되었을 때.
잘못된 러너 등록 토큰이 입력된 경우.

이 오류가 발생하면 GitLab 관리자에게 다음 작업을 요청할 수 있습니다:

러너 등록 토큰이 유효한지 확인합니다.
프로젝트나 그룹에서 러너 등록이 허용되었는지 확인합니다.

러너 등록

요구 사항

러너 인증 토큰으로 등록

레거시 러너 등록 토큰으로 등록하기(누락됨)

레거시 호환 등록 프로세스

구성 템플릿으로 등록

GitLab Community Edition 통합 테스트용 러너 등록

Docker로 실행 중인 러너 등록

문제 해결

`registration token 확인` 오류

도움말

기능 사용 가능성과 제품 평가판

도움받기

러너 등록

요구 사항

러너 인증 토큰으로 등록

레거시 러너 등록 토큰으로 등록하기(누락됨)

레거시 호환 등록 프로세스

구성 템플릿으로 등록

GitLab Community Edition 통합 테스트용 러너 등록

Docker로 실행 중인 러너 등록

문제 해결

registration token 확인 오류

도움말

기능 사용 가능성과 제품 평가판

도움받기

`registration token 확인` 오류