---
work_item: ORCH-009
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: claude-opus-4-8
---

# 07 — Инфра-требования: ORCH-009 — Turnkey-онбординг проектов

Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: architecture

> Топология оркестратора **не меняется** (NFR-1/NFR-2: `src/**` и compose не трогаются).
> Файл фиксирует **предусловия исполнения способности** (токены/доступы/контуры) и инфра-границы
> операторского скрипта. Детали решений — `06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md`.

## I-1. Топология / окружения

- **Прод (`orchestrator`, 8500):** не затрагивается. Скрипт не создаёт/не останавливает/не
  рестартит контейнеры; в общую БД не пишет (читает только файлы чекаута и внешние API).
- **Staging (`orchestrator-staging`, 8501, БД `./data/staging`):** контур smoke-прогона (ADR D8).
  Регистрация sandbox-проекта — в `.env.staging`; рестарт staging — штатный, свободный
  (прод-инвариант на него не распространяется).
- **Новые внешние сущности** (создаются скриптом в `apply`): Plane-проект, Gitea-репо +
  per-repo webhook. Аддитивно: существующие проекты/репо не модифицируются (BR-9).
- **Запуск скрипта:** хост mva154, из корня чекаута репо orchestrator. Среда исполнения —
  venv с `requirements.txt` (httpx уже в зависимостях; новых pip-зависимостей нет) **или**
  `docker compose exec orchestrator python scripts/onboard_project.py …` (read-only к рантайму,
  без рестартов). Канонический способ фиксирует runbook `docs/operations/ONBOARDING.md`.

## I-2. Переменные окружения / секреты

**Новых env-переменных не вводится.** Используются существующие (предусловия запуска):

| Переменная | Роль в онбординге |
|---|---|
| `ORCH_PLANE_API_TOKEN` (+ `ORCH_PLANE_API_URL`, `ORCH_PLANE_WORKSPACE_SLUG`) | создание/чтение Plane-проекта, статусов, лейблов; токен с правом создания проектов в workspace |
| `ORCH_GITEA_TOKEN` (+ Gitea base URL) | создание репо (под `{{GITEA_OWNER}}`), per-repo webhook; токен с правом create-repo + hooks |
| `ORCH_GITEA_WEBHOOK_SECRET` | **переиспользуется** для webhook нового репо (приёмник валидирует один глобальный секрет, ADR D6); отсутствует → скрипт генерит и печатает оператору для `.env` |
| `ORCH_PROJECTS_JSON` | источник существующих записей для merged-вывода (ADR D7); **применение новой строки — операторский шаг** |

- Секреты — только в `.env`/`.env.staging` на хосте, в гит не попадают (правило #8 CLAUDE.md);
  в логах/отчётах скрипта секреты маскируются (NFR-3).
- Kit несёт собственный `.env.example` нового проекта (дескрипторы без значений) — канон секретов
  транслируется в онбордируемые репо.

## I-3. Деплой / рестарт

- **Скрипт НИКОГДА не рестартит/не останавливает прод-контейнер** (NFR-2, self-hosting инвариант).
- Регистрация проекта в реестре (Ф-3): правка `.env` (строка `ORCH_PROJECTS_JSON` из отчёта
  скрипта) + **управляемый операторский рестарт** оркестратора — групповое окно для ВСЕХ проектов
  общего инстанса; runbook помечает шаг self-hosting-предупреждением и командой проверки
  (`GET /queue`, резолв статусов нового проекта).
- TTL-self-heal статусов Plane (ORCH-068, 300с) рестарта не требует: статусы/лейблы, созданные
  после регистрации, подхватываются без вмешательства.
- Деплой самой задачи ORCH-009 — штатный конвейер: изменение docs/scripts/tests-only, образ
  пересобирается стандартно, staging-гейт (8501) обязателен как обычно.

## I-4. CI/CD

- `.gitea/workflows/` — **без изменений**: новые тесты (`tests/test_onboarding_kit.py`,
  `test_onboarding_script.py`, `test_onboarding_invariants.py`) подхватываются существующим
  pytest-шагом; все детерминированы, без сети (NFR-5).
- Инфра-предусловий в образе нет: скрипт — операторский CLI вне рантайма, в образ ничего
  дополнительно не запекается.