CI/CD на власному VPS: self-hosted runner для GitHub Actions

Яка VPS-конфігурація потрібна для цього завдання

Ресурси GitHub Actions self-hosted runner визначаються не самим агентом, а вашими job. Порожній runner споживає мало пам'яті та майже не використовує CPU. Однак Docker build, тести, компіляція TypeScript, Java, Rust або Android здатні швидко зайняти всю доступну RAM, процесор і диск.

Для першого runner під приватний репозиторій розумна стартова конфігурація — 4 vCPU, 8 ГБ RAM, 100 ГБ NVMe та канал від 100 Мбіт/с. Такий сервер витримає Docker-збирання API, фронтенду та базові інтеграційні тести. За потреби можна взяти VPS із зазначеними характеристиками або підібрати конфігурацію в іншого провайдера зі швидким NVMe-диском.

Чому важливий обсяг диска

Docker не видаляє невикористовувані образи, build cache, зупинені контейнери та volumes автоматично. У CI диск зазвичай закінчується раніше за CPU. Один образ із кількома шарами може займати 1–3 ГБ, а кеш залежностей Node.js, Maven, Gradle або Cargo — ще десятки гігабайтів.

Залишайте щонайменше 20–30% вільного місця. Для Docker корисно регулярно виконувати docker system prune, але не запускайте агресивне очищення під час build: воно може видалити потрібні образи або кеш активного завдання.

Коли потрібен dedicated, а не VPS

VPS достатньо для більшості проєктів з одним runner і послідовними job. Dedicated-сервер варто обирати, коли потрібна гарантована продуктивність CPU та диска, одночасно працюють кілька runner, збираються важкі Android-проєкти, великі Docker-образи або виконуються ресурсоємні тести.

Також dedicated виправданий, якщо CI обробляє конфіденційний код, ключі підпису релізів, великі бази тестових даних або постійно виконує високе навантаження. На виділеному сервері простіше передбачити продуктивність і зменшити вплив сусідніх віртуальних машин на storage I/O.

Локація VPS

Локація впливає насамперед на затримку до GitHub, Docker Registry, package registry і цільових серверів деплою. Якщо runner збирає образи та надсилає їх у registry в Європі, європейська локація зазвичай зменшить час завантаження. Якщо runner деплоїть сервіс на сервер у конкретному регіоні, розміщуйте його ближче до production-інфраструктури.

Для звичайних тестів різниця в географії менш критична, ніж швидкість NVMe та стабільність каналу. Але якщо workflow часто завантажує залежності обсягом кілька гігабайтів, перевіряйте включений трафік і пропускну здатність порту.

Підготовка сервера

Далі використовується Ubuntu Server 24.04 LTS x86_64. На момент налаштування у 2026 році це стабільна LTS-гілка з підтримкою безпеки. Команди виконуються від імені початкового адміністратора з правами root або sudo. Замінюйте значення в кутових дужках на свої, але не вводьте самі символи < і >.

Оновіть операційну систему

Спочатку встановіть усі доступні патчі. Після оновлення ядра VPS знадобиться перезавантаження. Перевірити необхідність можна за файлом /var/run/reboot-required.

# Обновляет индекс пакетов и устанавливает актуальные обновления Ubuntu.
sudo apt update && sudo apt full-upgrade -y

# Удаляет больше не нужные зависимости и очищает локальный кэш APT.
sudo apt autoremove --purge -y && sudo apt clean

# Перезагружает сервер, если обновилось ядро или системные библиотеки.
sudo reboot

Створіть окремого адміністратора

Не використовуйте root для постійної роботи. Створіть користувача, який виконуватиме адміністративні завдання. Runner пізніше отримає окремий обліковий запис без інтерактивного пароля.

# Создаёт пользователя deployadmin с домашним каталогом и запросом пароля.
sudo adduser deployadmin

# Добавляет пользователя в группу sudo для административных команд.
sudo usermod -aG sudo deployadmin

