git pull submodules при деплое Laravel на VPS
Подмодули не обновляются сами при git pull: их нужно тянуть отдельной командой git submodule update --init --recursive. На чистом сервере Ubuntu 24.04 это делают сразу после клонирования, до composer install и сборки фронтенда.
01Подготовьте каталог и ключ для приватного репозитория
Создайте каталог сайта и передайте его пользователю, который деплоит. Приватный репозиторий клонируют по SSH-ключу этого пользователя: публичный ключ добавляют в GitHub как deploy key. Проверьте доступ командой ssh -T git@github.com, она должна ответить приветствием с вашим логином.
sudo mkdir -p /var/www/example.com
sudo chown $USER:www-data /var/www/example.com
ssh -T git@github.com
02Клонируйте репозиторий с подмодулями
Клонируйте проект в каталог сайта. Ключ --recurse-submodules заставляет git сразу инициализировать и скачать все подмодули, прописанные в .gitmodules. Без него каталоги подмодулей останутся пустыми, и composer install упадёт на отсутствующих файлах.
git clone --recurse-submodules git@github.com:user/app.git /var/www/example.com
03Обновите код и подмодули при следующем деплое
При каждом деплое сначала забирают изменения основной ветки, затем синхронизируют подмодули с зафиксированными в репозитории коммитами. Команда git submodule update --init --recursive подтягивает новые подмодули и обновляет вложенные. Флаг --remote не нужен: он уводит подмодуль с зафиксированного коммита на последний в ветке.
cd /var/www/example.com
git pull origin main
git submodule update --init --recursive
04Установите зависимости и соберите фронтенд
Зависимости ставят без dev-пакетов и с оптимизированным автозагрузчиком. Сборку фронтенда запускают после установки npm-пакетов. Обе команды выполняйте от владельца проекта, без sudo.
cd /var/www/example.com
composer install --no-dev --optimize-autoloader
npm ci
npm run build
05Выдайте права на storage и bootstrap/cache
Владельцем файлов проекта остаётся пользователь, который деплоит. www-data пишет только в storage и bootstrap/cache, доступ дают через группу. Остальные файлы www-data только читает, поэтому chown -R www-data:www-data на весь сайт не применяют.
cd /var/www/example.com
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache
06Примените миграции и соберите кэши
При APP_ENV=production миграции запускают с --force, иначе команда ждёт подтверждения. Затем php artisan optimize кэширует конфиг, маршруты, события и шаблоны. После этого перезапустите обработчики очереди, чтобы они подхватили новый код.
cd /var/www/example.com
php artisan migrate --force
php artisan optimize
php artisan queue:restart
07Проверьте, что подмодули и сайт работают
Сверьте состояние подмодулей: у каждого должен быть коммит без минуса в начале строки. Откройте сайт в браузере и посмотрите свежие записи в логе Laravel. Если страница отдаёт 500, причина будет в storage/logs/laravel.log.
cd /var/www/example.com
git submodule status
tail -n 50 storage/logs/laravel.log
Частые ошибки
-
После
git pullкаталоги подмодулей пустые, иcomposer installпадает на отсутствующих файлах.Выполните
git submodule update --init --recursiveв каталоге проекта. При первом клонировании используйтеgit clone --recurse-submodules. -
error: cannot open .git/FETCH_HEAD: Permission deniedприgit pull.Файлы репозитория принадлежат другому пользователю, обычно после
sudo git cloneилиchown -R www-dataна весь проект. Верните владельца:sudo chown -R $USER:www-data /var/www/example.com. -
git@github.com: Permission denied (publickey).при клонировании или обновлении подмодуля.У пользователя, который делает
git pull, нет ключа, добавленного в GitHub. Проверьтеssh -T git@github.comот этого пользователя и добавьте его публичный ключ как deploy key. -
file_put_contents(/var/www/example.com/bootstrap/cache/packages.php): Failed to open stream: Permission denied.Команду запустил пользователь без записи в
bootstrap/cache, обычно послеchown www-data:www-dataна этот каталог. Верните группу:sudo chown -R $USER:www-data bootstrap/cache.
Deploykin
Как это делается в Deploykin
В Deploykin репозиторий GitHub подключается к сайту из панели, и после каждого пуша панель сама запускает деплой с миграциями и кэшами. git pull по SSH не нужен.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Почему git pull не обновляет подмодули?
git pull обновляет только основную ветку и записывает новые коммиты подмодулей. Сами файлы подмодулей подтягивает отдельная команда git submodule update --init --recursive.
Чем отличается git submodule update от git submodule update --remote?
Без флагов подмодуль переходит на коммит, зафиксированный в основном репозитории. С --remote он переходит на последний коммит ветки, указанной в .gitmodules, и состояние расходится с тем, что проверяли разработчики.
Нужно ли запускать git submodule update с sudo?
Нет. Команду запускают от владельца проекта, иначе новые файлы подмодулей достанутся root, и следующий git pull упадёт с Permission denied.
Как проверить, что все подмодули на месте?
Выполните git submodule status в каталоге проекта. Строка, которая начинается с минуса, значит, что подмодуль не инициализирован, плюс значит расхождение с зафиксированным коммитом.
Ещё по теме
- Руководство · Деплой Как развернуть сайт на VPS: Laravel и PHP на Ubuntu 24.04 Пошаговый деплой сайта на VPS: nginx, PHP 8.3, MySQL 8, git clone, composer install, миграции, права на storage и проверка через curl.
- Руководство · Деплой git pull rebase при деплое Laravel на VPS Как включить git pull rebase для деплоя Laravel на VPS: настройка git config, порядок команд, права на storage, проверка через git log и artisan.
- Руководство · Деплой CI CD на Jenkins: деплой Laravel и PHP-сайтов на VPS Пошаговая настройка CI CD на Jenkins для деплоя Laravel и PHP-сайтов на Ubuntu 24.04: команды сборки, права, миграции и проверка результата.
- Руководство · Деплой Как отменить git pull на сервере: пошаговый разбор Как отменить git pull на Ubuntu 24.04: сохранить правки, вернуть коммиты через git reset и git revert, восстановить деплой Laravel и проверить результат.
- Руководство · Деплой git fetch и git pull: различия и деплой Laravel на VPS Чем git fetch отличается от git pull, как настроить деплой Laravel на Ubuntu 24.04: команды, права на storage, nginx и проверка работы сайта.
- Руководство · Деплой Деплой PHP сайта на VPS: от чистого сервера до рабочего сайта Пошаговый деплой PHP-сайта и Laravel на VPS с Ubuntu 24.04: установка nginx, PHP 8.3, MySQL 8, настройка конфига, права и проверка.
Деплой Laravel на сервер: команды, конфиг и ошибки: все материалы темы