러너 등록
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
러너 등록은 러너를 하나 이상의 GitLab 인스턴스와 연결하는 프로세스입니다. 러너를 등록하면 구성이 config.toml에 저장됩니다. 러너 인증 토큰으로 러너를 등록하려면: 프록시 뒤에 있는 경우 환경 변수를 추가한 다음 등록 명령을 실행합니다:
히스토리
- 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에 저장됩니다.
러너 인증 토큰으로 러너를 등록하려면:
-
등록 명령을 실행합니다:
sudo gitlab-runner register프록시 뒤에 있는 경우 환경 변수를 추가한 다음 등록 명령을 실행합니다:
export HTTP_PROXY=http://yourproxyurl:3128 export HTTPS_PROXY=http://yourproxyurl:3128 sudo -E gitlab-runner registergitlab-runner register.\gitlab-runner.exe registersudo -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 볼륨 마운트의 경우:
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입니다.
- GitLab Self-Managed의 러너의 경우 GitLab 인스턴스의 URL을 사용합니다. 예를 들어 프로젝트가
- 러너 인증 토큰을 입력합니다.
- 러너에 대한 설명을 입력합니다.
- 쉼표로 구분하여 잡 태그를 입력합니다.
- 러너에 대한 선택적 유지 관리 메모를 입력합니다.
- executor 유형을 입력합니다.
- 동일한 호스트 머신에 각각 다른 구성으로 여러 러너를 등록하려면
register명령을 반복합니다. - 여러 호스트 머신에 동일한 구성을 등록하려면 각 러너 등록에 동일한 러너 인증 토큰을 사용합니다. 자세한 내용은 러너 구성 재사용을 참조하세요.
비대화형 모드를 사용하여 러너 등록에 추가 인수를 사용할 수도 있습니다:
sudo gitlab-runner register \ --non-interactive \ --url "https://gitlab.com/" \ --token "$RUNNER_TOKEN" \ --executor "docker" \ --docker-image alpine:latest \ --description "docker-runner"gitlab-runner register \ --non-interactive \ --url "https://gitlab.com/" \ --token "$RUNNER_TOKEN" \ --executor "docker" \ --docker-image alpine:latest \ --description "docker-runner".\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"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 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"러너 등록 토큰으로 등록 (deprecated)#
Warning러너 등록 토큰 및 여러 러너 구성 인수가 deprecated되었습니다. GitLab 20.0에서 제거될 예정입니다. 대신 러너 인증 토큰을 사용하세요. 자세한 내용은 새 러너 등록 워크플로우로 마이그레이션을 참조하세요.
사전 조건:
러너를 등록하면 구성이
config.toml에 저장됩니다.러너 등록 토큰으로 러너를 등록하려면:
-
등록 명령을 실행합니다:
sudo gitlab-runner register프록시 뒤에 있는 경우 환경 변수를 추가한 다음 등록 명령을 실행합니다:
export HTTP_PROXY=http://yourproxyurl:3128 export HTTPS_PROXY=http://yourproxyurl:3128 sudo -E gitlab-runner registergitlab-runner register.\gitlab-runner.exe registersudo -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 볼륨 마운트의 경우:
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 인스턴스 URL은
https://gitlab.com입니다.
- GitLab Self-Managed의 러너의 경우 GitLab 인스턴스의 URL을 사용합니다. 예를 들어 프로젝트가
- 러너를 등록하기 위해 획득한 토큰을 입력합니다.
- 러너에 대한 설명을 입력합니다.
- 쉼표로 구분하여 잡 태그를 입력합니다.
- 러너에 대한 선택적 유지 관리 메모를 입력합니다.
- executor 유형을 입력합니다.
동일한 호스트 머신에 각각 다른 구성으로 여러 러너를 등록하려면
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 "Free-form maintainer notes about this runner" \ --tag-list "docker,aws" \ --run-untagged="true" \ --locked="false" \ --access-level="not_protected"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 "Free-form maintainer notes about this runner" \ --tag-list "docker,aws" \ --run-untagged="true" \ --locked="false" \ --access-level="not_protected".\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 "Free-form maintainer notes about this runner" \ --tag-list "docker,aws" \ --run-untagged="true" \ --locked="false" \ --access-level="not_protected"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 "Free-form maintainer notes about this runner" \ --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 "Free-form maintainer notes about this runner" \ --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에서 도입됨.
러너 등록 토큰 및 여러 러너 구성 인수가 deprecated되었습니다. GitLab 20.0에서 제거될 예정입니다. 자동화 워크플로우의 중단을 최소화하기 위해 러너 인증 토큰이 레거시 파라미터
--registration-token에 지정되면legacy-compatible registration process가 트리거됩니다.레거시 호환 등록 프로세스는 다음 명령줄 파라미터를 무시합니다. 이러한 파라미터는 UI 또는 API에서 러너를 생성할 때만 구성할 수 있습니다.
--locked--access-level--run-untagged--maximum-timeout--paused--tag-list--maintenance-note
구성 템플릿으로 등록#
register명령으로 지원되지 않는 설정으로 러너를 등록하기 위해 구성 템플릿을 사용할 수 있습니다.사전 조건:
- 템플릿 파일 위치의 볼륨이 GitLab Runner 컨테이너에 마운트되어야 합니다.
- 러너 인증 또는 등록 토큰:
구성 템플릿은 다음 이유로
register명령의 일부 인수를 지원하지 않는 자동화 환경에 사용할 수 있습니다:- 환경을 기반으로 한 환경 변수의 크기 제한.
- Kubernetes executor 볼륨에 사용할 수 없는 명령줄 옵션.
Warning구성 템플릿은 단일
[[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 \ "# --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-" 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 또는 존재하지 않는 항목
- 0
명령줄 인수 또는 환경 변수가 구성 템플릿의 설정보다 우선합니다. 예를 들어 템플릿이
dockerexecutor를 지정하지만 명령줄에서shell을 지정하면 구성된 executor는shell입니다.GitLab Community Edition 통합 테스트를 위한 러너 등록#
GitLab Community Edition 통합을 테스트하려면 구성 템플릿을 사용하여 제한된 Docker executor로 러너를 등록합니다.
-
프로젝트 러너를 생성합니다.
-
[[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 -
러너를 등록합니다:
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-3.1" \ --executor "docker" \ --docker-image ruby:3.1gitlab-runner register \ --non-interactive \ --url "https://gitlab.com" \ --token "$RUNNER_AUTHENTICATION_TOKEN" \ --template-config /tmp/test-config.template.toml \ --description "gitlab-ce-ruby-3.1" \ --executor "docker" \ --docker-image ruby:3.1.\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-3.1" \ --executor "docker" \ --docker-image ruby:3.1sudo -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-3.1" \ --executor "docker" \ --docker-image ruby:3.1docker 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-3.1" \ --executor "docker" \ --docker-image ruby:3.1더 많은 구성 옵션은 고급 구성을 참조하세요.
Docker로 러너 등록#
Docker 컨테이너로 러너를 등록한 후:
- 구성이 구성 볼륨에 기록됩니다. 예를 들어
/srv/gitlab-runner/config. - 컨테이너는 구성 볼륨을 사용하여 러너를 로드합니다.
Notegitlab-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 관리자에게 다음을 요청할 수 있습니다:
- 구성이 구성 볼륨에 기록됩니다. 예를 들어
-
-