Локальные раннеры (Self-hosted)

Info

Локальный (self-hosted) раннер — это приложение, которое вы развертываете и которым управляете самостоятельно. Такой раннер подключается к вашему экземпляру GitVerse и выполняет задачи workflow в контролируемой вами среде (на хосте или в контейнере).

Рекомендации

Self-hosted раннеры подходят, если вам нужно:

  • запускать сборки и тесты в специфической инфраструктуре (например, со своими зависимостями, библиотеками, GPU и т. д.);
  • работать с внутренними сетями кодовой базой физически или по соображениям безопасности недоступной из облака;
  • выполнять долговременные задачи без ограничений по времени выполнения.

Режимы работы

В настоящее время self-hosted раннеры поддерживают два режима работы:

  • запуск в Docker-контейнере;
  • запуск непосредственно на хост-машине.

Рекомендуется запускать job’ы в контейнерах — это повышает изоляцию и воспроизводимость окружения.

Уровни привязки

Раннеры регистрируются/привязываются на одном из уровней:

  • уровень репозитория — выполняет задачи только в рамках этого репозитория;
  • уровень организации — выполняет задачи в рамках любого репозитория этой организации, см. организационный раннер.

Не запрещается иметь одновременно несколько раннеров на различных уровнях, задачи будут распределяться на первый освободившийся раннер в случайном порядке.

Скачивание, регистрация и настройка раннера

Info

Раннеры GitVerse доступны как нативные приложения под различные ОС и архитектуры, а также в виде Docker-образов.

Вы можете добавлять раннеры к репозиториям. Чтобы добавить локальный раннер к репозиторию, нужно быть владельцем репозитория.

  1. В репозитории перейдите в Настройки → Раннеры.

  2. В разделе Локальные раннеры нажмите Добавить раннер.

  3. Выберите платформу и архитектуру машины, на которой будет использоваться раннер.

  4. Скачайте актуальную версию раннера по кнопке Начать загрузку или из командной строки, следуя указаниям.

    Все версии доступны в пакетах организации GitVerse

  5. Зарегистрируйте и запустите раннер, последовательно выполнив дальнейшие рекомендации.

  6. Проверьте, что в Настройки → Раннеры → Локальные раннеры появился раннер.

Регистрация и запуск раннера

Перед запуском раннера, его необходимо зарегистрировать на сервере GitVerse.
Регистрация позволяет раннеру понимать, откуда забирать задания, а серверу — корректно идентифицировать этот раннер.

Регистрация

Сделайте файл исполняемым:

chmod +x act_runner

Если раннер запускается из бинарника, зарегистрировать его можно командой:

./act_runner register

Если используется конфигурационный файл:

./act_runner --config config.yaml register

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

  • uRL инстанса GitVerse, по умолчанию это https://gitverse.ru/sc;

  • токен регистрации раннера. Получить токен можно через интерфейс на странице регистрации раннера или через API;

  • имя раннера (необязательно). Если оставить пустым — будет использовано имя хоста;

  • метки раннера (необязательно). Если не указать — применяются значения по умолчанию.

Неинтерактивная регистрация

Для автоматизации можно передать параметры сразу:

./act_runner register \
  --no-interactive \
  --instance <URL инстанса GitVerse> \
  --token <токен регистрации раннера> \
  --name <имя раннера> \
  --labels <метки раннера>

Запуск раннера

После регистрации раннер можно запустить командой:

./act_runner daemon

или с конфигурационным файлом:

./act_runner daemon --config config.yaml

Если раннер запускается в docker-контейнере, регистрация и запуск выполняются так:

    docker run \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v $PWD/config.yaml:/config.yaml \
      -e CONFIG_FILE=/config.yaml \
      -e RUNNER_REGISTRATION_TOKEN=<registration_token> \
      -e RUNNER_NAME=<runner_name> \
      --name my_runner \
      -d gitverse.ru/gitverse/act-runner:latest

После запуска раннер:

  • подключается к инстансу GitVerse;
  • автоматически получает задания;
  • выполняет их согласно настройкам.

Запуск раннеров в качестве службы Linux

  1. Создайте файл для службы systemd: /etc/systemd/system/act_runner.service следующего содержания (нужно выполнять под пользователем, который состоит в группе sudo):
[Unit]
Description=My GitVerse runner
Documentation=https://gitverse.ru/docs/cicd/docs/runners/
After=docker.service
   
[Service]
ExecStart=/opt/act_runner/act_runner daemon --config /opt/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/opt/act_runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner
   
[Install]
WantedBy=multi-user.target
  1. Перезагрузите конфигурацию systemd:
    sudo systemctl daemon-reload
  1. Добавьте автоматический запуск сервиса при загрузке:
    sudo systemctl enable act_runner --now

Метки и среды выполнения

При регистрации self-hosted раннера ему автоматически присваиваются стандартные метки (labels).

