요구 사항
러너 인증 토큰으로 등록
실행자 등록 토큰으로 등록하기 (사용 중단)
- 레거시 호환 등록 프로세스
구성 템플릿으로 등록하기
GitLab Community Edition 통합 테스트를 위한 러너 등록
Docker로 러너 등록하기
문제 해결
- Check registration token 오류
- 410 Gone - runner registration disallowed 오류

러너 등록

Tier: Free, Premium, Ultimate

Offering: GitLab.com, Self-managed

도입됨 GitLab Runner 15.0에서, 등록 요청 형식의 변경으로 인해 GitLab Runner가 이전 버전의 GitLab과 통신할 수 없습니다. GitLab 버전에 적합한 GitLab Runner 버전을 사용해야 하며, 또는 GitLab 애플리케이션을 업그레이드해야 합니다.

러너 등록은 러너를 하나 이상의 GitLab 인스턴스에 연결하는 과정입니다. 러너가 GitLab 인스턴스에서 작업을 가져올 수 있도록 등록해야 합니다.

요구 사항

러너를 등록하기 전에:

GitLab이 설치된 서버와는 별도의 서버에 GitLab Runner를 설치합니다.
Docker를 사용한 러너 등록의 경우, Docker 컨테이너에 GitLab Runner 설치를 진행합니다.

러너 인증 토큰으로 등록

도입됨 GitLab 15.10.

전제 조건:

러너 인증 토큰을 확보합니다. 다음 중 하나를 수행할 수 있습니다:
- 인스턴스, 그룹, 또는 프로젝트 러너를 생성합니다.
- config.toml 파일에서 러너 인증 토큰을 찾습니다. 러너 인증 토큰은 glrt-라는 접두사가 있습니다.

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

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

등록 명령어를 실행합니다:
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 인스턴스 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에 저장됩니다.

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

등록 명령을 실행합니다:
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
GitLab URL을 입력합니다:
- GitLab 자체 관리 러너의 경우 GitLab 인스턴스의 URL을 사용하십시오. 예를 들어, 프로젝트가 gitlab.example.com/yourname/yourproject에 호스팅되는 경우 GitLab 인스턴스 URL은 https://gitlab.example.com입니다.
- GitLab.com의 경우 GitLab 인스턴스 URL은 https://gitlab.com입니다.
러너 등록에 사용할 토큰을 입력합니다.
러너에 대한 설명을 입력합니다.
쉼표로 구분된 작업 태그를 입력합니다.
러너에 대한 선택적 유지 관리 노트를 입력합니다.
실행기 유형을 입력합니다.

동일한 호스트 머신에서 여러 러너를 다르게 구성하여 등록하려면 register 명령을 반복하십시오.

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

Linux

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

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에서 제거될 예정입니다. 자동화 워크플로우에서 최소한의 중단을 보장하기 위해 legacy-compatible registration process는 레거시 매개변수 --registration-token에 러너 인증 토큰이 지정되면 트리거됩니다.

레거시 호환 등록 프로세스는 다음 명령줄 매개변수를 무시합니다. 이 매개변수는 UI 또는 API를 통해 러너를 생성할 때만 구성할 수 있습니다.

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

구성 템플릿으로 등록하기

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

필수 조건:

템플릿 파일 위치에 대한 볼륨이 GitLab Runner 컨테이너에 마운트되어 있어야 합니다.
러너 인증 또는 등록 토큰:
- 러너 인증 토큰을 획득하십시오(권장). 다음 방법 중 하나를 사용하여:
  - 인스턴스, 그룹 또는 프로젝트 러너를 생성합니다.
  - 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 if using the deprecated runner registration token"
    --name test-runner \
    --executor kubernetes
    --host = "http://localhost:9876/"

.gitlab.yaml 파일에서 환경 변수를 사용합니다:
```
variables:
  TEMPLATE_CONFIG_FILE = <file_path>
```
환경 변수를 업데이트하면 매번 등록할 때 register 명령에 파일 경로를 추가할 필요가 없습니다.

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

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"

템플릿 설정은 다음 옵션에 대해서만 병합됩니다:

빈 문자열
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 컨테이너를 재시작하세요.

문제 해결

`Check registration token` 오류

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

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

이 오류가 발생하면 GitLab 관리자에게 요청하여:

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

`410 Gone - runner registration disallowed` 오류

410 Gone - runner registration disallowed 오류 메시지는 등록 토큰을 통한 러너 등록이 비활성화되었을 때 표시됩니다.

이 오류가 발생하면 GitLab 관리자에게 요청하여:

러너 등록 토큰이 유효한지 확인합니다.
인스턴스에서의 러너 등록이 허용되었는지 확인합니다.
그룹 또는 프로젝트 러너 등록 토큰의 경우, 해당 그룹 및/또는 프로젝트에서 러너 등록이 허용되었는지 확인합니다.

러너 등록

요구 사항

러너 인증 토큰으로 등록

실행자 등록 토큰으로 등록하기 (사용 중단)

레거시 호환 등록 프로세스

구성 템플릿으로 등록하기

GitLab Community Edition 통합 테스트를 위한 러너 등록

Docker로 러너 등록하기

문제 해결

`Check registration token` 오류

`410 Gone - runner registration disallowed` 오류

도움말

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

도움받기

러너 등록

요구 사항

러너 인증 토큰으로 등록

실행자 등록 토큰으로 등록하기 (사용 중단)

레거시 호환 등록 프로세스

구성 템플릿으로 등록하기

GitLab Community Edition 통합 테스트를 위한 러너 등록

Docker로 러너 등록하기

문제 해결

Check registration token 오류

410 Gone - runner registration disallowed 오류

도움말

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

도움받기

`Check registration token` 오류

`410 Gone - runner registration disallowed` 오류