Внешние трекеры и инструменты

Эта страница описывает интеграции с трекерами уровня namespace: создание и зеркалирование задач, приём вебхуков и привязку evidence разработки. Про сетевую топологию (resolver-ноды, runner-агенты, MCP-сервер) читайте в Руководстве по интеграциям.

После настройки авторизованные пользователи могут отправлять аномалии или задачи Mockarty Tasks во внешний трекер. Явно зеркалированные задачи сохраняют связь с внешней задачей; поддерживаемые входящие вебхуки обновляют выбранные поля и evidence разработки.

Поддерживаемые трекеры

Обновление каталога Allure TestOps

Подключение Allure в пространстве с forward_pull: true обновляет названия,
описания и теги кейсов из заданных base_url и числового project_id.
Каждый проход читает весь каталог. Переименование сохраняет привязку кейса;
проекты на разных серверах TestOps различаются. Очищенные в источнике описания
и теги очищаются и в импортированных кейсах. Кейсы, вручную отсоединённые
от источника, автоматически не присоединяются обратно.

Временные ответы источника (429, 502, 503, 504) и сетевые сбои чтения
повторяются не более двух раз. Учитывается Retry-After: ожидание более 30
секунд завершает текущий проход, а курсор остаётся прежним до следующей
плановой попытки. Отправка результатов и обмен токенов не повторяются.

Это обновление не переносит весь проект TestOps: для шагов, медиа, процессов,
истории и связей прогонов необходима дальнейшая поддержка миграции.
Конфликт одинаковых названий с существующим кейсом возвращает ошибку.
Старые импортированные записи без привязки к серверу блокируют автоматическое
обновление до явного сопоставления источника; не удаляйте их для обхода проверки.
Перед включением на рабочем каталоге проверьте подключение с сохранённым токеном
и используемую версию TestOps.

Если TestOps недоступен и сохранённое подключение нужно сразу остановить,
отправьте PATCH /api/v1/namespaces/{namespace}/integrations/{id} с телом
{"enabled":false}. Конфигурация и сохранённый токен останутся на месте.
Для этого запроса не требуется разрешать DNS-имя уже настроенного сервера;
изменение адреса или других параметров подключения проходит обычную проверку.

Авторизация для обновления каталога

Задайте auth_mode в конфигурации подключения Allure:

• bearer (также используется, если поле не задано): сохранённые учётные данные
  уже являются access token. Mockarty отправляет его напрямую как Bearer.
• api_token: сохранённые учётные данные являются персональным API token.
  Mockarty обменивает его на краткосрочный access token на указанном сервере
  TestOps и использует полученный токен для запросов каталога. Кешированный
  токен обновляется до истечения указанного сервером срока. Если TestOps не
  сообщает срок, токен используется без кеширования.

Пример конфигурации подключения; сохраните учётные данные отдельно:

{
  "base_url": "https://testops.example.com",
  "project_id": 7,
  "forward_pull": true,
  "auth_mode": "api_token"
}

Укажите точный адрес сервера TestOps: схему, имя хоста и, при необходимости,
порт, без пути и query-параметров. Перенаправления отклоняются. Обмен следует
документации авторизации Allure TestOps API.
Перед включением обновления проверьте совместимость со своей версией TestOps.

При api_token кнопка Проверить подключение проверяет доступ к проекту
через актуальный API TestOps. Ссылки на кейсы и прогоны получают данные по
проектным ID, а поиск кейсов использует AQL. Режим bearer сохраняет прежний
протокол поиска и ссылок. Успешная проверка подключения подтверждает доступ,
но не полноту миграции.

Добавление интеграции

1. Откройте Безопасность, откройте аномалию и выберите провайдер в блоке Отправить в трекер.
2. Нажмите Отправить. Если провайдер ещё не настроен, Mockarty откроет модальное окно Внешние трекеры вместо отправки.
3. Заполните конфигурацию под адаптер (base URL, ключ проекта, …) и вставьте API-токен.
4. Нажмите Сохранить. Кнопка Проверить подключение становится доступна после создания конфигурации.
5. Нажмите Проверить подключение — Mockarty выполнит минимальный API-вызов и сохранит последний вердикт.

Сохранённые токены доступны только на запись: UI и API никогда не возвращают их значение. При хранении они шифруются, если администратор настроил в Mockarty ключ шифрования PII.

Что хранит Mockarty

Сохранённые учётные данные интеграций пространства

