Как зарегистрировать runner в GitLab

1.0 Junior🔥 112 комментариев

#CI/CD и автоматизация

Комментарии (2)

🐱

deepseek-v3.2PrepBro AI5 апр. 2026 г.(ред.)

Ответ сгенерирован нейросетью и может содержать ошибки

Регистрация GitLab Runner: Методы и детальная инструкция

Регистрация GitLab Runner — это процесс подключения автономного исполнителя (runner) к вашему проекту, группе или инстансу GitLab для выполнения задач CI/CD. Runner выступает в роли рабочего агента, который получает задания из GitLab CI и исполняет их в изолированном окружении. Ниже я детально разберу основные методы и приведу пошаговые инструкции.

Предварительные требования

Перед регистрацией убедитесь, что:

GitLab Runner установлен на целевой машине (способ установки зависит от ОС: Linux, Windows, macOS, Docker, Kubernetes).
У вас есть доступ к GitLab инстансу с правами для регистрации раннера (обычно Maintainer или Owner).
Вы определились с типом раннера:

    *   **Shared**: доступен для всех проектов в инстансе (регистрирует администратор).
    *   **Group**: доступен для всех проектов в конкретной группе.
    *   **Project (специфичный)**: доступен только для одного проекта.

Ключевые методы регистрации

1. Интерактивная регистрация (рекомендуется для новичков)

Это самый распространённый метод, где утилита gitlab-runner register запрашивает необходимые данные в интерактивном режиме.

sudo gitlab-runner register

Во время выполнения команды вас последовательно запросят:

URL GitLab-инстанса: Например, https://gitlab.com для SaaS или https://gitlab.example.com для self-hosted.
Токен регистрации:

    *   Для **Shared** runner: `Settings` -> `CI/CD` -> `Runners` -> раздел "Set up a shared Runner manually" (требуются права администратора).
    *   Для **Group** runner: `Group` -> `Settings` -> `CI/CD` -> раздел "Runners" -> "New group runner".
    *   Для **Project** runner: `Project` -> `Settings` -> `CI/CD` -> раздел "Runners" -> "New project runner".

Описание: Человекочитаемое имя, например, linux-docker-runner-production.
Тэги: Список через запятую, например, docker,production,backend. Тэги позволяют направлять конкретные джобы на определённые раннеры.
Исполнитель (executor): Способ изоляции задач. Наиболее популярные:

    *   `docker` (задачи выполняются в Docker-контейнерах, высокий уровень изоляции).
    *   `shell` (задачи выполняются напрямую в shell системы, требует осторожности).
    *   `kubernetes` (задачи запускаются в pods Kubernetes).
    *   `docker+machine` (для автоматического масштабирования).

Пример интерактивного сеанса:

$ sudo gitlab-runner register
Runtime platform arch=amd64 os=linux pid=12345 revision=abcdef version=15.0.0
Running in system-mode.
Enter the GitLab instance URL (for example, https://gitlab.com/):
https://gitlab.example.com
Enter the registration token:
gr1342n-xxxYYYzzz123456
Enter a description for the runner:
my-aws-docker-runner
Enter tags for the runner (comma separated):
aws,linux,docker
Enter optional maintenance note for the runner:
Runner for production deployment
Registering runner... succeeded runner=gr1342n
Enter an executor: docker, shell, ssh, docker-ssh+machine, custom, parallels, virtualbox, docker+machine, kubernetes:
docker
Enter the default Docker image (for example, ruby:3.2):
alpine:latest
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

2. Неинтерактивная регистрация (автоматизация)

Для автоматизации в скриптах или конфигурациях инфраструктуры (IaC) используйте неинтерактивный режим, передавая все параметры переменными окружения или аргументами.

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --description "my-automated-runner" \
  --tag-list "docker,aws" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --maintenance-note "Runner deployed via Terraform"

Этот метод идеален для использования в Dockerfile, Terraform (с помощью local-exec), Ansible или скриптах облачной инициализации (cloud-init).

3. Регистрация через Docker (ad-hoc метод)

Если раннер запущен в Docker-контейнере, регистрацию можно выполнить "на лету".

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

Конфигурация и проверка

После успешной регистрации конфигурация сохраняется в файле config.toml (обычно расположен в /etc/gitlab-runner/ на Linux). Вы можете отредактировать его вручную для тонкой настройки (лимиты, параметры исполнителей, кеширование).

concurrent = 4
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "my-aws-docker-runner"
  url = "https://gitlab.example.com"
  token = "RUNNER_AUTH_TOKEN_FROM_GITLAB"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]

Чтобы проверить статус раннера:

В интерфейсе GitLab: Зайдите в Settings -> CI/CD -> Runners. Новый раннер должен отображаться с зелёным кружком (онлайн) или серым (офлайн).

На машине с раннером:

sudo gitlab-runner verify
# Или посмотреть статус службы
sudo systemctl status gitlab-runner
# Или проверить список зарегистрированных раннеров
sudo gitlab-runner list

Решение типовых проблем

Ошибка ERROR: Registering runner... failed: Чаще всего связана с неверным URL или токеном. Перепроверьте токен и корректность URL (без завершающего слеша).
Раннер не запускает джобы: Убедитесь, что служба раннера запущена (sudo gitlab-runner start). Проверьте тэги в .gitlab-ci.yml — они должны соответствовать тэгам раннера, либо раннер должен быть помечен как untagged (Run untagged jobs в настройках).
Проблемы с исполнителем Docker: Убедитесь, что демон Docker запущен и пользователь gitlab-runner добавлен в группу docker (sudo usermod -aG docker gitlab-runner).