Как установить и настроить автодеплой из Git на VPS

MAATRIX

Выкатывать код на сервер вручную через SSH — медленно и чревато ошибками: забыл шаг, перепутал ветку, оставил сервис лежать. Автодеплой из Git на VPS убирает человеческий фактор: вы делаете push в нужную ветку, а сервер сам подтягивает изменения, собирает и перезапускает приложение. Разберём настройку по шагам — от ключей доступа до скрипта выката и отката, чтобы деплой стал предсказуемым и быстрым.

Как устроен автодеплой и какие есть подходы

Суть автодеплоя проста: событие в репозитории (обычно push в определённую ветку) запускает на сервере последовательность действий — забрать свежий код, установить зависимости, собрать проект, перезапустить сервис. Разница между подходами в том, что именно инициирует эту цепочку и где она выполняется.

Первый подход — webhook. Git-платформа при пуше шлёт HTTP-запрос на ваш сервер, где небольшой обработчик запускает скрипт деплоя. Всё происходит на самом целевом сервере, схема простая и не требует внешних раннеров. Второй подход — через CI/CD платформы (GitLab CI, GitHub Actions): пайплайн собирает проект на раннере и затем по SSH выкладывает результат на сервер. Он мощнее, позволяет прогнать тесты перед выкатом, но сложнее в настройке.

Для одного-двух проектов на своём VPS обычно достаточно webhook-подхода или ещё более простой схемы с pull по расписанию. Для командной разработки с тестами и несколькими окружениями оправдан полноценный CI/CD. Ниже разберём надёжный и понятный вариант на основе скрипта деплоя и защищённого доступа к репозиторию, который легко расширить до любого из подходов.

Шаг 1. Подготовка сервера и пользователя

Работаем на Ubuntu 24.04 с root-доступом. Первое правило безопасности — не деплоить и не запускать приложение от root. Заведите отдельного пользователя для деплоя и приложения, чтобы ограничить возможный ущерб при компрометации:

adduser deploy
usermod -aG www-data deploy

Поставьте Git и то, что нужно вашему стеку — например, среду выполнения приложения. Настройте базовую защиту сервера: вход по SSH-ключу, фаервол с открытыми портами приложения. У MAATRIX сервер выдаётся с root и чистым выделенным IP, оплата из России картой, по СБП, криптой или токеном MAAT, так что подготовить окружение под деплой можно с первой минуты, не завися от иностранных платёжек.

Шаг 2. Ключ деплоя для доступа к репозиторию

Серверу нужно право забирать код из приватного репозитория, но давать ему полный доступ к вашему аккаунту небезопасно. Для этого существуют deploy-ключи — отдельная SSH-пара, привязанная к конкретному репозиторию и, как правило, только на чтение. Сгенерируйте ключ под пользователем deploy:

sudo -u deploy ssh-keygen -t ed25519 -f /home/deploy/.ssh/deploy_key

Открытую часть ключа добавьте в настройки репозитория как deploy-ключ с доступом на чтение. Теперь сервер сможет клонировать и обновлять код, но не сможет ничего пушить или лезть в другие репозитории. Это принцип минимальных привилегий в действии: доступ ровно такой, какой нужен для задачи, и ни граммом больше. Проверьте, что клонирование работает под нужным пользователем и ключом, прежде чем идти дальше.

Шаг 3. Первый клон и структура каталогов

Продуманная структура каталогов упрощает и деплой, и откат. Распространённая схема — держать текущую версию по фиксированному пути, куда смотрит веб-сервер, а обновления делать в этом же рабочем каталоге через git pull. Склонируйте репозиторий под пользователем deploy:

sudo -u deploy git clone git@github.com:you/project.git /home/deploy/app

Более продвинутая схема хранит несколько релизов в отдельных папках и переключает символическую ссылку на активный релиз — это позволяет мгновенно откатываться на предыдущую версию. Для старта достаточно простого рабочего каталога, а усложнять структуру стоит, когда появится реальная потребность в быстрых откатах. Главное — чтобы путь, который обслуживает веб-сервер, был отделён от служебных файлов и не отдавал наружу папку .git.

Шаг 4. Скрипт деплоя

Сердце автодеплоя — скрипт, который выполняет всю последовательность выката. Он должен быть идемпотентным и безопасным: если шаг падает, деплой прерывается, а не оставляет сервис в поломанном состоянии. Создайте /home/deploy/deploy.sh:

#!/bin/bash
set -e
cd /home/deploy/app
git pull origin main
# установка зависимостей и сборка под ваш стек
# npm ci && npm run build   или   composer install --no-dev
systemctl restart myapp
echo "Деплой $(date) выполнен"

Строка set -e критична: она прерывает скрипт на первой же ошибке, чтобы не перезапускать сервис с наполовину обновлённым кодом. Сделайте скрипт исполняемым. Продумайте порядок шагов так, чтобы сервис перезапускался только после успешной сборки, а не до неё, — иначе пользователи поймают ошибку во время выката.

Шаг 5. Автоматический запуск по пушу

Теперь свяжем push с запуском скрипта. Простой и надёжный вариант — небольшой обработчик webhook, который слушает запрос от Git-платформы и вызывает скрипт деплоя. Обработчик обязательно должен проверять секрет из настроек webhook, иначе кто угодно сможет инициировать деплой запросом на ваш эндпоинт.

Альтернатива без своего обработчика — пайплайн CI/CD, который после успешной сборки заходит на сервер по SSH и запускает deploy.sh. В этом случае на сервере заводят отдельный ограниченный ключ для CI, а сам деплой-шаг описывают в конфигурации пайплайна. Ещё более простой вариант для некритичных проектов — cron, который раз в несколько минут делает git pull и перезапускает сервис при изменениях. Выбор зависит от того, нужен ли вам мгновенный деплой и прогон тестов перед ним.

Шаг 6. Откат, уведомления и безопасность

Автодеплой без плана отката — риск. Обязательно предусмотрите способ быстро вернуться к рабочей версии, если свежий выкат сломал приложение. В простой схеме это откат на предыдущий коммит и повторный запуск сборки; в схеме с несколькими релизами — переключение ссылки на прошлый релиз. Проверьте откат заранее, а не в момент аварии.

Добавьте уведомления об успешном и неудачном деплое — в мессенджер или почту, чтобы не узнавать о поломке от пользователей. Держите секреты webhook и ключи вне репозитория. И следите за ресурсами: сборка фронтенда или компиляция в момент деплоя нагружает сервер, и если выкаты частые, а VPS слабый, деплой будет тормозить работу приложения. В таком случае разумно либо собирать на отдельном раннере, либо перейти на более мощный сервер. У MAATRIX нарастить конфигурацию можно в любой момент, оплатив из России удобным способом. С продуманным откатом, уведомлениями и защитой доступа автодеплой из Git становится тем, ради чего затевался, — быстрым и спокойным выкатом по одному пушу.

Частые вопросы