При настройке интеграции пространства через API или MCP поле secretsRef
содержит UUID уже сохранённых в Mockarty учётных данных, а не сам токен.
Некорректный UUID и UUID из нулей отклоняются. При обновлении подключения
не передавайте secretsRef, чтобы оставить текущие учётные данные, или
передайте пустую строку, чтобы отсоединить их. После замены учётных данных
нажмите Проверить подключение.

• Конфигурация принадлежит одному namespace и одному провайдеру.
• Токен и секрет вебхука доступны только на запись; API сообщает лишь, задано ли значение.
• Зеркалирование создаёт явную связь локальной и внешней задачи. Произвольный текст с похожим ключом не становится синхронизируемой записью автоматически.
• Вебхуки разработки добавляют канонические HTTP(S)-ссылки на ветки, коммиты, merge/pull request и пайплайны.

Необходимые права

Диагностика

Test credentials failed (401 / 403). Токен просрочен или не имеет нужных прав — выпустите заново со scope’ами выше.

Test credentials failed (сетевой таймаут). Проверьте, что admin-нода видит URL трекера напрямую. За корпоративным прокси — экспортируйте HTTPS_PROXY для сервера Mockarty и перезапустите.

Зеркалированная задача не обновляется. Проверьте provider-specific URL и секрет вебхука задач, а также подписку на нужные события задач/комментариев во внешней системе.

Отправка в трекер (создание тикета в один клик)

Доступно из модалки деталей аномалии в Security Agent. Превращает аномалию безопасности в тикет вашего трекера одним кликом — название, серьёзность, сканер, CVE/CWE, оценка CVSS, доказательства, рекомендации по исправлению и AI-анализ автоматически форматируются в тело тикета. Также добавляется ссылка на аномалию в Mockarty для обратной трассировки.

Поддерживаемые трекеры

Как использовать

1. Откройте любую аномалию на странице Безопасность.
2. В модалке деталей найдите строку Отправить в трекер под полем bug URL.
3. Выберите трекер из выпадающего списка (Jira / Linear / GitHub / GitLab).
4. Нажмите Go.
5. Тикет создан, его URL автоматически заполняется в поле bug tracker URL.

Что попадает в тикет

Тело тикета формируется по стандартному шаблону. Заголовки внутри шаблона —
это то, что продукт кладёт в тикет, поэтому они приведены дословно:

## {title}
{description}

| Field    | Value     |
|----------|-----------|
| Scanner  | sql_inj   |
| Severity | critical  |
| CVE      | CVE-2024  |
| CWE      | CWE-89    |
| CVSS     | 9.8       |
| Target   | /api/...  |

### Evidence

{raw evidence}

### Remediation
{fix guidance}

### AI Analysis
{LLM analysis summary}

---
[Mockarty finding]({url}) · ID: {id}

Настройка

Учётные данные трекера хранятся на уровне пространства. Для настройки:

1. Откройте Безопасность, откройте аномалию, выберите провайдер в блоке Отправить в трекер и нажмите Отправить. Для ненастроенного провайдера Mockarty откроет окно настроек без создания тикета.
2. Заполните:
   • URL — Jira: https://company.atlassian.net, Linear: https://api.linear.app. GitHub: оставьте пустым для github.com (GitHub Cloud); для GitHub Enterprise Server укажите адрес вашей инсталляции, например https://github.company.com (Mockarty сам обращается к её API по пути /api/v3). GitLab: укажите URL инсталляции, например https://gitlab.com или https://gitlab.company.com; Mockarty сам добавляет /api/v4.
   • Токен — API-токен Jira, персональный ключ Linear, GitHub PAT или GitLab access token
   • Проект — Jira: ключ проекта (SEC), Linear: ключ команды, GitHub: owner/repo, GitLab: путь проекта (team/app) или числовой ID проекта
   • Email (только Jira) — email аккаунта Atlassian, владеющего API-токеном
   • Тип задачи (только Jira) — Bug (по умолчанию), Task, или Story
   • Метки — через запятую, автоматически применяются к каждому тикету
3. Нажмите Test credentials для проверки.
4. Сохраните.

Двусторонняя синхронизация (входящий вебхук)

Когда вы отзеркаливаете задачу Mockarty Tasks в Jira, GitHub или GitLab, связь запоминается. Двусторонняя синхронизация замыкает цикл: изменение, сделанное во внешнем трекере (сменили статус, отредактировали заголовок, добавили комментарий), автоматически возвращается в отзеркаленную задачу Mockarty — без ручного повторного импорта.

Настройка