# Проверяет, что пользователь получил нужные группы.
id deployadmin

Додайте свій публічний SSH-ключ до файлу /home/deployadmin/.ssh/authorized_keys. Якщо ви вже підключені як root і ваш ключ є в /root/.ssh/authorized_keys, його можна скопіювати.

# Создаёт каталог SSH и задаёт безопасные права доступа.
sudo install -d -m 700 -o deployadmin -g deployadmin /home/deployadmin/.ssh

# Копирует существующие авторизованные ключи root новому администратору.
sudo cp /root/.ssh/authorized_keys /home/deployadmin/.ssh/authorized_keys

# Выставляет владельца и права файла с публичными ключами.
sudo chown deployadmin:deployadmin /home/deployadmin/.ssh/authorized_keys
sudo chmod 600 /home/deployadmin/.ssh/authorized_keys

Відкрийте другу SSH-сесію та переконайтеся, що можете увійти як deployadmin за ключем. Лише після цього вимикайте root-login і парольну автентифікацію. Помилка на цьому етапі може позбавити доступу до VPS.

Посильте налаштування SSH

Створіть окремий конфігураційний файл. Ubuntu OpenSSH читає файли з каталогу /etc/ssh/sshd_config.d/, тому не потрібно редагувати основний файл і конфліктувати з оновленнями пакета.

# Создаёт отдельную конфигурацию SSH: root и вход по паролю будут отключены.
sudo tee /etc/ssh/sshd_config.d/99-hardening.conf > /dev/null <<'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
X11Forwarding no
MaxAuthTries 3
LoginGraceTime 30
EOF

# Проверяет синтаксис конфигурации до перезапуска SSH.
sudo sshd -t

# Применяет безопасные параметры SSH без остановки активных сессий.
sudo systemctl reload ssh

Встановіть базові утиліти, firewall і Fail2ban

GitHub runner не потребує вхідного порту. Для адміністрування залиште лише SSH. Якщо ви змінювали SSH-порт, дозвольте в UFW саме його. Перед увімкненням firewall перевірте, що поточний IP не блокується зовнішнім мережевим firewall провайдера.

# Устанавливает инструменты диагностики, firewall, Fail2ban и средства работы с архивами.
sudo apt install -y curl wget ca-certificates gnupg lsb-release jq unzip \
  git htop tmux ufw fail2ban ncdu

# Запрещает входящие соединения и разрешает исходящие.
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Разрешает SSH для удалённого администрирования.
sudo ufw allow OpenSSH

# Включает firewall и показывает действующие правила.
sudo ufw --force enable
sudo ufw status verbose

Fail2ban відстежує логи SSH і тимчасово банить IP-адреси з повторними невдалими спробами входу. Він не замінює SSH-ключі та firewall, але зменшує шум від автоматичних сканерів.

# Включает Fail2ban при загрузке и запускает его немедленно.
sudo systemctl enable --now fail2ban

# Показывает состояние SSH-jail и число заблокированных адресов.
sudo fail2ban-client status sshd

Увімкніть автоматичні оновлення безпеки

Автоматичні security-updates корисні для базового захисту VPS. Однак оновлення Docker або ядра може вимагати перезапуску сервісів. Для критичного production-runner краще вибрати фіксоване maintenance window і тестувати оновлення на окремій машині.

# Устанавливает механизм автоматического применения обновлений безопасности Ubuntu.
sudo apt install -y unattended-upgrades

# Запускает интерактивную настройку автоматических security-updates.
sudo dpkg-reconfigure --priority=low unattended-upgrades

Встановлення ПЗ — покроково

Для self-hosted runner буде встановлено Docker Engine з офіційного репозиторію Docker і GitHub Actions Runner з офіційних GitHub Releases. Не використовуйте пакет docker.io зі стандартного Ubuntu-репозиторію, якщо вам потрібна передбачувана свіжа версія Docker Engine: офіційний репозиторій Docker зазвичай оновлюється швидше.

