Git-деплой подключает репозиторий к сайту так, что каждый пуш в выбранную ветку клонирует код, запускает вашу сборку и публикует результат. Это руководство охватывает первоначальное подключение, два шага на стороне репозитория, завершающие настройку, чтение истории развёртываний и определение buildpack, которое решает, как собирается приложение на Node.js.
Где находится Git-деплой
Откройте раздел Сайты, нажмите на сайт, откройте группу Окружение в левом меню сайта и выберите Git-деплой. Рядом находятся две связанные страницы:
- Развёртывания, полная история развёртываний для этого сайта, в той же группе Окружение.
- Buildpack, определённая стратегия сборки, для сайтов на Node.js, в группе Приложения.
Страница Git-деплоя прямо объясняет своё назначение: подключите репозиторий, и каждый пуш в настроенную ветку запускает сборку и развёртывание.
Подключение репозитория
- Выберите Провайдера: GitHub, GitLab или Bitbucket.
- Введите URL репозитория. Вам нужна форма SSH, например
git@github.com:user/repo.git. - Укажите Ветку, из которой будет выполняться развёртывание. По умолчанию в поле указано
main. - При необходимости укажите Команду сборки, например
npm run build. - При необходимости укажите Выходной каталог, например
dist,publicили.для репозитория, который уже собран. - Нажмите Подключить репозиторий.
Оставьте команду сборки и выходной каталог пустыми, если ваш репозиторий уже готов к развёртыванию в текущем виде, что обычно верно для простого сайта на PHP или статического сайта.
Дополнительные скрипты
Разворачивая раздел Дополнительно, вы увидите два дополнительных поля:
- Скрипт перед развёртыванием, который выполняется перед сборкой.
- Скрипт после развёртывания, который выполняется после развёртывания.
Используйте хук после развёртывания для действий, которые обязательно должны произойти после появления нового кода: очистка кеша приложения, выполнение миграции базы данных, перезапуск воркера.
Автоматическое развёртывание при пуше
Переключатель внизу карточки управляет тем, вызывают ли пуши развёртывание вообще. Когда он включён, каждый пуш в настроенную ветку запускает развёртывание. Когда он выключен, развёртывания выполняются только тогда, когда вы запускаете их вручную кнопкой Развернуть сейчас.
Отключайте автоматическое развёртывание во время заморозки кода или инцидента, вместо того чтобы отключать репозиторий. Отключение репозитория приводит к удалению ключа развёртывания и секрета webhook, поэтому оба шага на стороне репозитория придётся выполнять заново.
Завершение настройки в вашем репозитории
Подключение репозитория в KPanel это лишь первый из трёх шагов. Пока не выполнено ни одно развёртывание, страница показывает баннер с надписью Завершить настройку: осталось 2 шага и всем необходимым для этого.
Шаг 2: добавьте ключ развёртывания
KapsuleHost нужен доступ на чтение, чтобы клонировать ваш репозиторий. Баннер показывает публичный ключ с кнопкой Скопировать ключ.
Вставьте его в ключи развёртывания вашего репозитория. Для GitHub баннер предлагает кнопку быстрого перехода Добавить на GitHub прямо на нужную страницу настроек. Достаточно доступа на чтение, не выдавайте доступ на запись.
Шаг 3: добавьте webhook
Webhook сообщает KapsuleHost о том, что произошёл пуш. Баннер показывает три значения:
| Поле | Значение |
|---|---|
| URL полезной нагрузки | URL, заканчивающийся на /api/git-deploy/webhook/ плюс идентификатор этого сайта |
| Секрет | Сгенерированный секрет подписи, скрытый до нажатия на значок «глаз» |
| Тип содержимого | application/json |
Скопируйте каждое значение в настройки webhook вашего репозитория. Для GitHub есть кнопка быстрого перехода Добавить webhook на GitHub. Установите тип содержимого JSON, а не значение по умолчанию с кодировкой формы, иначе полезная нагрузка не будет разобрана.
Относитесь к секрету webhook как к паролю. Любой, у кого есть этот секрет и URL полезной нагрузки, может запустить развёртывание вашего сайта. Оба значения показываются только тем, кто уже может администрировать сайт, а секрет остаётся скрытым за значком «глаз», пока вы его не запросите.
Развёртывание вручную
Нажмите Развернуть сейчас на странице Git-деплоя, чтобы собрать и развернуть текущую вершину настроенной ветки без пуша коммита. Это работает независимо от того, включено ли автоматическое развёртывание, именно поэтому это подходящий инструмент во время заморозки: пуши игнорируются, но вы всё равно можете выпустить исправление.
Чтение истории развёртываний
Откройте Окружение, затем Развёртывания. Страница называется История развёртываний и перечисляет каждое развёртывание, запущенное webhook'ом или вручную, начиная с самого нового.
Каждая строка содержит:
- Значок статуса и короткий хеш коммита SHA, с веткой в виде метки.
- Сообщение коммита или Ручное развёртывание, если сообщения коммита не было.
- Автора, сколько времени прошло, сколько времени это заняло и что вызвало запуск.
- Метку статуса.
Статусы: ожидание, сборка, развёртывание, успех и ошибка. Пока что-то выполняется, страница обновляется автоматически каждые пять секунд и показывает под таблицей примечание Автоматическое обновление, так что можно оставить страницу открытой и наблюдать за ходом развёртывания.
Когда развёртывание завершается неудачей
У неудачной строки справа появляется кнопка Ошибка. Нажмите на неё, чтобы развернуть захваченный вывод ошибки прямо здесь, не покидая страницу. Этот вывод это собственный текст ошибки сборки, поэтому обычно в нём указан файл или команда, которые привели к сбою.
Разбирайтесь в таком порядке: прочитайте ошибку, воспроизведите ту же команду сборки локально, исправьте, запушьте. Если сборка работает локально, но не здесь, разница почти всегда связана с окружением: это либо отсутствующая зависимость, установленная глобально на вашей машине, либо файл, который есть в вашей рабочей директории, но не закоммичен.
Определение buildpack
На сайтах с Node.js страница Buildpack в группе Приложения показывает, как KapsuleHost решил собирать ваше приложение. Определение выполняется по файлам в корне вашего репозитория, и побеждает первое совпадение:
| Определено | Триггер |
|---|---|
| Пользовательский buildpack | kapsule.config.yaml или kapsule.config.yml в корне |
| Buildpack Dockerfile | Dockerfile в корне |
| Node.js | package.json со скриптом start, build или dev |
| Python | requirements.txt или pyproject.toml |
| PHP | composer.json |
| Статический сайт | index.html в корне |
Если ничего не совпадает, страница сообщает об этом и перечисляет поддерживаемые триггеры. Добавьте Dockerfile или kapsule.config.yaml, чтобы взять управление сборкой под явный контроль.
Запуск сборки
Нажмите Запустить сборку, чтобы поставить её в очередь. Страница опрашивает сервер каждые три секунды, пока выполняется запуск, а таблица Последние сборки показывает последние запуски с временем начала, типом, статусом, продолжительностью и получившейся ссылкой на образ. Нажмите на строку, чтобы увидеть хвост её лога.
Одновременно может выполняться только одна сборка. Попытка запустить вторую, пока одна уже в очереди или выполняется, отклоняется с сообщением Сборка уже выполняется, и это сделано намеренно: две сборки, одновременно записывающие один и тот же результат, это верный способ получить наполовину развёрнутый сайт.
Отключение
Нажмите Отключить и подтвердите. Подтверждение явно объясняет последствия: конфигурация Git-деплоя и ключ развёртывания удаляются, а файлы вашего сайта не затрагиваются. Сайт продолжает обслуживать то, что было развёрнуто последним.
После этого наведите порядок, удалив ключ развёртывания и webhook в настройках вашего репозитория. Они просто перестанут работать, но оставленные «мёртвые» записи усложняют следующую проверку.
Решение проблем
Пуши ничего не вызывают. Сначала проверьте переключатель автоматического развёртывания, затем webhook в вашем репозитории. Большинство провайдеров показывают последние доставки и их коды ответа, что сразу покажет, покинул ли запрос ваш репозиторий вообще.
Клонирование не удаётся. Ключ развёртывания отсутствует, был вставлен с переносом строки внутри, либо был добавлен не в тот репозиторий. Скопируйте его заново кнопкой Скопировать ключ, а не выделением текста вручную.
Развёртывание проходит успешно, но сайт не меняется. Скорее всего, неверно указан выходной каталог. Если ваша сборка записывает результат в dist, а выходной каталог не указан, собранные файлы никогда не попадут в корень, который обслуживается сайтом.
Всё показывает «ожидание» и ничего не меняется. Развёртывание было поставлено в очередь, но так и не было подхвачено. Запустите Развернуть сейчас вручную и проверьте страницу «Развёртывания» на наличие строки с ошибкой.
Куда двигаться дальше
- Предпросмотр развёртываний для pull request'ов добавляет отдельный URL для каждого PR поверх этой настройки.
- Хранение секретов приложения для сайта для учётных данных, которые нужны вашей сборке и среде выполнения.
- Журнал активности сайта фиксирует изменения конфигурации, сделанные здесь.