BRD — ORCH-36: Исполняемый самодеплой (стадия deploy дёргает хост-хук, Вариант B)

Work Item: ORCH-036 Stage: analysis Автор: analyst Дата: 2026-06-06

1. Контекст и проблема

Стадия deploy конвейера сейчас «бумажная». На ней deployer-агент (LLM) только пишет docs/work-items/<wi>/14-deploy-log.md с deploy_status: SUCCESS|FAILED, а QG check_deploy_status (src/qg/checks.py:464) парсит этот вердикт и пускает deploy → done. Реального docker-деплоя нет — продакшен орка катается руками (Стрим).

Хост-хук scripts/orchestrator-deploy-hook.sh уже существует (ORCH-34) и умеет: захват PREV_IMG → git pull → рестарт сервиса → health-check (10×6с = 60с) → авто-rollback при провале health, с корректным exit-code. Дефолты — STAGING-безопасные; прод включается через override env (TARGET_SERVICE, TARGET_PORT, TARGET_IMAGE, COMPOSE_PROFILE).

Главная мина (self-hosting): прод-контейнер orchestrator (8500) — ОДИН на все проекты, и в нём же бежит сам deployer-агент. Deployer не может синхронно рестартить контейнер, в котором живёт (docker compose up -d orchestrator убьёт его процесс на середине). Реальный рестарт self-репо обязан делать ВНЕШНИЙ хост-хук (вне контейнера), который срабатывает ПОСЛЕ выхода агента. Рубильник — снаружи; орк только ИНИЦИИРУЕТ.

2. Цель

Превратить стадию deploy в РЕАЛЬНЫЙ самодеплой: после зелёного deploy-staging-гейта конвейер вызывает хост-хук с прод-параметрами, хук промоутит образ в прод (8500) с health-чеком и авто-rollback. Результат хука (exit-code) маппится в deploy_status. На старте — с ОБЯЗАТЕЛЬНЫМ ручным approve (DEPLOY_REQUIRE_MANUAL_APPROVE=true): прод не трогается без явного «go» Владельца.

3. Ценность для бизнеса

Уходит последний ручной шаг конвейера (прод-деплой Стрим) → шаг к автономному внедрению (эпик ORCH-54).
deploy_status: SUCCESS становится доказанным (реальный health-ok), а не декларацией LLM.
Гарантия build-once: «что протестировали на staging — то и в проде» (тот же образ, без пересборки).
Прод никогда не остаётся в нерабочем состоянии: авто-rollback + health-таймаут.

4. Заинтересованные стороны

Роль	Интерес
Владелец (Слава/Стрим)	Контроль через ручной approve; уведомления о каждом промоуте/откате
Проект enduro-trails	Прод-орк не должен падать (общий инстанс) — групповой риск
Конвейер ORCH	Стадия `deploy` исполняемая, гейты не сломаны

5. Объём (scope)

В объёме

Исполнение реального прод-деплоя из стадии deploy через хост-хук (ssh / detached на хосте).
Обязательный ручной approve-гейт ПОСЛЕ зелёного staging и ДО прод-рестарта (флаг включён).
Маппинг exit-code хука → deploy_status: SUCCESS|FAILED (реальный, не бумажный).
Уведомления (Plane-коммент + Telegram) на каждый промоут и откат.
Build-once: перетегирование образа, прошедшего staging, без пересборки.
Обновление deployer.md и INFRA.md (документация = golden source).
Для НЕ-self репо (enduro-trails и др.) — деплой по ssh на их хост (поведение не ломается).

Вне объёма (явно)

Включение полного авто (DEPLOY_REQUIRE_MANUAL_APPROVE: true → false) — отдельная задача, ТОЛЬКО после набора метрик доверия (см. §7). В этой задаче флаг НЕ выключается.
Изменение docker-compose.yml без явной необходимости.
Изменение стадий STAGE_TRANSITIONS, реестра QG, terminal-sync deploy → done.
Прод-деплой в реальный бой во время разработки задачи (отладка — только на staging-цели хука).

6. Бизнес-требования

BR-1. После зелёного deploy-staging-гейта стадия deploy РЕАЛЬНО собирает/перетегирует образ, рестартит целевой сервис и проверяет health — не пишет бумажный SUCCESS.
BR-2. Для self-репо orchestrator рестарт 8500 выполняется ВНЕШНИМ (detached/host) процессом; deployer-агент НЕ убивает контейнер, в котором работает.
BR-3. deploy_status: SUCCESS пишется ТОЛЬКО при health-ok хука; провал/health-fail → deploy_status: FAILED → откат на development (как ORCH-35 staging-rollback, БАГ-8).
BR-4. Ручной approve обязателен (флаг true): без явного «go» прод НЕ трогается.
BR-5. Каждый промоут и откат уведомляет Владельца: Plane-коммент в задачу + Telegram. «Молчаливых» деплоев нет.
BR-6. Build-once: в прод идёт тот образ, что прошёл staging-гейт (перетег, не пересборка).
BR-7. Staging-гейт (check_staging_status) остаётся обязательным предусловием прод-деплоя.
BR-8. Прод никогда не остаётся в нерабочем состоянии — авто-rollback при провале health.
BR-9. Существующие гейты и инварианты не ломаются: check_deploy_status, _parse_deploy_status, rollback deploy → development (БАГ-8), terminal-sync deploy → done, merge-gate (ORCH-43).
BR-10. Документация (deployer.md, INFRA.md, CHANGELOG.md) обновлена в том же PR.

7. Критерии готовности к включению ПОЛНОГО авто (вне этой задачи)

Переключать DEPLOY_REQUIRE_MANUAL_APPROVE: true → false можно ТОЛЬКО когда закрыты ВСЕ 5:

≥10 успешных промоутов подряд (staging зелёный → approve → прод поднялся, откат не нужен).
Zero false-negative: staging-гейт ни разу не пропустил битый деплой как «зелёный».
Авто-rollback проверен в бою (≥2–3 реальных срабатывания), recovery 100%, MTTR < 60с.
Ни одного «молчаливого» деплоя (каждый промоут/откат уведомил Владельца).
Период наблюдения ≥10 деплоев ИЛИ ≥2 недели без инцидентов в режиме manual-approve.

8. Риски

Риск	Влияние	Митигация
Падение прод-орка 8500 при self-деплое	Встаёт конвейер ВСЕХ проектов	Detached host-хук + health + авто-rollback; отладка на staging-цели
Deployer рестартит сам себя синхронно	Процесс агента убит на середине	BR-2: рестарт только внешним detached-процессом
Преждевременный `deploy_status: SUCCESS` (хук ещё не закончил)	Задача уходит в done при незавершённом деплое	Гейт читает РЕАЛЬНЫЙ исход хука (механизм — на дизайне)
Деплой без approve	Неконтролируемый прод-деплой	BR-4: approve-гейт блокирует до «go»
Пересборка вместо перетега	В прод уезжает не то, что тестировали	BR-6: build-once, `--no-build` + retag

9. Связанные задачи

ORCH-7 (self-hosting), ORCH-21 (auto-rollback), ORCH-34 (хук готов), ORCH-35 (staging-гейт), ORCH-43 (merge-gate в проде), ORCH-54 (эпик автономного внедрения). Дизайн-референс: tasks/orchestrator/DESIGN_STAGING_ENV.md §4/§7.

9.4 KiB Raw Permalink Blame History Unescape Escape