Встановіть Docker Engine

У 2026 році орієнтуйтеся на актуальну стабільну гілку Docker Engine 27.x або новішу, доступну для Ubuntu 24.04. Команди нижче додають офіційний ключ і репозиторій, після чого APT встановить актуальний stable-пакет.

# Создаёт каталог для ключей репозиториев APT.
sudo install -m 0755 -d /etc/apt/keyrings

# Загружает и сохраняет официальный GPG-ключ Docker.
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Разрешает APT читать ключ Docker всем пользователям.
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Добавляет официальный stable-репозиторий Docker для текущей архитектуры Ubuntu.
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Обновляет индекс пакетов после добавления нового репозитория.
sudo apt update

# Устанавливает Docker Engine, CLI, Buildx и Docker Compose v2.
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Включает Docker при загрузке и запускает daemon сейчас.
sudo systemctl enable --now docker

# Проверяет версии Docker Engine, Compose и Buildx.
docker --version
docker compose version
docker buildx version

Поки команда docker ps від звичайного користувача видаватиме помилку доступу — це нормально. Runner запускатиметься від окремого користувача ghrunner, якого ми свідомо додамо до групи docker.

Членство в групі docker еквівалентне широким root-привілеям на сервері. Не додавайте туди звичайних користувачів і не дозволяйте недовіреним workflow виконуватися на цьому runner.

Створіть системного користувача runner

Для агента не потрібні пароль та інтерактивний SSH-вхід. Окремий системний користувач спрощує аудит файлів, логів і дозволів. Домашнім каталогом буде /opt/actions-runner.

# Создаёт системную учётную запись ghrunner без пароля и с домашним каталогом runner.
sudo useradd --system --create-home --home-dir /opt/actions-runner \
  --shell /usr/sbin/nologin ghrunner

# Даёт runner доступ к Docker daemon для контейнерных workflow.
sudo usermod -aG docker ghrunner

# Проверяет UID, домашний каталог и группы нового пользователя.
id ghrunner
getent passwd ghrunner

Завантажте актуальний GitHub Actions Runner

GitHub регулярно випускає оновлення runner 2.x. Замість жорстко зафіксованого номера команда нижче отримує останню стабільну версію для архітектури x64 через офіційний GitHub API. Це зменшує ризик встановити застарілий агент. Для ARM64 замініть фільтр linux-x64 на linux-arm64.

# Получает URL последнего официального релиза runner для Linux x64.
RUNNER_URL=$(curl -fsSL https://api.github.com/repos/actions/runner/releases/latest \
  | jq -r '.assets[] | select(.name | test("actions-runner-linux-x64-[0-9.]+\\.tar\\.gz$")) | .browser_download_url')

# Показывает найденный URL; он не должен быть пустым.
echo "$RUNNER_URL"

# Скачивает архив runner в домашний каталог системного пользователя.
sudo -u ghrunner curl -fL "$RUNNER_URL" -o /opt/actions-runner/actions-runner.tar.gz

# Распаковывает runner и удаляет архив после успешной распаковки.
sudo -u ghrunner tar xzf /opt/actions-runner/actions-runner.tar.gz \
  -C /opt/actions-runner
sudo -u ghrunner rm /opt/actions-runner/actions-runner.tar.gz

У релізах GitHub зазвичай публікуються контрольні суми. Для середовища з підвищеними вимогами завантажте файл checksums з тієї самої сторінки release і перевірте SHA-256 перед розпакуванням. Це особливо важливо, якщо VPS розташований у недовіреній мережі або пакет завантажується через корпоративний proxy.

Встановіть залежності runner

Скрипт installdependencies.sh встановлює системні бібліотеки, необхідні агенту. Запускайте його через sudo, потім переконайтеся, що каталог runner належить ghrunner.

