Деплой на 1С:Предприятие.Элемент

Справочник по API: references/endpoints.md — читай его если нужны детали по полям запросов/ответов.

Шаг 0: Загрузи переменные окружения

Перед любым обращением к API загрузи env vars. Выполни команду:

set -a && source .env 2>/dev/null; set +a

Если .env не найден — продолжай: нужные переменные могут быть уже заданы в системе.

Обязательные переменные: ELEMENT_BASE_URL, ELEMENT_CLIENT_ID, ELEMENT_CLIENT_SECRET. Если хотя бы одна отсутствует — сообщи пользователю и остановись.

Два вида веток: внешний git vs внутренний git платформы

В 1С:Элемент существуют два независимых механизма веток — не путай их:

	Внешний git (GitHub/GitLab)	Внутренний git платформы
Что это	Твой обычный git-репозиторий	Встроенная система групповой разработки платформы
Как обновить приложение	`sync-branch` / кнопка «Загрузить из ветки» в IDE	Сценарий B (update-branch + restart)
API	`/console/ui/module/call` (внутренний)	`GET/POST /console/api/v2/branches`
Когда работает	Всегда (если репо доступен платформе)	Только если проект включил режим групповой разработки
Ошибка если не поддерживается	—	503 “does not use export branches”
Merge изменений	Через git (PR/MR)	Сценарий G (merge-branch)
Типичный сценарий	Деплой из GitHub на продакшн	Командная разработка задач внутри платформы (`issue/CRM-1`)

Если получаешь 503 на list-branches / get-branch — проект работает через внешний git. Используй Сценарий I (путь 2: --from-branch) вместо Сценария B.

Шаг 1: Определи намерение

Фраза пользователя	Сценарий
создать / новое / задеплой с нуля / развернуть	A: Создать + задеплоить
обновить / задеплой / загрузить ветку / редеплой	B: Обновить существующее
статус / как дела / что с приложением / проверь	C: Проверить статус
запусти / старт / включи	D: Запустить
останови / стоп / выключи	E: Остановить
удали / снести / delete / убери	F: Удалить
принять изменения / смёрджи / merge	G: Merge ветки
создать проект / загрузить сборку / новый проект из файла	H: Создать проект из сборки
задеплой из исходников / собери и задеплой / deploy from source	I: Собрать .xasm и задеплоить
sync-branch / обнови ветку в облаке / загрузить из ветки / pull из git	J: sync-branch с фолбэком на сборку

Шаг 2: Получи токен

python3 .claude/skills/xbsl-deploy/scripts/api.py --action get-token

Если ошибка — сообщи пользователю что нужно задать env vars: ELEMENT_BASE_URL, ELEMENT_CLIENT_ID, ELEMENT_CLIENT_SECRET.

Сценарий A: Создать новое приложение и задеплоить

По умолчанию: новое приложение привязывается к существующему проекту. Загрузка файла сборки для создания нового проекта — только если пользователь явно попросил («создать проект из сборки», «загрузить сборку» и т.п.) — тогда используй Сценарий H.

A0. Проверь вид проекта (если известна папка проекта)

Если пользователь указал локальную папку проекта — прочитай Проект.yaml и проверь наличие поля ВидПроекта: Библиотека:

grep "ВидПроекта" <путь>/Проект.yaml

Если найдено ВидПроекта: Библиотека — остановись и сообщи пользователю:

Платформа не может развернуть библиотеку как самостоятельное приложение. Библиотека предназначена для подключения через Импорт в другой проект, а не для деплоя.

A1. Определи проект

Если ELEMENT_PROJECT_ID не задан — выведи список проектов и попроси пользователя выбрать:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-projects

Показывай только не удалённые ("deleted": false) проекты типа Application.

Сохрани выбранный project-id для следующих шагов.

A2. Определи space-id

Если ELEMENT_SPACE_ID не задан:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-spaces

Если пространство одно — используй его id как space-id. Предложи пользователю сохранить в .env: ELEMENT_SPACE_ID=<id>.
Если пространств несколько — покажи список и спроси пользователя выбрать.
Если пространств нет — сообщи пользователю, создать пространство нужно через веб-консоль.

