admin/.wiki/concepts/skills-catalog-deploy-runbook.md

---
title: "Деплой каталога скилов на сервер mappa (skills-catalog deploy)"
type: concept
tags: [runbook, mappa, skills, catalog, deploy, ops, admin]
related: [concepts/runbooks-index.md, concepts/mappa-vds-deploy-runbook.md, concepts/gitea-project-create-runbook.md]
updated: 2026-08-28
---

# Деплой каталога скилов на сервер mappa

> **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.**
> Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять.
> Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать.
> Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют.

> ✅ **Финализирован (2026-08-28, task:1462).** Команды деплоя — из README каталогов
> (deploy-catalog.mjs, task:1461 done). Core-immutable — **interim** (ручной шаг только
> с согласования оператора) до доработки /skills (mappa task:1466/1467): финальный
> механизм программный, ранбук обновится после их деплоя.

## Scope

Синк **каталога скилов** (skill-сущности mappa) на сервер mappa из репо-источников.
Направление — **репо → mappa** (один источник истины = исходники SKILL.md в git).

- Каталоги-источники (оба private, owner victor, созданы 2026-08-28 task:1458):
  - `victor/mappa-skills` → `kind=core` (техника, глобально);
  - `victor/mappa-vitya-skills` → `kind=methodology` (методология, фильтр `mappa-vitya-`).
- Сервер: `mappa.vds.kzntsv.site` (стек 27, Portainer), API `/skills` (task:1375/1376).
- **Деплой НЕ автоматический**: прогон только по письму-уведомлению от владельцев
  репо (см. «Стоящее правило») + ops-таска на борде `.admin`.

## Артефакты

- **Репо-источники (clone):**
  - `https://git.kzntsv.site/victor/mappa-skills.git`
  - `https://git.kzntsv.site/victor/mappa-vitya-skills.git`
  - SSH-порт git.kzntsv.site — **2222** (не 22).
- **Endpoint:** `https://mappa.vds.kzntsv.site/skills` — GET (список), GET `/skills/:name`,
  POST (create). PATCH/DELETE для `kind=core` → **403 (immutable)**.
- **Токен:** `MAPPA_API_TOKEN` — `<из pass mappa/full-env>` (тот же, что env 3/3 стека mappa).
- **Deploy-скрипт (task:1461 done):** `scripts/deploy-catalog.mjs` в каждом каталоге-репо
  (синк изменений вместо oneshot-засева seed-skills.ts, task:1448; kind по имени репо
  или `--kind`). Тесты: `scripts/deploy-catalog.test.mjs` (`node --test scripts/`).
  Семантика: отсутствующие → POST (create); изменённые methodology → PATCH (update);
  изменённый core → `! immutable` (не применяется).
- **Обратное направление (НЕ этот ранбук):** `scripts/sync-skills.ts` (task:1381) —
  синк каталога mappa → диск харнесса (pi/CC). Разделять: здесь деплой исходников в mappa.

## Шаги (команды из README каталогов, task:1461)

0. **Вход:** письмо-уведомление от проекта-держателя каталога (что изменилось:
   скилы/версии) → ops-таска на борде `.admin` (если ещё нет) → прогон по ранбуку.