# Устанавливает системные библиотеки, требуемые GitHub Actions Runner.
cd /opt/actions-runner
sudo ./bin/installdependencies.sh

# Возвращает владение рабочими файлами агенту после установки зависимостей.
sudo chown -R ghrunner:ghrunner /opt/actions-runner

# Показывает версию установленного runner.
sudo -u ghrunner /opt/actions-runner/bin/Runner.Listener --version

Перевірте Docker від імені runner

Ця перевірка критична. Якщо Docker працює в адміністратора, але недоступний користувачу ghrunner, workflow з контейнерами та docker build завершаться помилкою permission denied.

# Проверяет, что пользователь runner видит Docker daemon и может запустить тестовый контейнер.
sudo -u ghrunner docker run --rm hello-world

# Показывает место, занятое образами, контейнерами, volumes и build cache.
sudo docker system df

Резервні копії та обслуговування

GitHub Actions runner не містить основної бізнес-бази даних: вихідний код зберігається в GitHub, workflow — у репозиторії, а GitHub Secrets не вивантажуються на VPS як постійна конфігурація. Тому бекап runner простіший, ніж бекап GitLab або Jenkins. Однак потрібно зберегти документацію, локальні конфігурації, scripts деплою, systemd overrides і дані, створені вашими workflow.

Що потрібно і не потрібно бекапити

Резервне копіювання через restic у S3

Restic створює дедупліковані зашифровані бекапи. Як сховище можна використовувати S3-compatible storage, окремий backup VPS через SFTP або інший віддалений backend. Нижче використовується S3. Не зберігайте пароль репозиторію restic у shell history і не додавайте його до Git.

# Встановлює restic з репозиторію Ubuntu.
sudo apt install -y restic

# Створює закритий каталог для змінних резервного копіювання.
sudo install -d -m 700 -o root -g root /etc/restic

# Створює файл середовища з S3-обліковими даними та паролем шифрування.
sudoedit /etc/restic/runner-backup.env

# Обмежує доступ до файлу із секретами лише користувачем root.
sudo chmod 600 /etc/restic/runner-backup.env

Файл /etc/restic/runner-backup.env повинен мати такий вигляд. Використовуйте окремого S3-користувача з доступом лише до backup bucket. Пароль RESTIC_PASSWORD має бути довгим і також зберігатися в менеджері паролів: без нього відновити дані неможливо.

export RESTIC_REPOSITORY="s3:https://s3.example.net/ci-runner-backup"
export AWS_ACCESS_KEY_ID="CHANGE_ME"
export AWS_SECRET_ACCESS_KEY="CHANGE_ME"
export RESTIC_PASSWORD="CHANGE_ME_TO_A_LONG_UNIQUE_PASSWORD"

Ініціалізуйте порожній репозиторій один раз. Потім створіть скрипт, який архівує лише потрібні каталоги та виключає registration credentials runner.

# Ініціалізує новий зашифрований restic-репозиторій у віддаленому S3-сховищі.
sudo bash -c 'source /etc/restic/runner-backup.env && restic init'

# Створює сценарій щоденного резервного копіювання конфігурацій і локальних даних.
sudo tee /usr/local/sbin/backup-ci-runner.sh > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

source /etc/restic/runner-backup.env

restic backup \
  /etc/systemd/system \
  /etc/my-app \
  /usr/local/sbin \
  /opt/actions-runner \
  --exclude=/opt/actions-runner/_work \
  --exclude=/opt/actions-runner/.credentials \
  --exclude=/opt/actions-runner/.credentials_rsaparams \
  --exclude=/opt/actions-runner/.runner \
  --tag ci-runner

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune
restic check
EOF

# Робить скрипт доступним для запуску лише root.
sudo chmod 700 /usr/local/sbin/backup-ci-runner.sh

Перед додаванням у cron виконайте резервне копіювання вручну та перевірте знімки. Перший запуск може бути тривалим, наступні передаватимуть лише змінені блоки.

