К содержимому

git pull submodules при деплое Laravel на VPS

Подмодули не обновляются сами при git pull: их нужно тянуть отдельной командой git submodule update --init --recursive. На чистом сервере Ubuntu 24.04 это делают сразу после клонирования, до composer install и сборки фронтенда.

Руководство Деплой 3 мин чтения

01Подготовьте каталог и ключ для приватного репозитория

Создайте каталог сайта и передайте его пользователю, который деплоит. Приватный репозиторий клонируют по SSH-ключу этого пользователя: публичный ключ добавляют в GitHub как deploy key. Проверьте доступ командой ssh -T git@github.com, она должна ответить приветствием с вашим логином.

bash
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 упадёт на отсутствующих файлах.

bash
git clone --recurse-submodules git@github.com:user/app.git /var/www/example.com

03Обновите код и подмодули при следующем деплое

При каждом деплое сначала забирают изменения основной ветки, затем синхронизируют подмодули с зафиксированными в репозитории коммитами. Команда git submodule update --init --recursive подтягивает новые подмодули и обновляет вложенные. Флаг --remote не нужен: он уводит подмодуль с зафиксированного коммита на последний в ветке.

bash
cd /var/www/example.com
git pull origin main
git submodule update --init --recursive

04Установите зависимости и соберите фронтенд

Зависимости ставят без dev-пакетов и с оптимизированным автозагрузчиком. Сборку фронтенда запускают после установки npm-пакетов. Обе команды выполняйте от владельца проекта, без sudo.

bash
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 на весь сайт не применяют.

bash
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 кэширует конфиг, маршруты, события и шаблоны. После этого перезапустите обработчики очереди, чтобы они подхватили новый код.

bash
cd /var/www/example.com
php artisan migrate --force
php artisan optimize
php artisan queue:restart

07Проверьте, что подмодули и сайт работают

Сверьте состояние подмодулей: у каждого должен быть коммит без минуса в начале строки. Откройте сайт в браузере и посмотрите свежие записи в логе Laravel. Если страница отдаёт 500, причина будет в storage/logs/laravel.log.

bash
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 в каталоге проекта. Строка, которая начинается с минуса, значит, что подмодуль не инициализирован, плюс значит расхождение с зафиксированным коммитом.

Ещё по теме

Деплой Laravel на сервер: команды, конфиг и ошибки: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.