1. **Pre-flight:** `git pull` каталога-репо (mappa-skills / mappa-vitya-skills);
   ENV: `MAPPA_API_TOKEN` из `pass mappa/full-env` (+ `MAPPA_CORE_URL` опц., дефолт
   https://mappa.vds.kzntsv.site); `admin_secret_scan` — 0 хитов (тела с секретом → 422).
2. **Dry-run** (из чекаута каталога):
   ```bash
   node scripts/deploy-catalog.mjs --dry-run   # дефолт тоже dry-run
   ```
   Сверить план: `create` / `update` / `immutable (!)` / `up-to-date` — нет ли
   неожиданного (лишний create = чужой каталог; immutable = правка core).
3. **Apply:**
   ```bash
   node scripts/deploy-catalog.mjs --apply
   ```
   Применяет create + update (**methodology** PATCH). Изменённый **core** —
   `! immutable`, НЕ применяется (см. interim, п.4).
4. **core-immutable (interim, до деплоя mappa task:1466/1467):** если в плане есть
   `! immutable` — правки core не применены. Путь: согласование с оператором →
   обновление сущности вне API (админ-операция .admin / пересоздание) → повторный
   dry-run подтверждает. **Финал — программный** (после 1466/1467); ручной шаг —
   только с согласования оператора, не «ограничение навсегда».
5. **Verify** (см. ниже).
6. **Фиксация:** письмо-отчёт проекту-держателю (verify-таблица) + закрытие ops-таски.

> Конкретика: `mappa-skills` → kind=core (10 скилов), `mappa-vitya-skills` →
> kind=methodology (2 скила, фильтр mappa-vitya-). Скрипт определяет kind по имени
> репо (или `--kind core|methodology`).

## Стоящее правило: деплой при каждом изменении исходников

**Прогон деплоя каталога скилов — при каждом изменении исходников в каталогах-репо.**
Уведомление — **письмом от владельцев репо** (mappa-зона — держатель исходников).

1. Проект, который пушит изменения в каталог-репо, при каждом замерженном изменении
   исходников (новый SKILL.md / правка / удаление) шлёт письмо-уведомление в `.admin`
   (`inbox_send`, from проект-владелец, type action): какие скилы затронуты, что изменилось.
   Адресант НЕ фиксирован на проекте («кто пришлёт, тот и держатель»): сейчас mappa →
   mappa-skills (core), skills → mappa-vitya-skills (methodology); сменится владелец
   каталога — сменится адресант.
2. `.admin` по письму: ops-таска (при необходимости) → прогон деплоя по этому ранбуку
   (dry-run → apply → verify) → письмо-отчёт + закрытие таски.
3. Триггер — **только письмо**. Без CI/крона/автоматики (подтверждено оператором 2026-08-28).

## Verify / smoke

- `GET https://mappa.vds.kzntsv.site/skills` (с `MAPPA_API_TOKEN`) — затронутые скилы
  присутствуют, `version` актуальна (из frontmatter SKILL.md), `enabled:true`.
- Прогон без ошибок: created/updated без 4xx/5xx (ошибки → в письме); methodology —
  PATCH применён; изменённый core — остался без применения (interim, зафиксировать в письме).
- Потребительская сторона: `sync-skills.ts` подхватит обновления на дисках харнессов
  (после `/reload`, спека wiki:3300 п.11) — verify-контур, не часть деплоя.

## Rollback

- **Откат содержимого (methodology):** revert коммита в репо-источнике → повторный
  `--apply` (PATCH вернёт прежнее тело).
- **Откат (core):** до деплоя 1466/1467 — только админ-операция вне API (revert
  исходника → ручной шаг с согласования оператора); после — программный путь из
  ранбука-апдейта.
- **Удаление ошибочного скила:** methodology — DELETE /skills; core — 403 (до
  1466/1467 — админ-операция, после — контролируемый путь).

## Gotchas

1. **`kind=core` immutable (interim)** — PATCH/DELETE `/skills` → 403, deploy-catalog
   помечает правки core как `! immutable` и НЕ применяет. Это **пробел сервера**
   (решение оператора inbox:2620: «ДОДЕЛАТЬ»): доработка /skills — mappa
   **task:1466/1467** (ready; в README репо — 1466, в письме inbox:2625 — 1467 —
   проверить дедуп). До её деплоя — ручной шаг только с согласования оператора.
   Не пытаться PATCH'ить core напрямую. (2026-08-28)
2. **422 secret-scan** — тело SKILL.md с секретом (token/password/… ≥6 симв.) →
   `POST /skills` → 422. Перед деплоем прогон `mcp__mappa__admin_secret_scan` (0 hits).
3. **Направление не путать** — репо → mappa (этот ранбук, deploy) vs mappa → диск
   (`sync-skills.ts`). Перепутать = «обновление с диска» не имеет смысла: каталог —
   источник, диск — потребитель. (2026-08-28)
4. **Триггер письмом, не таской** — таска на борде .admin не пингует живую сессию;
   уведомление = письмо (канон mappa-messaging). Без письма деплой не стартует. (2026-08-28)

## Решения оператора (2026-08-28, inbox:2620)

1. **Стоящее правило** — подтверждено как сформулировано: деплой каталога при каждом
   изменении исходников; уведомление письмом → ops-таска → dry-run → apply → verify;
   триггер только письмом, без CI/автоматики.
2. **Адресант уведомлений** — НЕ фиксировать на проекте: «кто пришлёт, тот и держатель».
   Проект, пушащий изменения в каталог-репо, шлёт письмо в .admin. Сейчас: mappa (core),
   skills (methodology); сменится владелец каталога — сменится адресант.
3. **Обновление core (immutable)** — ДОДЕЛАТЬ: core должны обновляться деплоем по
   определённому пути. 403 = пробел сервера → доработка /skills (follow-up mappa
   **task:1466/1467**, ready; дедуп проверить), не «ограничение + ручной шаг» как финал.
   До деплоя доработки — **interim**: ручной шаг только с согласования оператора.

**Статус (2026-08-28):** task:1461 done → команды деплоя в ранбуке, task:1462
финализирована; ранбук-апдейт финального core-механизма — после деплоя 1466/1467
(штатный WRITE-апдейт).