Самостоятельно размещённые раннеры для GitHub Actions

Кратко

Самостоятельно размещённый раннер (self-hosted runner) — это рабочий узел, который вы запускаете на своей машине или сервере, чтобы выполнять workflow GitHub Actions. Такой раннер полезен для тяжёлых сборок, интеграции с корпоративной сетью или когда нужен нестандартный образ ОС. В этой инструкции — зачем это нужно, как настроить и как обезопасить запуск.

Быстрые ссылки

• Почему стоит использовать самостоятельные раннеры?

• Как настроить самостоятельный раннер

Определение

Самостоятельно размещённый раннер — это агент, установленный на вашем оборудовании или VPS, который принимает задания от GitHub Actions и выполняет их локально.

Почему стоит использовать самостоятельные раннеры?

GitHub Actions обеспечивает удобную автоматизацию и глубокую интеграцию с GitHub. По умолчанию workflow выполняются на облачных раннерах GitHub (hosted runners). Однако у self-hosted runner’ов есть отдельные преимущества:

• Контроль окружения. Вы выбираете ОС, версии пакетов и предустановленные инструменты.
• Производительность. На выделённом сервере или локальной машине сборки и компиляции часто проходят быстрее.
• Доступ к локальным ресурсам. Можно подключаться к on-premise базам данных, артефактным репозиториям и сетевым ресурсам без VPN/прокси.
• Экономия минуты биллинга для приватных репозиториев. GitHub Actions считает минуты выполнения. Для приватных репозиториев есть квоты (2000 минут по умолчанию, 3000 с Pro/Teams, 50 000 в Enterprise). Самостоятельные раннеры обходят платный учёт минут.

Важно: self-hosted раннеры несут дополнительные риски безопасности при запуске сборок из pull request’ов от сторонних контрибьюторов. GitHub по умолчанию блокирует использование self-hosted для public-репозиториев, чтобы снизить риск выполнения зловредного кода на вашем оборудовании.

Когда это не подходит

• Если у вас простой CI с небольшими рабочими нагрузками и нет требований к окружению — облачные hosted runners удобнее.
• Если вы не готовы поддерживать серверы (патчи, обновления, мониторинг). Self-hosted требует эксплуатации.
• Если вы запускаете чужой код из PR в публичных репозиториях — это риск безопасности, пока вы не настроите изоляцию (контейнеры, VM).

Альтернативы

• Hosted runners GitHub — быстрее начать, меньше поддержки.
• Контейнеризированные CI на вашем облаке (например, GitLab CI, CircleCI) — те же преимущества изоляции, но разный функционал.
• Запуск в облачных инстансах под вашим управлением (EC2, GCE) с инфраструктурой, которая автоматически масштабируется.

Настройка самостоятельного раннера

Ниже — пошаговая инструкция, с примерами команд и картинками интерфейса. Если вы уже видели панель настроек в GitHub, порядок действий совпадает.

1. В GitHub откройте настройки организации или репозитория: Actions > Runners > Add runner.

2. GitHub предложит команды для загрузки и установки программного обеспечения раннера. Вы можете выполнить их напрямую или использовать Docker-образ.

3. Связь с аккаунтом обеспечивается токеном, который создаётся в интерфейсе. Команда пример:

./config.sh --url https://github.com/Organization --token XXXXXX

4. На одном экране выбираете имя раннера, группу (runner group) и метки (labels). Метки помогают выбирать нужные раннеры в workflow.

5. Запускаете агент. Для надежности рекомендуем запустить его как системную службу или внутри tmux/screen, чтобы он перезапускался после падения сеанса.

./run.sh

6. В публичных репозиториях self-hosted раннеры включены не по умолчанию (ради безопасности). Если вы не собираете PR от сторонних контрибьюторов, можно включить их через настройки Runner Group.

7. В workflow указываете метку self-hosted в ключе runs-on, чтобы задания шли на ваш раннер:

8. В интерфейсе вы увидите, что раннер подхватил задание почти сразу.

Рекомендации по эксплуатации и безопасности

Важно выполнять базовую жёсткую настройку и мониторинг для self-hosted раннеров:

• Огранивайте доступ. Запускайте раннеры на отдельных машинах с минимальными правами доступа.
• Обновляйте ОС и пакеты. Регулярно применяйте патчи безопасности.
• Изолируйте сборки. Если возможно, выполняйте каждую сборку в контейнере или VM, чтобы ограничить побочные эффекты.
• Ограничьте запуск чужих PR. Отключите автоматический запуск workflow для pull request от форков, если не доверяете исполнению чужого кода.
• Логи и аудит. Собирайте логи выполнения, храните их централизованно и следите за аномалиями.
• Ротация токенов. При смене оператора или компрометации — регенерируйте токены доступа.

