Источники Git и Build Workers

Настройте коннектор по руководству Git-хостинги. Там также разделены права на репозиторий и права на целевой ресурс для запуска сохранённых сборок и просмотра истории. Учётные данные реестров описаны в разделе Реестры образов.

Источник Git связывает одобренную ревизию репозитория с неизменяемым артефактом сборки. Он может поставлять артефакт для Docker Container, Deployment, Compose Project или релиза Pages, но рабочая нагрузка всё равно следует жизненному циклу владеющего ресурса. Само подключение источника не даёт права менять Route рабочей среды или цель трафика.

Решите, что разрешено автоматизации

Разделите три решения: кто может читать исходный код, что считается одобренным артефактом и можно ли развёртывать этот артефакт автоматически. Так команда сможет автоматизировать обычные релизы, не выдавая webhook репозитория неограниченные полномочия в рабочей среде.

Владелец источника управляет доступом к репозиторию и выбирает коммит для сборки. Владелец платформы отвечает за Build Worker, политику сборки, реестр и целевой ресурс развёртывания. Владелец сервиса задаёт критерии приёмки и отката. Opfield связывает эти записи и сохраняет происхождение от коммита до дайджеста, но успешная сборка остаётся лишь входными данными для релиза.

Используйте автоматическую сборку, если каждое выбранное изменение источника должно создавать артефакт. Включайте автоматическое развёртывание только после проверки состояния и пути восстановления владеющего ресурса и только для веток, где модель контроля изменений это допускает. Для сервисов с повышенным риском оставляйте одобрение артефакта и развёртывание отдельными решениями человека.

Предварительные условия и владение

Используйте поддерживаемую интеграцию источника из списка разрешённых и выдавайте только необходимый для сборки доступ к репозиторию. Выберите точную ревизию ветки и убедитесь, что назначенный выделенный Build Worker подключён. По умолчанию Build Worker выполняет одну сборку за раз (Parallel jobs на странице ноды, до 16), использует изолированное состояние BuildKit и containerd, применяет фиксированные ограничения ресурсов, запрещает небезопасные разрешения сборки и очищает кэш между заданиями. Хосту Build Worker нужен systemd.

Сборки из очереди получают Build Workers в том порядке, в котором они стоят в списке Nodes: первый подключённый Build Worker берёт сборки, пока заняты не все его параллельные задания, затем следующий. Перетащите Build Worker выше, чтобы он был предпочтительным, или в конец, чтобы он брал только избыток. Порядок списка такой: папки верхнего уровня по их положению, внутри папки сначала её вложенные папки, затем её ноды, и последними ноды вне папок. Build Worker берёт сборки только для своей платформы (архитектуры).

Build Secrets ограничены источником и подключаются как секреты только во время сборки. Не помещайте учётные данные в аргументы сборки, ссылки на образы, URL репозитория, сохранённую в репозитории конфигурацию или журналы. Build Worker отвечает за изоляцию выполнения, реестр хранит созданный артефакт, а целевая нода Docker позднее загружает и запускает этот артефакт.

Соберите и проверьте артефакт

1. Подключите интеграцию и выберите репозиторий, ветку и нужную ревизию.
2. Настройте входные данные сборки и Build Secrets, ограниченные источником.
3. Запустите сборку и следите за её Task от назначения Build Worker до публикации артефакта.
4. Проверьте очищенные журналы, найденные уязвимости, результат политики, исходный коммит и неизменяемый дайджест артефакта.
5. Выберите одобренный дайджест в сценарии владеющего Container, Deployment или Pages.

Пока сборка развёртывается в Container, Deployment или Compose Project, Opfield блокирует эту цель: изменения жизненного цикла и конфигурации, изменения секретов, изменения Availability и миграции отклоняются с BUILD_ROLLOUT_IN_PROGRESS, пока развёртывание не завершится успешно, с ошибкой или не будет отменено, а Console показывает на цели баннер. Блокировка сохраняется после перезапуска Opfield. Если в момент начала развёртывания цель занята другой операцией, развёртывание ждёт до 5 минут, а затем завершается ошибкой BUILD_ROLLOUT_TARGET_BUSY. Релизы Pages так не блокируются. Во время обновления Opfield сборки, запущенные через webhook или опрос, откладываются и запускаются однократно после обновления.

Действие Sync now у источника Git для Container, Deployment, Compose Project или проекта Pages сразу проверяет ветку и запускает сборку, если в ней появились изменения и автоматические сборки включены. Политика уязвимостей источника отклоняет артефакты с находками выбранной серьёзности и выше (по умолчанию Critical, либо High, Medium или Low); None одобряет любой просканированный артефакт, а Disabled одобряет артефакты без обязательного сканирования. Результаты сборки отправляются в реестр, не оставаясь в собственном хранилище образов Build Worker, поэтому сборки не заполняют его диск.

Автоматическая сборка и автоматическое развёртывание — независимые настройки. Не включайте автоматическое развёртывание, пока для рабочей нагрузки не проверены состояние и путь отката. Успешная сборка доказывает только наличие артефакта, но не подтверждает, что приложение корректно запустится на целевой ноде.

Папки для рабочих нагрузок из сборки

Контейнер или развёртывание, созданные из источника Git, попадают в папку, выбранную при создании: поле папки на вкладке Repository диалога развёртывания или folderId в API и MCP. Для создания в ней нужно право создания на эту папку, а пользователь, которому разрешено создавать только в папках, должен выбрать одну из них; диалог сам подставляет единственную доступную папку. Для настройки источника также нужен integrations:<provider>:use на репозиторий; см. «Git-хостинги».