Эти метки отражают операционную систему, аппаратную архитектуру раннера, а также влияют на режим, в котором выполняются задачи:

РежимМеткаОписаниеПример использования
Hostself-hosted, linux, windows, macos, x64, arm64Задачи выполняются на самом хосте, где установлен раннер.runs-on: [self-hosted, linux, x64]
Dockerimg-ubuntu-latest, img-ubuntu-22.04, img-ubuntu-20.04Раннер запускает задачу в контейнере с указанным образом.runs-on: img-ubuntu-20.04

Создание своих меток

Метки, в том числе и по умолчанию, задаются списком значений, разделенных запятой. Стандартный набор меток для раннера под Linux выглядит так:

linux:host, x64:host, self-hosted:host,
img-ubuntu-latest:gitverse:gitverse/runner-image:ubuntu-latest, img-ubuntu-22.04:gitverse:gitverse/runner-image:ubuntu-22.04, img-ubuntu-20.04:gitverse:gitverse/runner-image:ubuntu-20.04

Метка img-ubuntu-20.04:gitverse:gitverse/runner-image:ubuntu-20.04, где:

  • img-ubuntu-20.04 — сама метка и указывается в runs-on: img-ubuntu-20.04;
  • gitverse:gitverse/runner-image:ubuntu-20.04 указывает окружение для выполнения задач в Docker-контейнере, созданном из образа gitverse/runner-image:ubuntu-20.04.

Метка self-hosted:host

  • self-hosted — сама метка и указывается в runs-on: self-hosted;
  • host указывает, что каждая задача будет выполняться на самом хосте, где установлен раннер.

Суффикс :host не является обязательным, но рекомендуется использовать уникальные метки, например, linux_amd64:host или windows:host, чтобы избежать неоднозначностей и ошибок при маршрутизации задач.

Отслеживание занятости раннеров

Вы можете отслеживать занятость раннеров прямо в интерфейсе GitVerse. В репозитории перейдите в Настройки → Раннеры. Вы увидите список всех раннеров.

Рядом с каждым раннером указан его текущий статус:

  • идет сборка — раннер выполняет задачу;
  • свободен — раннер свободен для новой задачи;
  • недоступен — раннер зарегистрирован, но оффлайн.

Чтобы узнать больше о конкретном раннере, нажмите на его имя. Откроется страница с информацией о раннере и историей сборок. В истории сборок вы увидите основную информацию по задачам, а также время взятия в работу и продолжительность выполнения. При нажатии на название задачи вы перейдете в workflow, в котором выполнялась данная задача.

Расширенные возможности настройки

Раннер GitVerse позволяет гибко настраивать свою работу с помощью конфиг-файлов.

Сгенерировать конфигурационный файл можно так:

./act_runner generate-config > config.yaml

Использовать тоже достаточно просто:

./act_runner --config config.yaml [command]

Пример полного конфиг-файла с описанием настраиваемых полей:

log:
  # Уровень логирования - trace, debug, info, warn, error, fatal
  level: info
 
runner:
  # После регистрации раннера, в этом файле будут храниться основные настройки
  file: .runner
  # Максимальное количество одновременно выполняемых задач раннером
  capacity: 1
  # Переменные окружения, доступные во всех задачах
  envs:
    ENV_NAME_1: env_value_1
    ENV_NAME_2: env_value_2
  # Файл с переменными окружения
  env_file: .env
  # Максимальное время выполнения задачи
  timeout: 1h
  # Время ожидания завершения задач при остановке раннера
  shutdown_timeout: 0s
  # Отключение проверки TLS-сертификата
  insecure: false
  # Таймаут получения задач
  fetch_timeout: 5s
  # Интервал опроса очереди задач
  fetch_interval: 2s
  # Метки раннера (определяют, какие задачи он может выполнять)
  labels:
    - "macOS:host"
    - "x64:host"
    - "self-hosted:host"
    - "img-ubuntu-latest:gitverse:gitverse/runner-image:ubuntu-latest"
 
cache:
  # Включить поддержку actions/cache
  enabled: true
  # Каталог хранения кэша
  dir: ""
  # Адрес сервера кэша
  host: ""
  # Порт сервера кэша
  port: 0
  # Внешний сервер кэша
  external_server: ""
 
container:
  # Тип сети контейнеров
  network: ""
  # Запуск контейнеров в privileged-режиме
  privileged: false
  # Дополнительные параметры docker run
  options:
  # Базовый каталог рабочей директории
  workdir_parent:
  # Разрешенные тома для монтирования
  valid_volumes: []
  # Docker host
  docker_host: ""
  # Принудительно обновлять образы
  force_pull: true
  # Принудительно пересобирать образы
  force_rebuild: false
 
host:
  # Базовый каталог рабочей директории
  workdir_parent:

Вид графа

Связанные страницы