A3. Создай приложение

Спроси имя приложения если не указано.

python3 .claude/skills/xbsl-deploy/scripts/api.py --action create-app --name <name> --space-id <space-id> --project-id <project-id>

Сохрани id из ответа как app-id.

A4. Запусти приложение

python3 .claude/skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

A5. Жди Running

Опрашивай каждые 10 сек, до 5 мин:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action get-app --app-id <app-id>

Жди пока status == Running. Если status == Error — сообщи error пользователю и остановись. Если 5 мин прошло, а статус не Running — сообщи пользователю текущий статус и предложи проверить логи в консоли Элемента.

A6. Верни ссылку

Из последнего ответа get-app возьми поле uri и отправь пользователю.

Сценарий B: Обновить приложение из ветки

B1. Найди приложение

Используй ELEMENT_APP_ID или спроси имя и найди:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-apps --name <name>

Сохрани id как app-id.

B2. Определи project-id

Используй ELEMENT_PROJECT_ID. Если не задан — извлеки из ответа B1: поле project.id в объекте приложения. Если поле project отсутствует или пустое:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-projects

Спроси пользователя выбрать проект. Сохрани как project-id.

B3. Создай дамп (страховка перед изменениями)

Дамп нужен как точка отката на случай проблем после деплоя.

python3 .claude/skills/xbsl-deploy/scripts/api.py --action create-dump --app-id <app-id>

Сохрани id из ответа как dump-id. Проверь статус сразу (без паузы), затем опрашивай каждые 3 сек (до 60 сек):

python3 .claude/skills/xbsl-deploy/scripts/api.py --action get-dump --app-id <app-id> --dump-id <dump-id>

Жди пока status станет Done или Completed. Если дамп завершился ошибкой или не готов за 60 сек — остановись и сообщи пользователю. Не продолжай.

B4. Найди ветку

python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-branches --project-id <project-id> --branch-name <branch>

B5. Привяжи ветку к приложению (если нужно)

Если branch.application.id != app-id:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action update-branch --branch-id <branch-id> --app-id <app-id>

B6. Перезапусти (подхвати изменения из репозитория)

Сначала останови (если приложение не Stopped):

python3 .claude/skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин). Затем запусти:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

B7. Жди Running → верни URL (как A5-A6)

Сценарий C: Статус приложения

python3 .claude/skills/xbsl-deploy/scripts/api.py --action get-app --app-id <app-id>

Выведи пользователю: - status (Running / Stopped / Error / …) - uri — ссылка на приложение - error — если есть - current-task — текущая задача если есть - technology-version

Сценарий D: Запустить приложение

python3 .claude/skills/xbsl-deploy/scripts/api.py --action start-app --app-id <app-id>

Жди Running (опрос каждые 10 сек, до 5 мин) → верни статус и ссылку. Если таймаут — сообщи текущий статус и предложи проверить логи в консоли Элемента.

Сценарий E: Остановить приложение

python3 .claude/skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин) → сообщи что остановлено. Если таймаут — сообщи текущий статус.

Сценарий F: Удалить приложение

Обязательно запроси подтверждение у пользователя перед любым удалением. Сообщи имя удаляемого объекта и что действие необратимо. Продолжай только после явного подтверждения («да», «удали», «confirm» и т.п.). Если пользователь не подтвердил — остановись.

Если приложение не Stopped:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action stop-app --app-id <app-id>

Жди Stopped (опрос каждые 10 сек, до 3 мин). Затем:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action delete-app --app-id <app-id>

Если ветка создавалась скиллом — предложи удалить и её. Удаляй ветку только после отдельного подтверждения:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action delete-branch --branch-id <branch-id>

Сценарий G: Принять изменения (merge ветки)

Если branch-id не известен — найди ветку. Для этого нужен project-id (из ELEMENT_PROJECT_ID или спроси пользователя через list-projects):

python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-branches --project-id <project-id> --branch-name <branch>

Затем выполни merge:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action merge-branch --branch-id <branch-id>

Сообщи результат.

Сценарий H: Создать проект из файла сборки

Проект на Элементе создаётся загрузкой бинарного файла сборки (.zip или артефакт компилятора). Без файла создать проект через API нельзя.

