- 요구 사항
- 러너 인증 토큰으로 등록
- 러너 등록 토큰으로 등록하기(사용 중단됨)
- 구성 템플릿으로 등록
- GitLab Community Edition 통합 테스트용 Runner 등록
- Docker와 Runner 등록
- 문제 해결
러너 등록
- GitLab Runner 15.0에서 소개된 등록 요청 형식 변경으로 인해, GitLab Runner가 GitLab 14.7 및 이전 버전과 통신할 수 없습니다. GitLab 버전에 적합한 GitLab Runner 버전을 사용하거나 GitLab 애플리케이션을 업그레이드해야 합니다.
러너 등록은 러너를 하나 이상의 GitLab 인스턴스에 연동하는 프로세스입니다. 러너를 등록하여 GitLab 인스턴스에서 작업을 수행하도록 설정해야 합니다.
요구 사항
러너를 등록하기 전에 다음을 준비하세요:
- GitLab이 설치된 서버와 별도의 서버에 GitLab Runner를 설치합니다.
- Docker로 러너를 등록하는 경우, 도커 컨테이너에 GitLab Runner 설치합니다.
러너 인증 토큰으로 등록
- GitLab 15.10에서 소개됨.
사전 요구 사항:
- 러너 인증 토큰을 획득합니다. 다음 중 하나를 사용할 수 있습니다:
러너를 등록한 후에는 구성이 config.toml
에 저장됩니다.
러너를 러너 인증 토큰과 함께 등록하려면:
-
등록 명령을 실행합니다:
Linuxsudo gitlab-runner register
프록시 뒤에 있으면 환경 변수를 추가한 다음 등록 명령을 실행합니다:
export HTTP_PROXY=http://yourproxyurl:3128 export HTTPS_PROXY=http://yourproxyurl:3128 sudo -E gitlab-runner register
macOSgitlab-runner register
Windows.\gitlab-runner.exe register
FreeBSDsudo -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 자체 관리형 러너의 경우 GitLab 인스턴스에 대한 URL을 사용합니다. 예를 들어, 프로젝트가
gitlab.example.com/yourname/yourproject
에 호스팅된 경우 GitLab 인스턴스 URL은https://gitlab.example.com
입니다. - GitLab.com의 러너의 경우
gitlab-ci coordinator URL
은https://gitlab.com
입니다.
- GitLab 자체 관리형 러너의 경우 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"
러너 등록 토큰으로 등록하기(사용 중단됨)
경고: 러너 등록 토큰을 전달하고 특정 구성 인수를 지원하는 기능은 GitLab 15.6에서 사용 중단되었으며 GitLab 18.0에서 제거될 것입니다. 러너 인증 토큰을 대신 사용해야 합니다. 자세한 내용은 새로운 러너 등록 워크플로의 이전을 참조하세요.
필수 구성 요소:
러너 등록을 완료한 후, 구성은 config.toml
에 저장됩니다.
러너를 러너 등록 토큰으로 등록하려면:
-
등록 명령을 실행하세요:
Linuxsudo gitlab-runner register
프록시 뒤에 있는 경우 환경 변수를 추가한 다음 등록 명령을 실행하세요:
export HTTP_PROXY=http://yourproxyurl:3128 export HTTPS_PROXY=http://yourproxyurl:3128 sudo -E gitlab-runner register
macOSgitlab-runner register
Windows.\gitlab-runner.exe register
FreeBSDsudo -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 Self-Managed 러너의 경우 GitLab 인스턴스 URL을 사용하세요. 예를 들어, 프로젝트가
gitlab.example.com/yourname/yourproject
에 호스팅되는 경우, GitLab 인스턴스 URL은https://gitlab.example.com
입니다. - GitLab.com의 경우,
gitlab-ci coordinator URL
은https://gitlab.com
입니다.
- GitLab Self-Managed 러너의 경우 GitLab 인스턴스 URL을 사용하세요. 예를 들어, 프로젝트가
- 러너 등록을 위해 획득한 토큰을 입력하세요.
- 러너에 대한 설명을 입력하세요.
- 쉼표로 구분된 작업 태그를 입력하세요.
- 러너에 대한 선택적 유지보수 노트를 입력하세요.
- 실행자 유형을 입력하세요.
동일한 호스트 머신에 여러 러너를 다른 구성으로 등록하려면 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에서 소개되었습니다.
런너 등록 토큰 및 몇 가지 러너 구성 인수가 GitLab 15.6에서는 사용되지 않게 표시되었으며, GitLab 18.0에서 제거될 예정입니다. 자동화 워크플로우에 최소한의 중단을 보장하기 위해, 레거시 호환 등록 프로세스
는 레거시 매개변수 --registration-token
에 러너 인증 토큰이 지정된 경우 트리거됩니다.
레거시 호환 등록 프로세스는 다음 명령줄 매개변수를 무시합니다. 이러한 매개변수는 UI에서 러너가 생성되거나 API로 구성될 때만 구성할 수 있습니다.
--locked
--access-level
--run-untagged
--maximum-timeout
--paused
--tag-list
--maintenance-note
구성 템플릿으로 등록
구성 템플릿을 사용하여 register
명령에서 지원되지 않는 설정으로 러너를 등록할 수 있습니다.
전제 조건:
- 템플릿 파일 위치를 나타내는 볼륨은 GitLab 러너 컨테이너에 마운트되어 있어야 합니다.
- 러너 인증 또는 등록 토큰:
구성 템플릿은 다음과 같은 이유로 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"
명령줄 인수 또는 환경 변수는 구성 템플릿의 설정보다 우선합니다. 예를 들어, 템플릿에서 docker
실행기를 지정하지만 명령줄에서 shell
을 지정하는 경우 구성된 실행기는 shell
입니다.
GitLab Community Edition 통합 테스트용 Runner 등록
GitLab Community Edition 통합을 테스트하려면 구성 템플릿을 사용하여 제한된 Docker 실행기가 있는 Runner를 등록합니다.
- 프로젝트 Runner를 생성합니다.
-
다음과 같이
[[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
-
Runner를 등록합니다:
Linuxsudo 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
macOSgitlab-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
FreeBSDsudo -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
Dockerdocker 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와 Runner 등록
Docker 컨테이너에 Runner를 등록한 후:
- 구성이 구성 볼륨에 작성됩니다. 예:
/srv/gitlab-runner/config
. - 컨테이너는 구성 볼륨을 사용하여 Runner를 로드합니다.
참고:
gitlab-runner restart
가 Docker 컨테이너에서 실행되는 경우, GitLab Runner는 기존 프로세스를 재시작하는 대신 새 프로세스를 시작합니다.
구성 변경을 적용하려면 Docker 컨테이너를 다시 시작해야 합니다.
문제 해결
Check registration token
오류
Check registration token
오류 메시지는 GitLab 인스턴스가 등록 중에 입력한 Runner 등록 토큰을 인식하지 못할 때 표시됩니다. 이 문제는 다음 중 하나일 때 발생할 수 있습니다:
- 인스턴스, 그룹 또는 프로젝트 Runner 등록 토큰이 GitLab에서 변경되었을 때.
- 잘못된 Runner 등록 토큰이 입력되었을 때.
이 오류가 발생하면 GitLab 관리자에게 다음을 요청할 수 있습니다:
- Runner 등록 토큰이 유효한지 확인합니다.
- 프로젝트 또는 그룹에서 Runner 등록이 허용되었는지 확인합니다.