# Створює перший backup і одночасно перевіряє доступність віддаленого сховища.
sudo /usr/local/sbin/backup-ci-runner.sh

# Показує список створених snapshots без розкриття вмісту секретів.
sudo bash -c 'source /etc/restic/runner-backup.env && restic snapshots'

# Відкриває root-crontab для додавання розкладу.
sudo crontab -e

Додайте в root-crontab рядок для щоденного запуску о 03:20. Лог корисний під час розслідування помилок, але не має бути єдиним індикатором: налаштуйте зовнішній моніторинг або сповіщення про невдалий backup.

# Запускає backup щодня о 03:20 і записує stdout/stderr в окремий лог.
20 3    /usr/local/sbin/backup-ci-runner.sh >> /var/log/backup-ci-runner.log 2>&1

# Створює тимчасовий каталог для перевірки відновлення.
sudo mkdir -p /root/restore-test

# Відновлює останній snapshot у тестовий шлях, не зачіпаючи робочу систему.
sudo bash -c 'source /etc/restic/runner-backup.env && restic restore latest --target /root/restore-test'

# Виводить перші рівні відновленого дерева для швидкої перевірки.
sudo find /root/restore-test -maxdepth 3 -type f | head -50

# Показує поточний статус runner перед плановим обслуговуванням.
sudo systemctl status 'actions.runner.' --no-pager

# Встановлює доступні оновлення ОС і Docker через APT.
sudo apt update && sudo apt upgrade -y

# Перевіряє версії runner і Docker після обслуговування.
sudo -u ghrunner /opt/actions-runner/bin/Runner.Listener --version
docker --version

Регулярно перевіряйте вільне місце, активні контейнери та помилки сервісу. Мінімальний щотижневий набір перевірок: df -h, docker system df, systemctl status, journalctl і статус runner у GitHub.

Усунення несправностей + FAQ

Чому runner відображається як Offline у GitHub?

Спочатку перевірте systemd: sudo systemctl status 'actions.runner.'. Потім перегляньте журнал через sudo journalctl -u 'actions.runner.' -n 100 --no-pager. Часті причини: сервіс не встановлено після реєстрації, VPS не має вихідного доступу на 443/tcp, неправильно налаштований proxy або системний час сильно відрізняється від реального. Перевірте timedatectl і curl -I https://api.github.com. Якщо credentials пошкоджено, видаліть runner в інтерфейсі GitHub і зареєструйте його повторно з новим одноразовим токеном.

Workflow зависає в черзі та не призначається на runner. Що перевірити?

Порівняйте labels у workflow і labels, показані в розділі GitHub Actions Runners. Job з runs-on: [self-hosted, linux, docker] чекатиме нескінченно, якщо runner не має хоча б однієї з цих міток або зайнятий іншим завданням. Також перевірте, чи дозволений runner для цього репозиторію, чи не перебуває він в іншій runner group і чи не увімкнені обмеження організації. Для діагностики тимчасово використовуйте runs-on: self-hosted, а потім поверніть точні labels.

Чому Docker у workflow видає permission denied під час підключення до /var/run/docker.sock?

Runner запущено користувачем ghrunner, якому потрібен доступ до групи docker. Виконайте id ghrunner: у виводі має бути група docker. Якщо її немає, додайте користувача командою sudo usermod -aG docker ghrunner, потім перезапустіть сервіс runner. Перевірте sudo -u ghrunner docker ps. Не виправляйте проблему командою chmod 666 /var/run/docker.sock: це небезпечно і зазвичай тимчасово.

На VPS закінчилося місце під час docker build. Як звільнити диск?

Спочатку визначте джерело: df -h, sudo docker system df -v і sudo du -sh /opt/actions-runner/_work. Після завершення всіх job видаліть невикористовувані Docker-дані через sudo docker system prune -af. Якщо volumes не потрібні, можна додати --volumes, але це видалить невикористовувані томи та може пошкодити локальний застосунок. Для постійного навантаження збільште диск, обмежте розмір артефактів і винесіть registry або кеш в окреме сховище.