1. Откройте модальное окно Внешние трекеры, как описано выше, и раскройте секцию Двусторонняя синхронизация (входящий вебхук) на карточке Jira, GitHub или GitLab.
2. Скопируйте показанный URL вебхука. Он выглядит так:
   https://your-mockarty/api/v1/public/issuetracker/<namespace>/webhook/jira
3. Нажмите Сгенерировать, чтобы создать секрет вебхука, затем Сохраните. Секрет показывается один раз — скопируйте его сразу; потом Mockarty сообщает лишь, что секрет задан, но не его значение.
4. Во внешнем трекере добавьте вебхук на этот URL:
   • Jira — Project settings → Webhooks → Create. Вставьте URL и добавьте секрет как заголовок запроса X-Mockarty-Webhook-Secret. Подпишитесь на Issue updated и Comment created.
   • GitHub — Repository settings → Webhooks → Add webhook. Вставьте URL в Payload URL, секрет — в поле Secret (GitHub подписывает каждую доставку), content type application/json, выберите события Issues и Issue comments.
   • GitLab — Project → Settings → Webhooks. Вставьте URL, укажите секрет в поле Secret token и включите события задач и комментариев/заметок. GitLab передаёт токен в X-Gitlab-Token.

Что синхронизируется внутрь

Названия статусов сопоставляются гибко: Done / Closed / Resolved → Готово, In Progress / Doing → В работе, In Review / QA / Testing → На ревью, To Do / Backlog / Open → К выполнению. Статус, не совпавший ни с одной колонкой, оставляется без изменений.

Доставки без секрета или с неверным секретом отклоняются. Событие для задачи, которая никогда не зеркалилась, игнорируется.

Связи задачи с разработкой

На карточках интеграций GitHub и GitLab также показан отдельный URL вебхука Связи с кодом. Добавьте его в репозиторий/проект с тем же секретом провайдера. Включите ключ задачи Mockarty в имя ветки, например ABC-12-fix-login. После этого push-события, pull/merge request и CI-прогоны с этой веткой автоматически привязываются к задаче.

Откройте панель задачи, чтобы увидеть ссылки по группам Ветки, Коммиты, Merge requests и Пайплайны, включая состояние во внешней системе, если провайдер его передал. Сначала в каждой группе показывается не больше шести записей; Показать все раскрывает только выбранную группу.

Импорт задач в Mockarty Tasks

Два пути импорта переносят существующие задачи в трекер пространства имён. Оба
принимают либо сырой JSON в теле запроса, либо multipart-загрузку file
(до 10 МиБ); типы, статусы и приоритеты автоматически маппятся на встроенные.

Из Jira

curl -X POST "http://localhost:5770/api/v1/namespaces/<ns>/issuetracker/import/jira" \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @jira-export.json

Формат — каноничный Jira REST search ({"issues":[…]}), то есть то, что
возвращает Jira API. Проекты создаются по префиксам ключей задач; родительские
связи и комментарии переносятся. POST .../import/jira/pull подтягивает задачи
напрямую из настроенного подключения к Jira вместо файла.

Из другого пространства имён Mockarty (слияние)

Экспортируйте проект из исходного пространства имён и импортируйте в целевой — так
объединяются трекеры двух команд при консолидации пространств имён:

# 1. В исходном пространстве имён: экспорт проекта в JSON
curl ".../namespaces/<source-ns>/issuetracker/projects/<projectId>/export?format=json" \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" -o project.json

# 2. В целевом пространстве имён: слияние
curl -X POST ".../namespaces/<target-ns>/issuetracker/import/mockarty" \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @project.json

Целевой проект находится или создаётся по префиксу ключа; связи родитель-потомок
сохраняются. Слияние идемпотентно: уже импортированные задачи (по исходному
ключу) пропускаются, повторный запуск ничего не дублирует — в ответе поле
alreadyPresent рядом с issuesCreated.

Что переносится. Заголовок, описание, тип, статус, резолюция, приоритет,
метки, связи родитель-потомок — и плановые данные, которые вводил человек:
story points, даты начала и срока, исходная и оставшаяся оценки, поле
environment и ваши кастомные поля.

Что не переносится и почему. Спринты и состояния workflow называют
сущности, существующие только в исходном пространстве имён — у целевого свои,
и задача с ними указывала бы в пустоту. Ранг на доске и номера задач
позиционны и назначаются заново. Исполнитель и репортёр переносятся как есть;
если таких пользователей в целевом пространстве нет, поля сохраняют исходное
значение, а не молча очищаются, — так ничего не теряется, пока вы сверяете
учётные записи.