Пока первая сборка не завершилась, рабочая нагрузка показана в этой папке с пометкой Awaiting build вместо образа. Её можно переместить, как любой другой контейнер: командой Move to folder..., перетаскиванием или через API и MCP — для этого нужно право изменения на саму нагрузку и на папку назначения. Первая сборка создаёт её в той папке, где она находится в этот момент, и проверяет там право создания, в том числе когда сборку запускает автоматизация источника. Поэтому у пользователя с доступом только к папке собранная нагрузка никогда не оказывается на верхнем уровне. Всё это время имя закреплено за источником: создание, дублирование, переименование или импорт другого контейнера под этим именем завершается ошибкой 409 NAME_IN_USE.

Обработка сбоев

Если сборка не начинается, откройте её Task и проверьте авторизацию источника, доступность Build Worker, право по тарифу и состояние интеграции. Отменённая сборка с сообщением Build paused: <user> no longer has use on <repo> означает, что учётная запись, сохранившая источник, потеряла integrations:<provider>:use на репозиторий; см. «Кто может запускать и просматривать сборки?». Если ошибка произошла после запуска, по этапу и журналам отделите сбой зависимости, секрета, политики, определения сборки или публикации артефакта. Исправьте источник или конфигурацию и запустите новую сборку. Повторная попытка создаёт новую операцию и сохраняет прежнюю историю.

Если Build Worker или автоматизация источника недоступны, прежняя история остаётся полезной для диагностики, но новые сборки нельзя считать выполняющимися. Не заменяйте отсутствующий неизменяемый артефакт изменяемым тегом образа. Дождитесь проверенной сборки или используйте отдельно одобренный образ.

Готовность после развёртывания

Когда сборка развёртывается в Container, Opfield пересоздаёт его с новым образом и до 60 секунд ждёт готовности: состояния healthy, если у образа есть проверка состояния, а иначе — 10 секунд работы без перезапуска. Контейнер, который перезапускается в цикле, завершается или становится unhealthy, возвращается на прежний образ, а сборка завершается ошибкой BUILD_ROLLOUT_ROLLED_BACK или BUILD_ROLLOUT_ROLLBACK_FAILED, если прежний образ восстановить не удалось. Текст ошибки называет состояние контейнера, код выхода и число перезапусков, за ними идут последние строки его журнала, а развёрнутым остаётся прежний коммит. Прочие сбои развёртывания сообщаются как BUILD_ROLLOUT_FAILED. Deployment использует собственный путь blue/green с проверкой состояния: неудачный кандидат останавливается, а трафик остаётся на обслуживающем слоте. Ревизия Compose, собранная из Git, опубликованный порт которой на ноде уже занят другой рабочей нагрузкой, завершается ошибкой COMPOSE_HOST_PORT_IN_USE, и ревизия не создаётся.

Очистка и откат

Удаление подключения источника блокирует будущие операции из этого источника, но не удаляет автоматически уже запущенную среду выполнения или артефакт. Удаление контейнера удаляет и его источник Git, а если вебхук репозитория удалённого контейнера удалить не удалось, источник перестаёт собирать и развёртывать, чтобы новый коммит не пересоздал контейнер; очистка повторяется позже. Образы сборок удалённых Containers, Deployments и Compose Projects удаляются с их нод автоматически, обычно в течение минуты, а ноды, которые были отключены, проверяются заново каждые 10 минут. Неиспользуемый образ сборки можно удалить и вручную в списке образов ноды; удаление образа, который ещё использует контейнер на ноде, отклоняется с 409 GATEWAY_INTERNAL_IMAGE. Перед отзывом подключения определите, какие артефакты ещё нужны для отката. Срок хранения задаётся реестром и историей активных, откатных, выполняющихся, закреплённых и недавно успешных состояний владеющего ресурса.

Критерии успеха

Приемлемая сборка указывает репозиторий и точный коммит, завершается на одобренном Build Worker, создаёт неизменяемый дайджест, проходит настроенную политику уязвимостей и показывает журналы без секретов. Приёмка Deployment выполняется отдельно: целевой ресурс должен загрузить дайджест, успешно запуститься, пройти проверку состояния и обслужить ожидаемый клиентский путь.

Сохраняйте достаточно истории сборок и артефактов, чтобы объяснить, что запущено, и восстановить предыдущий заведомо исправный релиз. Изменяемого тега, успешного сообщения Console или зелёного индикатора сборки без дайджеста недостаточно как доказательства готовности рабочей среды.

Операторские детали: изоляция и диагностика

Build Workers образуют выделенные границы выполнения, потому что содержимое репозитория и определения сборки могут исполнять код. Ограничивайте учётные данные Build Worker, не размещайте рядом несвязанные чувствительные рабочие нагрузки и считайте результат сборки недоверенным до завершения проверок политики и происхождения. Подключайте Build Secrets только на нужном этапе и не копируйте их в слои образа.

Шаги сборки не могут обратиться к самому хосту Build Worker ни по IPv4, ни по IPv6 при любом профиле исходящего трафика (internet или offline). На хосте с IPv6 Build Worker требует ip6tables и без него не запускается.

Если сборка находится в очереди, отделите нехватку ёмкости Build Worker от ошибки источника или политики. Если она запустилась и завершилась ошибкой, определите фазу: получение исходного кода, разрешение зависимостей, сборку Dockerfile или Compose, проверку уязвимостей, публикацию в реестр или итоговое подтверждение. До повторной попытки сохраните ограниченный фрагмент журнала и коммит. Повтор должен создать новую аудируемую попытку, а не перезаписать неуспешную запись.