Чи можна використовувати self-hosted runner для public repository?

Технічно можна, але постійний runner із Docker і секретами не можна надавати недовіреному коду. У public repository зовнішні учасники можуть відкрити pull request із workflow або кодом, який спробує прочитати файли, викрасти токени, змінити Docker-образи або закріпитися на сервері. Для публічних pull request використовуйте GitHub-hosted runner. Якщо self-hosted обов’язковий, створюйте ephemeral runner для кожної job, ізолюйте його в окремій VM і не надавайте йому доступу до production-мережі, Docker socket і чутливих секретів.

Яка VPS-конфігурація мінімально підійде?

Мінімум для невеликого private-проєкту — 2 vCPU, 4 ГБ RAM, 40 ГБ SSD і стабільний вихідний доступ до інтернету. Такої конфігурації достатньо для лінтингу, unit-тестів і легких Node.js або Python-збірок. Якщо workflow використовує Docker Compose, PostgreSQL, Redis і збірку образу, практичніше одразу обрати 4 vCPU, 8 ГБ RAM і 80–100 ГБ NVMe. Стежте за docker system df: розмір диска в CI важливіший, ніж здається під час першого запуску.

Що обрати — VPS чи dedicated для цього завдання?

Для одного runner і звичайного вебпроєкту обирайте VPS: він дешевший, швидше розгортається та легко масштабується зміною тарифу. Dedicated потрібен за постійних важких збірок, кількох паралельних runner, вимог до стабільного CPU і NVMe I/O, роботи з великими базами й артефактами або підвищених вимог до ізоляції. Почніть із VPS і виміряйте тривалість job, споживання RAM, навантаження CPU та вільне місце. Перехід на dedicated має сенс, коли ресурси VPS стають систематичним вузьким місцем.

Чи потрібно відкривати 80, 443 або налаштовувати Caddy для GitHub Actions Runner?

Ні. Runner сам створює вихідні HTTPS-з’єднання з GitHub, тому вхідні HTTP/HTTPS-порти йому не потрібні. Залиште закритими 80 і 443, якщо на VPS немає окремого вебсервісу. Caddy або Certbot потрібні лише коли цей самий сервер публікує застосунок, registry, dashboard або інший HTTP-сервіс. Для runner достатньо вихідного 443/tcp, коректного DNS і синхронізованого часу. Такий підхід безпечніший: сервер не має зайвої публічної мережевої поверхні.

Чому job після завершення залишає файли й контейнери?

На відміну від GitHub-hosted VM, self-hosted runner є постійним. GitHub очищає деякі службові дані job, але Docker-образи, build cache, volumes, частина checkout і тимчасові файли можуть залишатися на диску. Це прискорює повторні збірки, але потребує обслуговування. Додайте cleanup-step у workflow для чутливих даних, установіть ліміти на артефакти та запускайте планове очищення Docker у вільне вікно. Не видаляйте робочий каталог, поки є активні job: це призведе до непередбачуваних помилок збірки.

Висновки та наступні кроки

Тепер на VPS працює GitHub Actions self-hosted runner із Docker, systemd, firewall і базовою стратегією резервного копіювання. Він може виконувати CI/CD workflow, збирати контейнери, тестувати код і деплоїти застосунки без потреби відкривати вхідні порти для самого агента.

1. Створіть окремі labels і runner groups для CI, staging і production, щоб production-job не виконувалися на звичайній машині розробки.
2. Додайте моніторинг диска, пам’яті, статусу systemd та успішності бекапів; CI найчастіше ламається через заповнене Docker-сховище.
3. Зі зростанням навантаження розподіліть завдання між кількома runner або перейдіть на ephemeral runners для недовірених і публічних workflow.