H1. Уточни параметры

Спроси пользователя: - путь к файлу сборки (--file) - имя ветки (--branch-name), если нужно зафиксировать (иначе используется ELEMENT_BRANCH) - хэш коммита и сообщение (--commit-id, --commit-message) — опционально

H2. Определи space-id

Если ELEMENT_SPACE_ID не задан:

python3 .claude/skills/xbsl-deploy/scripts/api.py --action list-spaces

Если пространство одно — используй его автоматически.

H3. Загрузи сборку и создай проект

python3 .claude/skills/xbsl-deploy/scripts/api.py --action upload-build \
  --file <path> \
  --space-id <space-id> \
  [--branch-name <branch>] \
  [--commit-id <hash>] \
  [--commit-message <msg>]

Чтобы добавить сборку к существующему проекту, добавь --project-id <id>.

Из ответа возьми project-id для дальнейших операций (создание приложения, ветки и т.д.).

Сценарий I: Деплой через deploy.py

Детали путей деплоя — см. references/deploy-paths.md. Настройка CI/CD (GitHub Actions, GitLab CI) — см. references/ci-cd.md.

I0. Проверь вид проекта

Если известна папка проекта — прочитай Проект.yaml и проверь:

grep "ВидПроекта" <путь>/Проект.yaml

Если найдено ВидПроекта: Библиотека — остановись и сообщи пользователю:

Платформа не может развернуть библиотеку как самостоятельное приложение. Библиотека предназначена для подключения через Импорт в другой проект, а не для деплоя.

Путь 1 (из исходников): нужны ELEMENT_APP_ID, ELEMENT_PROJECT_ID.

python3 .claude/skills/xbsl-deploy/scripts/deploy.py [--project-dir PATH] [--branch B] [--commit C]

Если команда завершилась ошибкой (exit code != 0): 1. Покажи пользователю полный текст ошибки из вывода. 2. Проанализируй ошибку и предложи конкретный вариант исправления (что именно изменить в файлах проекта). 3. Жди явного подтверждения пользователя («да», «исправь», «ок» и т.п.). 4. Только после подтверждения — внеси исправление и повтори деплой.

Путь 2 (из git-ветки): нужны ELEMENT_APP_ID, ELEMENT_BRANCH_ID. ⚠️ sync-branch требует браузерную сессию — через API невозможен (Bearer возвращает 403).

python3 .claude/skills/xbsl-deploy/scripts/deploy.py --from-branch [--branch-id ID]

Сценарий J: sync-branch с фолбэком на сборку

sync-branch через API невозможен — эндпоинт /console/ui/module/call требует браузерную сессию (cookie), Bearer-токен возвращает 403.

J1. Объясни ограничение и предложи альтернативу

Сообщи пользователю:

Обновить ветку напрямую через API невозможно — платформа требует браузерную сессию. Можно обновить приложение через сборку из исходников (Путь 1): Claude соберёт .xasm из локальных файлов и загрузит на платформу. Обновить через сборку?

Жди явного согласия («да», «давай», «конечно», «ок» и т.п.). Если пользователь не согласился — остановись и напомни про ручной способ:

Раздел «Ветки» в веб-консоли → три точки у ветки → «Обновить приложение по ветке».

J2. Если пользователь согласился — выполни Сценарий I (Путь 1)

Перейди к Сценарию I, Путь 1: из исходников. Все шаги те же.

Правила работы

app-id: берётся из ELEMENT_APP_ID → аргумента → поиска по имени
project-id: берётся из ELEMENT_PROJECT_ID → аргумента → выбора пользователя
branch: берётся из ELEMENT_BRANCH (по умолчанию main)
Дамп нужен только перед обновлением существующего приложения (Сценарий B). При создании нового — не нужен.
space-id: берётся из ELEMENT_SPACE_ID → автоопределения через list-spaces (если пространство одно — используется автоматически, предложи сохранить в ELEMENT_SPACE_ID)
При ошибке API — показывай поле error и details из ответа
Удаление (приложения, ветки, проекта) — всегда запрашивай явное подтверждение пользователя перед выполнением. Без подтверждения не удалять ничего.