Практические шаги по обеспечению безопасности

• Запуск раннера в Docker: запустите GitHub Actions runner внутрь контейнера, чтобы обеспечить слои изоляции.
• Используйте непользовательский аккаунт (service account) с минимальными привилегиями для запуска раннера.
• Ограничьте сеть: разрешите доступ только к GitHub и внутренним ресурсам, необходимых для сборок.
• Мониторинг: настраивайте алерты по загрузке CPU, памяти и по нештатному поведению процессов.

Чек-лист для развертывания (рольной разбивкой)

Администратор (DevOps):

• Подготовить хост: ОС, диск, бэкап.
• Настроить сетевые правила и firewall.
• Создать сервисный аккаунт и сгенерировать токен.
• Настроить systemd unit или контейнер для автоматического запуска.
• Настроить мониторинг и логирование.

Разработчик:

• Добавить метку (label) в workflow: runs-on: [“self-hosted”, “label”]
• Проверить доступ к артефактам и секретам.
• Прогнать тестовую сборку и убедиться в воспроизводимости.

Операции/Безопасность:

• Настроить ротацию токенов и ревью доступа.
• Регулярно обновлять образ/пакеты.
• Периодически запускать тесты на изоляцию среды.

Критерии приёмки

• Раннер корректно регистрируется в GitHub и отображается как онлайн.
• Workflow с меткой self-hosted запускаются и завершаются успешно.
• Выполнена базовая настройка безопасности (контейнеризация/ограничения сети).
• Наблюдаются метрики CPU/памяти, соответствующие ожидаемой нагрузке.

Мини-методология: как внедрять постепенно

1. Разверните 1 раннер на тестовом окружении и прогоните типовые workflow.
2. Проверяйте совместимость образов и инструментов (компиляторы, SDK).
3. Оцените производительность и сравните с hosted runners.
4. Перенесите часть нагрузок в прод постепенно: сначала nightly, затем CI для важных веток.
5. Наблюдайте стоимость владения: администрирование, электричество, оборудование.

Пример простого плейбука восстановления (runbook)

• Случай: раннер перестал отвечать.
  1. Проверить статус сервиса systemd (или контейнера).
  2. Перезапустить сервис: sudo systemctl restart github-runner.service или ./run.sh в контейнере.
  3. Проверить логи раннера на ошибки аутентификации или нехватки ресурсов.
  4. Если токен просрочен — регенерировать токен в интерфейсе GitHub и переконфигурировать раннер.
  5. При подозрении на компрометацию — отключить раннер, собрать логи, пересоздать хост.

Пример файла workflow (фрагмент)

name: CI on self-hosted
on: [push]
jobs:
  build:
    runs-on: [self-hosted, linux, high-cpu]
    steps:
      - uses: actions/checkout@v2
      - name: Build
        run: |
          ./build.sh

Модель принятия решения (Mermaid)

flowchart TD
  A[Нужны ли локальные ресурсы или нестандартная ОС?] -->|Да| B[Рассмотреть self-hosted]
  A -->|Нет| C[Использовать hosted runners]
  B --> D{Есть ли команда для поддержки?}
  D -->|Да| E[Развернуть и мониторить]
  D -->|Нет| F[Оставаться на hosted или нанять поддержку]

Когда стоит оценить альтернативы

• Если вам нужно масштабирование по требованию — cloud-инстансы с autoscaling могут быть проще.
• Если безопасность критична и вы не хотите администрировать виртуалки — рассмотрите управляемые CI-сервисы с привязкой к VPC.

Сводка ключевых чисел

• Квоты минут GitHub Actions для приватных репозиториев: 2000 минут по умолчанию, 3000 с Pro/Teams, 50 000 в Enterprise (эти значения задаёт GitHub).
• Самостоятельные раннеры обходят учёт минут, но требуют эксплуатации и мониторинга.

Примечания

Важно: не включайте автоматический запуск workflow для внешних pull request’ов на self-hosted раннерах без дополнительной изоляции. Это главная причина, по которой GitHub ограничивает использование self-hosted в публичных репозиториях.

Итог

Самостоятельно размещённые раннеры дают контроль и производительность, но требуют ответственности за безопасность и эксплуатацию. Для тяжёлых сборок, доступа к on-premise ресурсам и экономии биллинга для приватных репозиториев self-hosted — разумный выбор. Начинайте с тестового раннера, настройте изоляцию и мониторинг, и постепенно переносите критичные задачи.