Сайты
Развертывание сайта из Git
Git Deploy connects a repository to a site so that every push to your chosen branch clones the code, runs your build, and publishes the result. This guide covers the initial connection, the two…
Место развёртывания Git Deploy
Откройте Websites, нажмите на сайт, откройте меню Advanced на вкладке сайта и выберите Git Deploy. Две связанные страницы находятся в том же меню:
- Deploys, полная история развёртывания для этого сайта.
- Buildpack, обнаруженная стратегия сборки на сайтах Node.js.
На странице Git Deploy описывается само по себе: подключите репозиторий, и каждый push к настроенной ветке запускает сборку и развёртывание.
Подключение репозитория
- Выберите Provider: GitHub, GitLab или Bitbucket.
- Введите Repository URL. Форма SSH, это то, что вам нужно, например
git@github.com:user/repo.git. - Установите Branch для развёртывания. Поле начинается с
main. - Опционально установите Build command, например
npm run build. - Опционально установите Output directory, например
dist,publicили.для репозитория, который уже собран. - Нажмите Connect repo.
Оставьте команду сборки и выходную папку пустыми, если ваш репозиторий уже пригоден к развёртыванию в нынешнем виде, что характерно для обычного PHP-сайта или статического сайта.
Advanced Scripts
Раскрытие Advanced показывает два дополнительных поля:
- Pre-deploy script, выполняется перед сборкой.
- Post-deploy script, выполняется после развёртывания.
Используйте hook после развёртывания для действий, которые должны произойти после того, как новый код будет на месте: очистка кэша приложения, выполнение миграции БД, перезапуск worker-процесса.
Auto-Deploy On Push
Переключатель в нижней части карточки контролирует, будут ли push-уведомления вызывать развёртывание. Когда он включен, каждый push к настроенной ветке запускает развёртывание. Когда он выключен, развёртывания работают только при ручном запуске с помощью Deploy now.
Отключайте auto-deploy во время заморозки кода или инцидента, а не отключайте репозиторий полностью. Отключение репозитория удаляет ключ развёртывания и секрет webhook, поэтому вам придётся повторить обе шаги на стороне репозитория.
Завершение настройки в вашем репозитории
Подключение репозитория в KPanel, это только первый из трёх шагов. До тех пор, пока развёртывание не выполнено, страница показывает баннер Complete setup: 2 steps remaining со всем необходимым.
Шаг 2: добавление ключа развёртывания
Kapsule требуется доступ на чтение для клонирования вашего репозитория. Баннер показывает открытый ключ с кнопкой Copy key.
Вставьте его в ключи развёртывания вашего репозитория. Для GitHub баннер предлагает ярлык Add to GitHub прямо на нужную страницу настроек. Доступа на чтение достаточно, не предоставляйте доступ на запись.
Шаг 3: добавление webhook-уведомления
Webhook, это то, что сообщает Kapsule, что произошёл push. Баннер предоставляет три значения:
| Поле | Значение |
|---|---|
| Payload URL | URL, заканчивающийся на /api/git-deploy/webhook/ плюс ID этого сайта |
| Secret | Сгенерированный подписанный секрет, скрыт до нажатия на значок глаза |
| Content Type | application/json |
Скопируйте каждое в настройки webhook вашего репозитория. Для GitHub есть ярлык Add webhook to GitHub. Установите тип контента на JSON, а не форму по умолчанию, иначе полезная нагрузка не будет разобрана.
Рассматривайте секрет webhook как пароль. Тот, кто имеет его плюс URL полезной нагрузки, может запустить развёртывание вашего сайта. Оба значения показываются только людям, которые могут администрировать сайт, а секрет остаётся скрытым за значком глаза, пока вы его не запросите.
Развёртывание вручную
Нажмите Deploy now на странице Git Deploy, чтобы выполнить сборку и развёртывание текущей версии настроенной ветки без push-уведомления о коммите. Это работает независимо от того, включена ли функция auto-deploy, что делает это правильным инструментом во время заморозки: push-уведомления игнорируются, но вы всё ещё можете развернуть исправление.
Чтение истории развёртывания
Откройте Advanced, затем Deploys. Страница называется Deploy history и содержит список всех развёртываний, инициированных webhook или вручную, сначала самые новые.
Каждая строка содержит:
- Значок статуса и короткий SHA коммита с веткой в виде таблетки.
- Сообщение коммита или Manual deploy, если не было сообщения коммита для отображения.
- Автор, давность выполнения, продолжительность и то, что его запустило.
- Таблетку статуса.
Статусы: pending, building, deploying, success и failed. Пока что-то находится в полёте, страница обновляется каждые пять секунд и показывает заметку Refreshing automatically под таблицей, поэтому вы можете оставить её открытой и смотреть, как развёртывание приземляется.
Когда развёртывание даёт сбой
Строка с ошибкой получает кнопку Error справа. Нажмите её, чтобы расширить захваченный вывод ошибки в строке, не покидая страницу. Этот вывод, это собственный текст ошибки сборки, поэтому он обычно называет файл или команду, которая дала сбой.
Разберитесь с этим в таком порядке: прочитайте ошибку, воспроизведите ту же команду сборки локально, исправьте, выполните push. Если сборка работает локально, но не здесь, разница почти всегда в окружении, отсутствующей зависимости, которая установлена глобально на вашей машине, или файле, который находится в вашей рабочей папке, но не совершён.
Обнаружение Buildpack
На сайтах Node.js страница Buildpack в меню Advanced показывает, как Kapsule решила выполнить сборку вашего приложения. Обнаружение проходит по файлам в корне вашего репозитория, и первое совпадение побеждает:
| Обнаружено | Триггер |
|---|---|
| Custom buildpack | kapsule.config.yaml или kapsule.config.yml в корне |
| Dockerfile buildpack | Dockerfile в корне |
| Node.js | package.json со скриптом start, build или dev |
| Python | requirements.txt или pyproject.toml |
| PHP | composer.json |
| Static | index.html в корне |
Если ничего не совпадает, страница сообщает об этом и перечисляет поддерживаемые триггеры. Добавьте Dockerfile или kapsule.config.yaml, чтобы явно взять сборку под контроль.
Запуск сборки
Нажмите Run build, чтобы поставить её в очередь. Страница выполняет опрос каждые три секунды, пока сборка выполняется, и таблица Recent builds показывает последние запуски с их временем начала, типом, статусом, продолжительностью и полученной ссылкой на образ. Нажмите на строку, чтобы увидеть её хвост журнала.
Одновременно может выполняться только одна сборка. Попытка запустить вторую, пока одна находится в очереди или выполняется, отклоняется с сообщением A build is already in progress, что сделано специально: две сборки, записывающие в одно и то же место одновременно,, это способ получить наполовину развёрнутый сайт.
Отключение
Нажмите Disconnect и подтвердите. Подтверждение явно указывает на радиус поражения: конфигурация Git deploy и ключ развёртывания удаляются, файлы вашего сайта не затрагиваются. Сайт продолжит обслуживать то, что было развёрнуто последним.
Очистите, удалив ключ развёртывания и webhook в настройках вашего репозитория. Они просто перестанут работать, но оставлять мёртвые записи облегчает следующий аудит.
Устранение неполадок
Pushes ничего не инициирует. Сначала проверьте переключатель auto-deploy, затем webhook в вашем репозитории. Большинство поставщиков показывают последние доставки и коды ответов, что сразу указывает, покинул ли запрос ваш репозиторий вообще.
Клонирование даёт сбой. Ключ развёртывания отсутствует, был вставлен с разрывом строки или был добавлен в неправильный репозиторий. Скопируйте его снова с помощью кнопки Copy key, а не выбирайте текст вручную.
Развёртывание успешно, но сайт не изменяется. Выходная папка, вероятно, неправильная. Если ваша сборка записывает в dist, а выходная папка пуста, построенные файлы никогда не достигают обслуживаемого корня.
Всё говорит pending и никогда не движется. Развёртывание было поставлено в очередь, но никогда не было выбрано. Запустите ручное Deploy now и проверьте страницу Deploys на предмет строки ошибки.
Что делать дальше
- Preview Deploys For Pull Requests добавляет URL для каждого PR поверх этой настройки.
- Storing App Secrets For a Site для учётных данных, которые требуют сборка и среда выполнения.
- Site Activity Log записывает изменения конфигурации, внесённые здесь.