2026-08-06 14:43:10 +03:00
parent 035bededb0
commit 8b273c9a72
16 changed files with 925 additions and 469 deletions
@@ -1,71 +1,52 @@
---
name: jira-workflow
description: Используй, когда нужно работать с корпоративным трекером задач (Jira) — прочитать тикет по ключу, добавить комментарий, приложить ссылку на MR, разобраться в статусах и переходах. Применяй при упоминании ключей задач, «тикет», «задача в трекере», «переведи в статус», а также в командах /bugfix и /feature.
description: Используй, когда нужно работать с корпоративным трекером задач (Jira) — прочитать тикет по ключу, создать/обновить задачу, добавить комментарий, перевести по статусам, найти по JQL, приложить ссылку на MR. Применяй при упоминании ключей задач, «тикет», «задача в трекере», «переведи в статус», а также в командах /bugfix и /feature.
---
# Работа с трекером задач (Jira)
Скилл описывает, как читать и обновлять задачи в нашем трекере через REST API.
Jira работает через **нативные инструменты pi** (регистрируют `extensions/jira-tools.ts`).
Никаких bash-скриптов и MCP — вызывай инструменты напрямую.
## Откуда берутся адрес и токен
## Откуда адрес и токен
**Никогда не хардкодь и не спрашивай их отдельно — они уже есть в окружении.**
- **Адрес трекера** — из `trackerUrl` в `config/company.json` (в контекст сессии инжектит
  `company-context`). Можно переопределить `TRACKER_URL`.
- **Токен** — `JIRA_TOKEN` (personal access token) из `~/.config/pi-kit/env.sh`.
- Токен не подставляй в команды и не логируй — инструменты читают его сами.
- **Базовый адрес трекера** — из переменной окружения `TRACKER_URL`. Если она не задана,
  возьми адрес трекера из корпоративного контекста сессии (его инжектит расширение
  `company-context`).
- **Токен доступа** — из переменной окружения `JIRA_TOKEN` (personal access token).
- Токен в команды и логи не подставляй в открытом виде — скрипты читают его из окружения сами.
## Инструменты
Для создания merge request в GitLab дополнительно нужен `GITLAB_TOKEN` (токен с scope `api`);
хост и путь проекта скрипт определяет из `git remote origin` (или `GITLAB_HOST`) — адреса не хардкодятся.
- **`jira_issue_get(key)`** — получить тикет (summary, status, description).
- **`jira_issue_create(projectKey, summary, issuetype, ...)`** — создать задачу.
- **`jira_issue_update(key, {summary?, description?, status?, ...})`** — обновить поля,
  `status` переводит по доступным переходам.
- **`jira_issue_comment(key, text)`** — добавить комментарий.
- **`jira_issue_transition(key, target)`** — перевести в статус
  (`To Do` / `In Progress` / `Review` / `Done`, поддерживаются русские синонимы).
- **`jira_search(jql, maxResults?)`** — поиск по JQL.
- **`jira_link_mr(key, mrUrl, title?)`** — привязать ссылку на MR (комментарием).
Быстрая проверка окружения:
## Типовой поток багфикса (/bugfix)
```bash
: "${TRACKER_URL:?установи TRACKER_URL или возьми адрес из корпоративного контекста}"
: "${JIRA_TOKEN:?установи JIRA_TOKEN (personal access token трекера)}"
```
## Готовые скрипты
Все скрипты лежат в `scripts/` и читают `TRACKER_URL` и `JIRA_TOKEN` из окружения:
- `./scripts/get-issue.sh <KEY>` — получить тикет (поля summary, status, description).
- `./scripts/add-comment.sh <KEY> "<текст>"` — добавить комментарий.
- `./scripts/link-mr.sh <KEY> "<url-MR>" ["<заголовок>"]` — приложить ссылку на MR
  (добавляется комментарием со ссылкой; при доступном remote link API — см. TODO в скрипте).
- `./scripts/create-mr.sh "<title>" [target] [source] [jira-key]` — создать merge request в
  GitLab (по текущей ветке), вывести его URL и, если передан `jira-key` и заданы
  `TRACKER_URL`/`JIRA_TOKEN`, автоматически приложить ссылку к тикету.
Пример:
```bash
./scripts/get-issue.sh PROJ-123
./scripts/add-comment.sh PROJ-123 "Начал работу, воспроизвёл баг"
./scripts/link-mr.sh PROJ-123 "https://<git-host>/ai/foo/-/merge_requests/42" "Fix PROJ-123"
# создать MR из текущей ветки в main и сразу привязать к тикету:
GITLAB_TOKEN=... ./scripts/create-mr.sh "Fix PROJ-123: NPE" main "" PROJ-123
```
Флаги окружения `create-mr.sh`: `GITLAB_TOKEN` (обязателен), `GITLAB_HOST` (override хоста),
`MR_PUSH=0` (не пушить ветку), `MR_DRY_RUN=1` (показать запрос без вызова API).
MR из защищённой/релизной ветки (`main`/`master`/`release-*`) скрипт создавать откажется.
1. `jira_issue_get <KEY>` — прочитать постановку.
2. `jira_issue_transition <KEY> "In Progress"` — при старте работы.
3. Создать ветку/фикс (языковые стандарты — в профильном скилле).
4. Перед мержем — `gitlab_mr_create` (см. скилл gitlab) и
   `jira_link_mr <KEY> <url-MR>` — привязать MR к тикету.
5. `jira_issue_transition <KEY> "Review"` — после выставления MR.
6. `jira_issue_transition <KEY> "Done"` — после мержа.
## Соглашения
- **Формат ключей задач:** вида `PROJ-123` (буквенный префикс проекта + номер).
  `<!-- TODO: перечислить реальные префиксы проектов -->`
- **Статусы и переходы:** To Do → In Progress → Review → Done.
- **Кто и когда меняет статус:** разработчик переводит тикет: в **In Progress** — при старте работы;
  в **Review** — при выставлении MR (в тикет добавляется ссылка на MR); в **Done** — после мержа.
- **Что писать в комментарии:** при старте — кратко о начале работы; при готовности — ссылку на MR
  (используй `create-mr.sh`, который сразу приложит ссылку, либо `link-mr.sh`).
- **Формат ключей:** `PROJ-123` (префикс проекта + номер).
- **Статусы:** To Do → In Progress → Review → Done.
- **Переходы:** при старте — In Progress; при готовности MR — Review (с ссылкой на MR);
  после мержа — Done.
- Если `jira_issue_update` со `status` не смог найти переход — инструмент вернёт список
  доступных статусов; уточни нужный.
## Полезное
- ID переходов статуса можно получить через `GET /rest/api/2/issue/<KEY>/transitions`,
  выполнить переход — `POST` туда же с `{"transition":{"id":"<id>"}}`.
- Если API возвращает 401/403 — проверь `JIRA_TOKEN` и права. Не логируй сам токен.
- `jira_search` удобен для «что в работе у меня»: `jira_search('assignee = currentUser() AND status != Done')`.
- Токен лежит в `~/.config/pi-kit/env.sh` (chmod 600).