--- name: admin-runbooks author: ours version: 1.1.0 description: > Единый контур ранбуков зоны админа (.admin): НАЙТИ нужный ранбук перед любой прод-операцией → ИСПОЛНИТЬ по нему (чек-лист + verify + откат + письмо/таска) → ВЕСТИ (обновлять после инцидентов/изменений) и СОЗДАВАТЬ новые. Поглощает writing-runbooks (v1.0.0, superseded) — секция WRITE это его канон. Trigger (user): деплой/редеплой/рестарт/ротация/миграция любого сайта или стека; «по ранбуку», «как деплоить X», «напиши/обнови ранбук», «есть ли ранбук по X»; любой прод-инцидент на сайте, который может потребовать операции. --- # admin-runbooks Один контур: **индекс → USE → EXECUTE → WRITE/UPDATE**. Цель — устранить «рыскание» (поиск рецепта по сессиям/чатам/grep), когда ранбук есть или должен быть. > ⚠️ **СЛУЖЕБНАЯ зона `.admin`.** Ранбуки — служебные документы `.admin`: > применять/выполнять может только `.admin`; другие проекты читают по запросу, > не выполняют; наружу не выносить. Прод-операция по ранбуку = таска на борде > `.admin` + письмо от заказчика (исполнитель-не-админ не деплоит сам). ## 0. ИНДЕКС РАНБУКОВ (всегда первый шаг) **Индекс:** mappa wiki-сущность [[wiki:3316]] (`concepts/runbooks-index`, .admin) — единственный источник «какой ранбук для чего». **Прибит в AGENTS.md** — контур обязателен. > Файловый канал `.admin/.wiki/concepts/` закрыт (2026-08-29, task:1507): файлы — стубы > «не читать, не править», канон — mappa wiki-сущности. Перед ЛЮБОЙ прод-операцией (деплой/редеплой/рестарт/ротация/миграция/инцидент): 1. **Прочитай индекс** (`wiki_get(project=".admin", slug="concepts/runbooks-index")`, или [[wiki:3316]]) — найди строку по проекту/операции → ранбук (wiki-сущность). 2. Ранбук может жить в двух местах (индекс указывает, где): - mappa wiki-сущности `.admin` (`wiki_get`/`wiki_search`) — канон для VDS-проектов ([[wiki:160]], [[wiki:1254]], [[wiki:3330]] и т.д.; полный список — в индексе); - `<репо-проекта>/.wiki/concepts/docker-deploy.md` и т.п. — репо-вики проекта (pilorama98.ru: `apps/web/.wiki/concepts/docker-deploy.md`) — репо-вики живут файлом, это канал самого проекта, не `.admin`. 3. **Нет ранбука → НЕ деплоить молча.** Создать (см. WRITE) до/вместе с операцией: отдельной таской или в теле операционной таски (пункт «нужен ранбук»). Это не бюрократия: отсутствие ранбука = повторное рыскание в следующий раз. ## 1. USE — найти и прочитать ранбук - Сначала индекс → ранбук. Не начинать grep по сессиям/чатам — это анти-паттерн (источник этой секции: инцидент 2026-08-26 pilonuxt — рыскал, ранбука не было). - Прочитать ранбук **целиком** перед операцией (секреты — плейсхолдеры, реальные значения — из pass по указателям; ранбук сам секретов не несёт). - Сверить актуальность: теги/версии на проде могут обогнать ранбук (пример: stostayer-web ранбук показывал 0.3.23, прод был 0.3.26 → тег брать с проде, а ранбук потом обновить — WRITE). Если расхождение → пометить на апдейт. ## 2. EXECUTE — деплой/операция по ранбуку Выполнять шаги ранбука как чек-лист, **не пропуская**: 1. **Предусловия** (auth: JWT/токены из pass; docker login; pull-ДО-рестарта; .dockerignore/.yarnrc временные модификации — пометить на возврат). 2. **Шаги операции** — дословно по ранбуку, порядок важен (gotchas в ранбуке). 3. **Verify** по секции ранбука (страницы/эндпоинты/логи/uptime) — зелёный перед закрытием. При красном — rollback-путь из ранбука, не импровизация. 4. **Фиксация результата:** - sync source-of-truth compose (если менялся тег) → commit + push; - письмо-отчёт заказчику (inbox_send, from `.admin`, с verify-таблицей); - закрыть операционную таску (reason = что сделано + verify); - при необходимости — обновить ранбук (WRITE): новый тег, новые gotchas. Ограничения: одна попытка там, где ранбук велит одну (egress-баны, retry-штормы); не отклоняться от ранбука без причины — отклонение фиксировать в письме. ## 3. WRITE / UPDATE — создание и ведение ранбуков Канон (наследие writing-runbooks v1.0.0, поглощено): ### Жёсткие правила 1. **Ранбук — служебный документ `.admin`.** Применять может только `.admin`. 2. **Из проекта не выносить.** Не копировать в другие вики, не публиковать. 3. **Деплой = таска + письмо админу.** Любая прод-операция — по задаче на борде `.admin` и письму. Исполнитель-не-админ ставит задачу, не деплоит сам. 4. **Служебный блок — в первых абзацах** (машиночитаемый маркер служебности): ```markdown > **⚙️ СЛУЖЕБНЫЙ РАНБУК — только для администратора проекта `.admin`.** > Применять/выполнять шаги может только **`.admin`** (оператор проекта admin). Другим проектам/агентам — читать по запросу, не выполнять. > Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать. > Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют. ``` Дословно, без перефразирования. ### Гигиена секретов (решение 5, write-тайм сканер mappa) **В ранбуках никогда не бывает реальных секретов.** Только плейсхолдеры + указатели на pass: `<из pass />`. Сканер блокирует запись (422) на password/token/api_key/secret+значение ≥6 симв., AKIA…, JWT, ssh-ключи. Обход плейсхолдером: значение <6 симв. (`'<...>'`), либо ключ-слово не латиницей, либо разрыв `: ` коротким словом (`PASSWORD: см. pass (…)`). После записи — проверить `admin_secret_scan` (0 хитов). ### Структура ранбука 1. Frontmatter: `title`, `type: concept`, `tags: [.., runbook]`, `related`, `updated`. 2. H1 + служебный блок (обязательно, дословно). 3. Scope (VDS, стек Portainer Id, endpointId, source-of-truth compose). 4. Артефакты (код/образ/стек/БД/эндпоинт; тег = как на проде). 5. Шаги операции (копируемые команды) + таблица «рестарт vs пересборка» если уместно. 6. Verify/smoke после операции. 7. Rollback-путь всегда. 8. Gotchas из практики (нумерованные, с датой). ### Ведение (UPDATE) Обновлять ранбук когда: - прод ушёл вперёд (новый тег/версия) — поправить инвентарь/таблицы; - появилась новая gotcha (инцидент с неочевидной причиной); - изменился канал деплоя (адреса/стек/порядок). После правки: bump `updated:`, синхронизировать с индексом (что покрывает), проверить secret_scan. Коммит отдельный от операционного («docs(runbook): …»). ## Порядок записи (мутации вики) - **Ранбук живёт ТОЛЬКО в mappa как wiki-сущность** (канон стуб wiki:3328 р.10, 2026-08-29): `wiki_create(project=".admin", slug="concepts/<имя>")` (или `wiki_update` при правках). Файл `.admin/.wiki/concepts/<имя>.md` — стуб-указатель «не читать, не править»; git-история стуба хранит прежний контент (`git show :`). - Индекс ([[wiki:3316]]) — обновить строку/ссылку на новый ранбук. - Секрет-сканер: `mcp__mappa__admin_secret_scan` после записи — 0 hits. ## Место жительства этого скила Скил лежит в `.admin/.agents/skills/admin-runbooks/SKILL.md` — проектные скилы `.admin` (pi: `.agents/skills/` в cwd). НЕ дублировать в `~/.agents/skills/` (глобальная установка, перезаписывается update-skills) и НЕ в общий skills-репо. Обновление — правкой файла в проекте + commit/push (.admin). ## Связи - [[wiki:3316]] (`concepts/runbooks-index`) — индекс ранбуков (обязательный первый шаг). - [[wiki:2608]] (AGENTS .admin) — канон зоны: runbooks rule, artifact placement rule. - `writing-skills` — RED-GREEN-REFACTOR для скилов (если править сам скил). - `using-vds-ops` — диагностика контейнеров (read-only), не деплой. - `project-discipline` — семвер/пуш-правила при правке версионируемых артефактов.