@yadsh/dsh-qa-integrations 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +617 -0
- package/compatibility.json +10 -0
- package/cordis.patch.yml +5 -0
- package/lib/broker.js +239 -0
- package/lib/broker.js.map +1 -0
- package/lib/client/bitrix24.js +33 -0
- package/lib/client/bitrix24.js.map +1 -0
- package/lib/client/card.js +33 -0
- package/lib/client/card.js.map +1 -0
- package/lib/client/confluence.js +148 -0
- package/lib/client/confluence.js.map +1 -0
- package/lib/client/copy.js +18 -0
- package/lib/client/copy.js.map +1 -0
- package/lib/client/gitlab.js +64 -0
- package/lib/client/gitlab.js.map +1 -0
- package/lib/client/index.js +71 -0
- package/lib/client/index.js.map +1 -0
- package/lib/client/integrations.js +34 -0
- package/lib/client/integrations.js.map +1 -0
- package/lib/client/jira.js +150 -0
- package/lib/client/jira.js.map +1 -0
- package/lib/client/provider-card.js +143 -0
- package/lib/client/provider-card.js.map +1 -0
- package/lib/client/styles.js +35 -0
- package/lib/client/styles.js.map +1 -0
- package/lib/client/teamcity.js +55 -0
- package/lib/client/teamcity.js.map +1 -0
- package/lib/client.js +8069 -0
- package/lib/client.js.map +1 -0
- package/lib/coerce.js +69 -0
- package/lib/coerce.js.map +1 -0
- package/lib/config.js +51 -0
- package/lib/config.js.map +1 -0
- package/lib/errors.js +14 -0
- package/lib/errors.js.map +1 -0
- package/lib/index.js +510 -0
- package/lib/index.js.map +1 -0
- package/lib/providers/bitrix24/catalog.js +245 -0
- package/lib/providers/bitrix24/catalog.js.map +1 -0
- package/lib/providers/bitrix24/config.js +40 -0
- package/lib/providers/bitrix24/config.js.map +1 -0
- package/lib/providers/bitrix24/index.js +128 -0
- package/lib/providers/bitrix24/index.js.map +1 -0
- package/lib/providers/bitrix24/operations.js +491 -0
- package/lib/providers/bitrix24/operations.js.map +1 -0
- package/lib/providers/bitrix24/tools.js +1035 -0
- package/lib/providers/bitrix24/tools.js.map +1 -0
- package/lib/providers/bitrix24/transport.js +142 -0
- package/lib/providers/bitrix24/transport.js.map +1 -0
- package/lib/providers/confluence/adf.js +348 -0
- package/lib/providers/confluence/adf.js.map +1 -0
- package/lib/providers/confluence/catalog.js +135 -0
- package/lib/providers/confluence/catalog.js.map +1 -0
- package/lib/providers/confluence/config.js +196 -0
- package/lib/providers/confluence/config.js.map +1 -0
- package/lib/providers/confluence/cql.js +78 -0
- package/lib/providers/confluence/cql.js.map +1 -0
- package/lib/providers/confluence/index.js +319 -0
- package/lib/providers/confluence/index.js.map +1 -0
- package/lib/providers/confluence/operations.js +653 -0
- package/lib/providers/confluence/operations.js.map +1 -0
- package/lib/providers/confluence/tools.js +282 -0
- package/lib/providers/confluence/tools.js.map +1 -0
- package/lib/providers/confluence/transport.js +247 -0
- package/lib/providers/confluence/transport.js.map +1 -0
- package/lib/providers/contract.js +2 -0
- package/lib/providers/contract.js.map +1 -0
- package/lib/providers/gitlab/catalog.js +171 -0
- package/lib/providers/gitlab/catalog.js.map +1 -0
- package/lib/providers/gitlab/config.js +141 -0
- package/lib/providers/gitlab/config.js.map +1 -0
- package/lib/providers/gitlab/index.js +227 -0
- package/lib/providers/gitlab/index.js.map +1 -0
- package/lib/providers/gitlab/operations.js +794 -0
- package/lib/providers/gitlab/operations.js.map +1 -0
- package/lib/providers/gitlab/tools.js +859 -0
- package/lib/providers/gitlab/tools.js.map +1 -0
- package/lib/providers/gitlab/transport.js +140 -0
- package/lib/providers/gitlab/transport.js.map +1 -0
- package/lib/providers/jira/adf.js +235 -0
- package/lib/providers/jira/adf.js.map +1 -0
- package/lib/providers/jira/catalog.js +145 -0
- package/lib/providers/jira/catalog.js.map +1 -0
- package/lib/providers/jira/config.js +198 -0
- package/lib/providers/jira/config.js.map +1 -0
- package/lib/providers/jira/index.js +301 -0
- package/lib/providers/jira/index.js.map +1 -0
- package/lib/providers/jira/jql.js +299 -0
- package/lib/providers/jira/jql.js.map +1 -0
- package/lib/providers/jira/operations.js +617 -0
- package/lib/providers/jira/operations.js.map +1 -0
- package/lib/providers/jira/tools.js +341 -0
- package/lib/providers/jira/tools.js.map +1 -0
- package/lib/providers/jira/transport.js +227 -0
- package/lib/providers/jira/transport.js.map +1 -0
- package/lib/providers/registry.js +21 -0
- package/lib/providers/registry.js.map +1 -0
- package/lib/providers/shared/account.js +20 -0
- package/lib/providers/shared/account.js.map +1 -0
- package/lib/providers/shared/host.js +15 -0
- package/lib/providers/shared/host.js.map +1 -0
- package/lib/providers/shared/http.js +148 -0
- package/lib/providers/shared/http.js.map +1 -0
- package/lib/providers/teamcity/artifacts.js +155 -0
- package/lib/providers/teamcity/artifacts.js.map +1 -0
- package/lib/providers/teamcity/catalog.js +155 -0
- package/lib/providers/teamcity/catalog.js.map +1 -0
- package/lib/providers/teamcity/config.js +262 -0
- package/lib/providers/teamcity/config.js.map +1 -0
- package/lib/providers/teamcity/index.js +228 -0
- package/lib/providers/teamcity/index.js.map +1 -0
- package/lib/providers/teamcity/locators.js +95 -0
- package/lib/providers/teamcity/locators.js.map +1 -0
- package/lib/providers/teamcity/logs.js +113 -0
- package/lib/providers/teamcity/logs.js.map +1 -0
- package/lib/providers/teamcity/network.js +160 -0
- package/lib/providers/teamcity/network.js.map +1 -0
- package/lib/providers/teamcity/operations.js +625 -0
- package/lib/providers/teamcity/operations.js.map +1 -0
- package/lib/providers/teamcity/tools.js +480 -0
- package/lib/providers/teamcity/tools.js.map +1 -0
- package/lib/providers/teamcity/transport.js +126 -0
- package/lib/providers/teamcity/transport.js.map +1 -0
- package/lib/redaction.js +38 -0
- package/lib/redaction.js.map +1 -0
- package/lib/repository.js +414 -0
- package/lib/repository.js.map +1 -0
- package/lib/secrets/key-provider.js +76 -0
- package/lib/secrets/key-provider.js.map +1 -0
- package/lib/secrets/secret-store.js +93 -0
- package/lib/secrets/secret-store.js.map +1 -0
- package/lib/shared/settings.js +19 -0
- package/lib/shared/settings.js.map +1 -0
- package/lib/tool-kit.js +55 -0
- package/lib/tool-kit.js.map +1 -0
- package/lib/tools.js +28 -0
- package/lib/tools.js.map +1 -0
- package/lib/typert.host.d.ts +3 -0
- package/lib/typert.host.js +1689 -0
- package/lib/typert.remote-client.d.ts +84 -0
- package/lib/typert.remote-client.js +1429 -0
- package/lib/types/broker.d.ts +30 -0
- package/lib/types/client/bitrix24.d.ts +18 -0
- package/lib/types/client/card.d.ts +13 -0
- package/lib/types/client/confluence.d.ts +17 -0
- package/lib/types/client/copy.d.ts +7 -0
- package/lib/types/client/gitlab.d.ts +15 -0
- package/lib/types/client/index.d.ts +13 -0
- package/lib/types/client/integrations.d.ts +28 -0
- package/lib/types/client/jira.d.ts +17 -0
- package/lib/types/client/provider-card.d.ts +63 -0
- package/lib/types/client/styles.d.ts +7 -0
- package/lib/types/client/teamcity.d.ts +19 -0
- package/lib/types/coerce.d.ts +18 -0
- package/lib/types/config.d.ts +48 -0
- package/lib/types/errors.d.ts +26 -0
- package/lib/types/index.d.ts +170 -0
- package/lib/types/providers/bitrix24/catalog.d.ts +48 -0
- package/lib/types/providers/bitrix24/config.d.ts +43 -0
- package/lib/types/providers/bitrix24/index.d.ts +31 -0
- package/lib/types/providers/bitrix24/operations.d.ts +13 -0
- package/lib/types/providers/bitrix24/tools.d.ts +9 -0
- package/lib/types/providers/bitrix24/transport.d.ts +26 -0
- package/lib/types/providers/confluence/adf.d.ts +22 -0
- package/lib/types/providers/confluence/catalog.d.ts +59 -0
- package/lib/types/providers/confluence/config.d.ts +68 -0
- package/lib/types/providers/confluence/cql.d.ts +43 -0
- package/lib/types/providers/confluence/index.d.ts +73 -0
- package/lib/types/providers/confluence/operations.d.ts +92 -0
- package/lib/types/providers/confluence/tools.d.ts +15 -0
- package/lib/types/providers/confluence/transport.d.ts +77 -0
- package/lib/types/providers/contract.d.ts +33 -0
- package/lib/types/providers/gitlab/catalog.d.ts +49 -0
- package/lib/types/providers/gitlab/config.d.ts +50 -0
- package/lib/types/providers/gitlab/index.d.ts +49 -0
- package/lib/types/providers/gitlab/operations.d.ts +40 -0
- package/lib/types/providers/gitlab/tools.d.ts +15 -0
- package/lib/types/providers/gitlab/transport.d.ts +52 -0
- package/lib/types/providers/jira/adf.d.ts +27 -0
- package/lib/types/providers/jira/catalog.d.ts +74 -0
- package/lib/types/providers/jira/config.d.ts +73 -0
- package/lib/types/providers/jira/index.d.ts +79 -0
- package/lib/types/providers/jira/jql.d.ts +51 -0
- package/lib/types/providers/jira/operations.d.ts +58 -0
- package/lib/types/providers/jira/tools.d.ts +17 -0
- package/lib/types/providers/jira/transport.d.ts +65 -0
- package/lib/types/providers/registry.d.ts +9 -0
- package/lib/types/providers/shared/account.d.ts +10 -0
- package/lib/types/providers/shared/host.d.ts +9 -0
- package/lib/types/providers/shared/http.d.ts +51 -0
- package/lib/types/providers/teamcity/artifacts.d.ts +45 -0
- package/lib/types/providers/teamcity/catalog.d.ts +55 -0
- package/lib/types/providers/teamcity/config.d.ts +66 -0
- package/lib/types/providers/teamcity/index.d.ts +62 -0
- package/lib/types/providers/teamcity/locators.d.ts +47 -0
- package/lib/types/providers/teamcity/logs.d.ts +31 -0
- package/lib/types/providers/teamcity/network.d.ts +32 -0
- package/lib/types/providers/teamcity/operations.d.ts +84 -0
- package/lib/types/providers/teamcity/tools.d.ts +15 -0
- package/lib/types/providers/teamcity/transport.d.ts +53 -0
- package/lib/types/redaction.d.ts +3 -0
- package/lib/types/repository.d.ts +48 -0
- package/lib/types/secrets/key-provider.d.ts +30 -0
- package/lib/types/secrets/secret-store.d.ts +12 -0
- package/lib/types/shared/settings.d.ts +19 -0
- package/lib/types/tool-kit.d.ts +26 -0
- package/lib/types/tools.d.ts +16 -0
- package/lib/types/types.d.ts +138 -0
- package/lib/types.js +2 -0
- package/lib/types.js.map +1 -0
- package/package.json +143 -0
package/README.md
ADDED
|
@@ -0,0 +1,617 @@
|
|
|
1
|
+
# dsh-qa-integrations
|
|
2
|
+
|
|
3
|
+
Персональные интеграции для `@yadsh/dsh-qa-surface`. Плагин подключает Bitrix24 через URL входящего вебхука, GitLab через personal access token, TeamCity через access token, а Jira и Confluence — через API-токен Atlassian, после чего даёт агенту набор read-only инструментов, ограниченный и правами подключения, и персональной политикой пользователя.
|
|
4
|
+
|
|
5
|
+
Плагин показывает подключения двумя монтированиями одного и того же набора карточек: отдельным разделом **«Интеграции»** в пользовательских настройках QA и карточкой плагина в разделе **«Настройки → Плагины → Конфигурация плагинов»** хоста — там же, где настройки остальных внешних плагинов. Карточка хоста читает аккаунт через клиентский сервис `qaUserSession` плагина `@yadsh/dsh-qa-surface`: без входа в QA она ничего не показывает и не делает запросов, пока её не раскрыли. Токен вводится один раз, шифруется на Host и никогда не возвращается браузеру. Выбор пользователя, integration id, secret id или токена отсутствует в model-visible схемах: principal берётся из DSH-сессии, а Bitrix user id — из сохранённой записи интеграции.
|
|
6
|
+
|
|
7
|
+
## Структура
|
|
8
|
+
|
|
9
|
+
Один каталог — одна интеграция. Всё, что знает про Bitrix24, GitLab, TeamCity, Jira и Confluence, лежит в своём каталоге `src/providers/<id>/`: каталог возможностей и операций, построение запросов, HTTP-граница, срез конфига и тулы. У TeamCity отдельно лежат locator-синтаксис, обработка логов, политика артефактов и сеть; у Jira — JQL и ADF; у Confluence — CQL и ADF. Общий слой — брокер, репозиторий, секреты, обвязка тулов — не знает ни одной интеграции по имени: capability это свободная строка, а `providers/contract.ts` описывает, что должен уметь провайдер. Порядок добавления следующей интеграции и правила гейта пакета — в [src/providers/README.md](https://github.com/xarleyn/dsh-plugins/blob/main/plugins/dsh-qa-integrations/src/providers/README.md).
|
|
10
|
+
|
|
11
|
+
## Инструменты
|
|
12
|
+
|
|
13
|
+
CRM:
|
|
14
|
+
|
|
15
|
+
| Tool | Что делает |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| `bitrix_search_crm` | Поиск лидов, сделок, контактов, компаний, счетов и смарт-процессов по названию и ответственному |
|
|
18
|
+
| `bitrix_get_crm_item` | Полная карточка элемента CRM, включая пользовательские поля и коммуникации |
|
|
19
|
+
| `bitrix_get_crm_fields` | Схема полей типа сущности, включая `UF_CRM_*` портала |
|
|
20
|
+
| `bitrix_get_crm_funnels` | Воронки (категории) типа сущности |
|
|
21
|
+
| `bitrix_get_crm_statuses` | Расшифровка стадий и справочников (`STATUS`, `DEAL_STAGE`, `DEAL_STAGE_<id>`, `SOURCE`, …) |
|
|
22
|
+
| `bitrix_get_crm_activities` | Дела CRM: звонки, встречи, письма, задачи; просрочки и незавершённые |
|
|
23
|
+
| `bitrix_get_crm_activity` | Одно дело целиком, включая описание |
|
|
24
|
+
| `bitrix_get_crm_timeline` | Комментарии таймлайна лида, сделки, контакта, компании |
|
|
25
|
+
| `bitrix_get_crm_stage_history` | История движения по стадиям: сколько висело, куда возвращали |
|
|
26
|
+
| `bitrix_get_crm_product_rows` | Товарные позиции: что продаём, количество, цена, скидки |
|
|
27
|
+
| `bitrix_find_crm_duplicates` | Поиск дублей клиента по телефону или e-mail |
|
|
28
|
+
| `bitrix_get_crm_requisites` | Реквизиты контакта или компании: ИНН, КПП, адрес, банк |
|
|
29
|
+
| `bitrix_get_call_transcript` | Готовая AI-расшифровка звонка по делу CRM |
|
|
30
|
+
|
|
31
|
+
Сотрудники и структура:
|
|
32
|
+
|
|
33
|
+
| Tool | Что делает |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `bitrix_get_current_user` | Чей вебхук подключён |
|
|
36
|
+
| `bitrix_search_users` | Поиск сотрудников по имени, e-mail, подразделению |
|
|
37
|
+
| `bitrix_get_departments` | Подразделения, родительский отдел, руководитель |
|
|
38
|
+
| `bitrix_get_user_fields` | Какие поля сотрудника доступны с этим вебхуком |
|
|
39
|
+
|
|
40
|
+
Чаты и открытые линии:
|
|
41
|
+
|
|
42
|
+
| Tool | Что делает |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| `bitrix_search_chats` | Поиск чатов по названию и участникам |
|
|
45
|
+
| `bitrix_get_chat_messages` | Последние сообщения чата |
|
|
46
|
+
| `bitrix_search_chat_messages` | Поиск по тексту и датам внутри одного чата |
|
|
47
|
+
| `bitrix_get_recent_chats` | Последние диалоги пользователя, счётчики непрочитанного |
|
|
48
|
+
| `bitrix_search_chat_users` | Поиск сотрудника как контакта чата: статус, телефоны |
|
|
49
|
+
| `bitrix_find_chat` | Чат, привязанный к объекту: обсуждение сделки, чат задачи, событие календаря, чат группы |
|
|
50
|
+
| `bitrix_get_chat_participants` | Кто участвует в чате |
|
|
51
|
+
| `bitrix_get_chat_user_data` | Профили участников: имя, должность, телефоны, присутствие |
|
|
52
|
+
| `bitrix_get_openline_dialog` | Диалог открытой линии: участники, связь с CRM |
|
|
53
|
+
| `bitrix_get_openline_history` | История переписки с клиентом в открытой линии |
|
|
54
|
+
|
|
55
|
+
Задачи, календарь, Диск:
|
|
56
|
+
|
|
57
|
+
| Tool | Что делает |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `bitrix_search_tasks` | Задачи по названию, ответственному, группе, дедлайну |
|
|
60
|
+
| `bitrix_get_task` | Карточка задачи целиком, включая `ufCrmTask` |
|
|
61
|
+
| `bitrix_get_task_history` | История изменений задачи: что, когда и кем |
|
|
62
|
+
| `bitrix_get_task_results` | Результаты работы по задаче |
|
|
63
|
+
| `bitrix_get_task_elapsed_time` | Затраченное время: кто сколько залогировал |
|
|
64
|
+
| `bitrix_get_calendar_events` | События календаря сотрудника, группы или компании |
|
|
65
|
+
| `bitrix_get_calendar_accessibility` | Занятость сотрудников, чтобы предложить время встречи |
|
|
66
|
+
| `bitrix_search_files` | Поиск по Диску, включая текст внутри документов |
|
|
67
|
+
| `bitrix_get_file` | Метаданные и ссылка на файл Диска |
|
|
68
|
+
| `bitrix_get_drives` | Доступные диски и их id |
|
|
69
|
+
| `bitrix_get_storage_items` | Содержимое корня диска |
|
|
70
|
+
| `bitrix_get_folder_items` | Содержимое папки Диска |
|
|
71
|
+
|
|
72
|
+
Списочные инструменты отвечают единым конвертом `{ items, pagination }`: у модели одна форма ответа вместо шести разных у REST, а курсор следующей страницы не теряется. Методы, возвращающие словари по id (история открытой линии, занятость), спроецированы в упорядоченные массивы.
|
|
73
|
+
|
|
74
|
+
## Инструменты GitLab
|
|
75
|
+
|
|
76
|
+
| Tool | Что делает |
|
|
77
|
+
| --- | --- |
|
|
78
|
+
| `gitlab_connection_get` | К какому инстансу и каким пользователем подключён аккаунт |
|
|
79
|
+
| `gitlab_projects_list` | Поиск проектов: путь, ветка по умолчанию, видимость |
|
|
80
|
+
| `gitlab_project_get` | Карточка проекта: описание, namespace, даты |
|
|
81
|
+
| `gitlab_repository_tree` | Содержимое каталогов на выбранном ref, постранично |
|
|
82
|
+
| `gitlab_repository_file_get` | Текст файла с метаданными; бинарное и слишком большое — только метаданные |
|
|
83
|
+
| `gitlab_commits_list` | Коммиты проекта, ветки или одного файла |
|
|
84
|
+
| `gitlab_commit_get` | Один коммит: сообщение, автор, родители, объём изменений |
|
|
85
|
+
| `gitlab_compare` | Сравнение двух refs: коммиты и изменённые файлы |
|
|
86
|
+
| `gitlab_search` | Поиск по проектам, задачам, MR, коммитам, коду и комментариям |
|
|
87
|
+
| `gitlab_issues_list` | Задачи по проекту, состоянию, автору, исполнителю, меткам, датам |
|
|
88
|
+
| `gitlab_issue_get` | Карточка задачи: описание, веха, срок |
|
|
89
|
+
| `gitlab_issue_notes_list` | Комментарии задачи, системные помечены |
|
|
90
|
+
| `gitlab_merge_requests_list` | Merge requests по проекту, веткам, автору, ревьюеру, черновику |
|
|
91
|
+
| `gitlab_merge_request_get` | Карточка MR: описание, ветки, статус слияния, конфликты |
|
|
92
|
+
| `gitlab_merge_request_changes_get` | Изменённые файлы MR с диффами |
|
|
93
|
+
| `gitlab_merge_request_discussions_list` | Обсуждения ревью и их разрешение |
|
|
94
|
+
| `gitlab_merge_request_approvals_get` | Сколько одобрений нужно, сколько есть, кто одобрил |
|
|
95
|
+
| `gitlab_merge_request_pipelines_list` | Пайплайны, привязанные к MR |
|
|
96
|
+
| `gitlab_pipelines_list` | Пайплайны проекта по ветке, статусу, источнику, автору |
|
|
97
|
+
| `gitlab_pipeline_get` | Один пайплайн: статус, длительности, покрытие |
|
|
98
|
+
| `gitlab_pipeline_jobs_list` | Джобы пайплайна: стадия, статус, длительность |
|
|
99
|
+
| `gitlab_job_get` | Одна джоба: причина падения, теги, список артефактов |
|
|
100
|
+
| `gitlab_job_log_get` | Лог джобы: ограничен по размеру и очищен от токенов |
|
|
101
|
+
|
|
102
|
+
Списочные инструменты GitLab отвечают тем же конвертом `{ items, pagination }`; `pagination.nextPage` — это номер следующей страницы, а не подписанный курсор: состояние между вызовами не хранится, principal и права перепроверяются на каждом вызове.
|
|
103
|
+
|
|
104
|
+
Диффы (`gitlab_compare`, `gitlab_merge_request_changes_get`) отдают список файлов целиком, а текст диффов — в пределах общего бюджета символов; при обрезке ответ помечается `diffTruncated`. Логи CI обрезаются по лимиту стенда и дополнительно проходят через редакцию секретов: встроенная маскировка GitLab — фильтр, а не гарантия.
|
|
105
|
+
|
|
106
|
+
## Инструменты TeamCity
|
|
107
|
+
|
|
108
|
+
| Tool | Что делает |
|
|
109
|
+
| --- | --- |
|
|
110
|
+
| `teamcity_connection_get` | К какому серверу TeamCity и каким пользователем подключён аккаунт, версия сервера |
|
|
111
|
+
| `teamcity_projects` | Проекты: поиск по id и названию, дочерние проекты, архивные |
|
|
112
|
+
| `teamcity_build_configs` | Конфигурации сборки: id, название, проект, пауза |
|
|
113
|
+
| `teamcity_builds` | Поиск сборок по проекту, конфигурации, ветке, статусу, состоянию и датам |
|
|
114
|
+
| `teamcity_build` | Одна сборка: состояние, статус и его текст, агент, кто запустил, времена |
|
|
115
|
+
| `teamcity_build_changes` | Изменения в VCS, попавшие в сборку: ревизия, автор, дата, комментарий |
|
|
116
|
+
| `teamcity_build_failures` | Почему упало: упавшие тесты и проблемы сборки одним ответом |
|
|
117
|
+
| `teamcity_build_log` | Фрагмент лога сборки: конец, начало или строки по поиску |
|
|
118
|
+
| `teamcity_queue` | Очередь сборки: что ждёт агента и на какой ветке |
|
|
119
|
+
| `teamcity_investigations` | Расследования падений: состояние, ответственный, разрешение |
|
|
120
|
+
| `teamcity_agents` | Агенты сборки: подключён, включён, авторизован |
|
|
121
|
+
| `teamcity_artifacts` | Артефакты сборки: имя, путь, размер, время изменения |
|
|
122
|
+
| `teamcity_artifact_text` | Текст небольшого артефакта: отчёты тестов, лог-файлы |
|
|
123
|
+
|
|
124
|
+
Списочные инструменты TeamCity отвечают конвертом `{ items, pagination }`, где `pagination.returned` — сколько строк вернулось, а `pagination.hasMore` — что сервер отдал не всё: инструмент никогда не ходит по `nextHref` сам, поэтому продолжение получается сужением фильтра, а не вторым запросом за спиной у модели. Лимит каждого списка задан спецификацией (сборки и очередь — 50, проекты, конфигурации, изменения, тесты, проблемы, расследования и агенты — 100, артефакты — 200) и не поднимается выше, сколько бы модель ни попросила.
|
|
125
|
+
|
|
126
|
+
Лог сборки скачивается не больше, чем разрешает стенд (`maxLogBytes`, по умолчанию 256 КиБ), чистится от управляющих последовательностей терминала, проходит через редакцию секретов и режется до запрошенного числа строк (`maxLines`, максимум 1000). Ответ различает два случая: `truncated` — окно не покрыло запрошенные строки, `logTruncated` — сам лог длиннее скачанного куска, и тогда в режиме `tail` это конец скачанного, а не конец сборки. Артефакты читаются только текстовые: архивы, образы, бинарники, документы и ключи (`zip`, `jar`, `png`, `pdf`, `pem`, …) отказываются по имени до запроса, а бинарное тело отвечает метаданными с `binary: true` вместо содержимого. Логи и артефакты описаны модели как недоверенные данные: это текст из внешней системы, а не инструкция.
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
## Инструменты Jira
|
|
130
|
+
|
|
131
|
+
| Tool | Что делает |
|
|
132
|
+
| --- | --- |
|
|
133
|
+
| `jira_get_current_user` | К какому сайту Jira и каким пользователем Atlassian подключён аккаунт |
|
|
134
|
+
| `jira_search_issues` | Поиск задач: текст, проекты, типы, статусы и их категория, приоритеты, резолюции, компоненты, метки, версии (fix и affected), люди, даты, кастомные поля |
|
|
135
|
+
| `jira_get_issue` | Карточка задачи: ключ, ссылка, проект, тип, статус, приоритет, люди, метки, компоненты, версии, резолюция, даты и описание |
|
|
136
|
+
| `jira_get_issue_comments` | Комментарии задачи, от новых к старым; ограниченный комментарий помечен видимостью |
|
|
137
|
+
| `jira_get_issue_attachments` | Метаданные вложений: имя файла, тип, размер, автор; файлы не скачиваются |
|
|
138
|
+
| `jira_get_available_transitions` | Доступные переходы статуса и их обязательные поля; переход не выполняется |
|
|
139
|
+
| `jira_get_project` | Карточка проекта: ключ, название, тип, руководитель, описание, ссылка |
|
|
140
|
+
| `jira_get_fields` | Поля сайта: id, имя, признак кастомного поля, тип и JQL-имена |
|
|
141
|
+
|
|
142
|
+
Модель не получает JQL: фильтры в `jira_search_issues` типизированные, а строку запроса собирает и экранирует провайдер — значение с кавычкой или обратным слэшем остаётся значением и не может добавить условие. Поиск без единого фильтра отказывается: «все задачи сайта» — не вопрос, на который этот инструмент отвечает. Ответы идут по последнему обновлению (сначала свежие) и несут `pagination.nextCursor` — это continuation-токен самого Jira, состояние между вызовами не хранится, а страница не выходит за потолок стенда (`defaultSearchLimit`, `maxSearchLimit`) и за 100 строк, которые Jira отдаёт с полями. Комментарии Jira по-прежнему листаются позицией, поэтому их `pagination` — `{ startAt, returned, total, hasMore }`.
|
|
143
|
+
|
|
144
|
+
Словарь фильтров покрывает то, что спрашивают у корпоративной Jira, и каждый фильтр — это клауза, которую собирает `jql.ts`: проект, тип задачи, статус и **категория статуса** (`To Do` / `In Progress` / `Done` — «закрытые» одним фильтром, чем бы ни называл их workflow), приоритет, резолюция, компонент, метки (все перечисленные, а не «любая из»), версии — `fixVersions` и `affectedVersions`, включая «не проставлена» (`fixVersionEmpty: true`) и «проставлена» (`false`), исполнитель и автор, даты создания и обновления в обе стороны, и кастомные поля. Даты принимают и абсолютное значение (`2026-08-01`, ISO-таймстемп), и родной относительный токен Jira (`-3w`, `-2d`, `-4h`, `-30m`), а пара «с/по» — это `createdAfter`/`createdBefore` (границы включительные). Текст ищется двумя способами: `match: "all"` (по умолчанию) требует все слова, `match: "phrase"` — точную фразу; оба варианта бьются на отдельные клаузы `text ~ "…"`, поэтому `OR` из фразы остаётся словом, а не оператором.
|
|
145
|
+
|
|
146
|
+
Кастомные поля фильтруются **по id**, который вернул `jira_get_fields`, или **по алиасу**, который объявил оператор стенда: `customFields: [{ field: "product", value: "…" }]`, с `match: "contains"` для текстовых полей и `empty: true`/`false` для пустого/заполненного. Имя поля Jira не принимается намеренно — на одном сайте легко живут несколько полей с одинаковым именем, а какой из них «продукт», знает только развёртывание: соответствие «алиас → `customfield_…`» задаётся в конфиге оператора (`jira.fieldAliases`), поэтому в репозитории нет ни одного id конкретного инстанса, а каталог полей (`jira_get_fields`) отдаёт объявленные алиасы вместе со схемой. Неизвестное имя — отказ со списком алиасов, а не пустая страница. Люди принимаются как `me`, как accountId или как имя: имя провайдер разрешает через справочник сайта (`/rest/api/3/user/search`, не больше десяти совпадений) и подставляет accountId в запрос, потому что Jira Cloud фильтрует именно по нему. Имя, которое никого не нашло, и имя, которое нашли несколько человек, — это отказ с подсказкой, а не пустая страница: «нет задач» и «фильтр не понят» — разные ответы. Ответ справочника модели не показывается, он только определяет id, по которому построен запрос.
|
|
147
|
+
|
|
148
|
+
Описания и комментарии приходят в Atlassian Document Format и рендерятся в текст с сохранением структуры: заголовки, списки, код, ссылки, упоминания, таблицы и вложения-маркеры. Сырой JSON документа модели не отдаётся, а встроенные ссылки и медиа-узлы не загружаются. История изменений задачи читается отдельной группой `include: ["changelog_summary"]` (Jira отдаёт её только через `expand=changelog`): ответ несёт до 20 изменённых полей с автором и значениями «было/стало» и честно различает две обрезки — свою (`truncated`, упёрлись в 20 записей) и джировскую (`groupsTruncated`, Jira посчитала групп изменений больше, чем прислала). Кастомные поля называются по схеме сайта (`jira_get_fields` показывает её модель целиком): схема читается только после того, как задача ответила, и **не кэшируется** — один и тот же сайт отдаёт разный список полей двум пользователям с разными правами, а кэш на двоих был бы утечкой ради одного запроса. Тело задачи, комментария или кастомного поля ограничено `maxTextChars` (по умолчанию 20 000 символов); при обрезке ответ помечается `descriptionTruncated` или `bodyTruncated`. Текст из Jira — данные, а не инструкция.
|
|
149
|
+
## Инструменты Confluence
|
|
150
|
+
|
|
151
|
+
| Tool | Что делает |
|
|
152
|
+
| --- | --- |
|
|
153
|
+
| `confluence_connection_get` | К какому сайту Confluence и каким аккаунтом Atlassian подключён пользователь |
|
|
154
|
+
| `confluence_search` | Поиск страниц по тексту, пространствам, меткам, автору и дате изменения |
|
|
155
|
+
| `confluence_get_page` | Страница целиком: заголовок, пространство, родитель, версия, метки и текст |
|
|
156
|
+
| `confluence_get_page_comments` | Комментарии страницы: подвал, inline или оба, с ответами и статусом резолва |
|
|
157
|
+
| `confluence_get_page_attachments` | Метаданные вложений: имя, тип, размер, версия, автор, ссылки |
|
|
158
|
+
| `confluence_get_page_versions` | История версий: номер, автор, дата и комментарий к версии |
|
|
159
|
+
| `confluence_get_space` | Пространство: ключ, имя, тип, статус, описание |
|
|
160
|
+
| `confluence_list_spaces` | Пространства, доступные аккаунту, с ключами для поиска и чтения |
|
|
161
|
+
|
|
162
|
+
Списочные инструменты Confluence отвечают конвертом `{ items, nextCursor }`: `nextCursor` — это значение, которое нужно вернуть в аргументе `cursor`, а не URL и не подписанный токен. У поиска это смещение строк (эндпоинт считает строки), у остальных чтений — курсор самого Confluence, из которого провайдер берёт только сам токен: путь и параметры следующего запроса он собирает сам, поэтому курсор не может увести запрос на чужой адрес. Комментарии с `kind: "all"` отвечают двумя курсорами (`cursors.footer` и `cursors.inline`), потому что продолжать их придётся по отдельности. `totalSize` у поиска говорит, сколько всего совпадений нашлось, — по нему модель понимает, стоит ли листать дальше.
|
|
163
|
+
|
|
164
|
+
Дату изменения можно задать абсолютным днём (`YYYY-MM-DD`) или окном от сегодняшнего дня (`-7d`, `-2w`, `-1m`, `-1y`): у агента в промпте часов нет, поэтому окно считает провайдер.
|
|
165
|
+
|
|
166
|
+
Поиск идёт через CQL, но CQL собирает провайдер: модель передаёт типизированные фильтры (текст, пространства, типы, метки, автор, дата), а `cql.ts` экранирует литералы и подставляет `space in (…)`, `currentUser()` и `ORDER BY`. Инструмента с произвольным CQL в surface нет. Текст страницы и комментариев приходит не сырым payload, а markdown-подобной разметкой в поле `untrustedContent`: `adf.ts` разбирает Atlassian Document Format в заголовки, списки, таблицы, блоки кода, ссылки, упоминания, панели и статусы, а макросы, медиа и встроенные представления заменяет плейсхолдерами (`[Confluence macro: jira]`, `[media: chart]`) — провайдер ничего не отрисовывает и никуда не ходит по ссылкам из страницы. Тело режется бюджетом (`maxChars` в аргументе, потолок — `maxBodyChars` стенда) и при обрезке отвечает `truncated: true` и `totalChars`. Подсветка совпадений в выдержках поиска снимается вместе с разметкой.
|
|
167
|
+
|
|
168
|
+
## Возможности и скопы Confluence
|
|
169
|
+
|
|
170
|
+
Подключение — Atlassian API token вместе с почтой аккаунта Atlassian (Basic-пара). Возможность появляется у пользователя, если её включил оператор (`confluence.*Read`).
|
|
171
|
+
|
|
172
|
+
| Возможность | Что открывает |
|
|
173
|
+
| --- | --- |
|
|
174
|
+
| `identity.read` | Сайт Confluence и подключённый аккаунт Atlassian |
|
|
175
|
+
| `spaces.read` | Список пространств и карточка пространства |
|
|
176
|
+
| `search.read` | Поиск страниц по тексту, пространствам, меткам, автору и дате |
|
|
177
|
+
| `content.read` | Страница целиком с текстом, метками и версией |
|
|
178
|
+
| `comments.read` | Комментарии страницы: подвал, inline и ответы |
|
|
179
|
+
| `attachments.read` | Метаданные вложений страницы |
|
|
180
|
+
| `versions.read` | История версий страницы |
|
|
181
|
+
|
|
182
|
+
Confluence, как и TeamCity, не сообщает через API, какие права выданы конкретному токену: у OAuth-приложений для этого есть `/oauth/token/accessible-resources`, а у API token аналога нет. Поэтому сужение идёт только по деплой-флагам оператора, а права аккаунта применяет сам Confluence — отказ приходит как `ProviderPermissionDenied`, и провайдер никогда не пробует другой credential.
|
|
183
|
+
|
|
184
|
+
Оператор дополнительно может сузить **пространства**: `confluence.allowedSpaces` — это список ключей, и он применяется одинаково к поиску, к списку пространств и к прямому чтению страницы, комментариев, вложений и версий. Страница в пространстве вне списка отвечает отказом `OperationDeniedByPolicy`, а не тихо исчезает из выдачи; в поиск добавляется `space in (…)`, и строки, пространство которых по ответу не подтверждается, отбрасываются. Страница не несёт ключ пространства, только `spaceId`, поэтому каждое чтение страницы делает дополнительный запрос самого пространства — он же и наполняет ответ ключом и именем, и по нему принимается решение политики; чтения комментариев, вложений и версий с включённой политикой стоят ещё одного чтения страницы, чтобы узнать её пространство.
|
|
185
|
+
|
|
186
|
+
Скопы, которые нужны токену: классические `read:confluence-content.all`, `read:confluence-space.summary`, `search:confluence`, `read:confluence-user` (или гранулярные `read:page:confluence`, `read:comment:confluence`, `read:attachment:confluence`, `read:space:confluence`, `read:content.metadata:confluence`, `read:user:confluence`). Классический токен работает по адресу сайта (`https://company.atlassian.net`); токен со скоупами Atlassian принимает только через шлюз `https://api.atlassian.com/ex/confluence/{cloudId}` — такой адрес оператор может задать как `instances[].baseUrl`, и провайдер будет ходить по тому же относительному пути `/wiki/...`. Сам cloudId провайдер не ищет.
|
|
187
|
+
|
|
188
|
+
Запись в surface отсутствует: создание и правка страниц, комментарии, резолв inline-комментариев, вложения, перемещение и администрирование пространств ждут confirmation-фреймворка. Произвольного REST (`confluence_rest_call`), произвольного CQL и скачивания вложений тоже нет — только метаданные и ссылки, которые отдал сам Confluence.
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
## Возможности и скопы
|
|
192
|
+
|
|
193
|
+
Одна возможность = один scope Bitrix24. Возможность появляется у пользователя только если её включил оператор (`bitrix24.*Read`) **и** подключённый вебхук реально получил соответствующий scope — плагин спрашивает это у портала методом `scope` при подключении и при нажатии «Проверить».
|
|
194
|
+
|
|
195
|
+
| Возможность | Scope вебхука | Что открывает |
|
|
196
|
+
| --- | --- | --- |
|
|
197
|
+
| `crm.read` | `crm` | CRM, дела, таймлайн, товарные строки, дубли |
|
|
198
|
+
| `chat.read` | `im` | Чаты, сообщения, поиск по переписке |
|
|
199
|
+
| `openlines.read` | `imopenlines` | Диалоги открытых линий и их история |
|
|
200
|
+
| `user.read` | `user_brief` / `user_basic` / `user` | Свой профиль и поиск сотрудников |
|
|
201
|
+
| `department.read` | `department` | Структура компании |
|
|
202
|
+
| `tasks.read` | `task` | Задачи |
|
|
203
|
+
| `calendar.read` | `calendar` | Календарь и занятость |
|
|
204
|
+
| `disk.read` | `disk` | Файлы Диска |
|
|
205
|
+
|
|
206
|
+
Выданные в Bitrix24 права не отменяются: портал всё равно применяет права того пользователя, чей вебхук используется. Возможность, обнаруженная после выдачи нового scope, появляется в карточке выключенной — пользователь включает её сам. Запись (`*.add`, `*.update`, `*.delete`), бизнес-процессы, управление пользователями и generic REST/MCP в surface отсутствуют.
|
|
207
|
+
|
|
208
|
+
## Возможности и скопы GitLab
|
|
209
|
+
|
|
210
|
+
Подключение — personal access token. Возможность появляется у пользователя только если её включил оператор (`gitlab.*Read`) **и** токен при подключении реально предъявил соответствующий scope: плагин спрашивает scopes у самого токена (`GET /api/v4/personal_access_tokens/self`) при сохранении и при нажатии «Проверить». Токен, который не может прочитать себя (старый GitLab, group/project access token), только снижает точность — срез остаётся на деплой-флагах оператора.
|
|
211
|
+
|
|
212
|
+
| Возможность | Scope токена | Что открывает |
|
|
213
|
+
| --- | --- | --- |
|
|
214
|
+
| `identity.read` | `read_user` / `read_api` / `api` | Свой профиль: логин, имя, инстанс |
|
|
215
|
+
| `projects.read` | `read_api` / `api` | Проекты, видимость, ветка по умолчанию |
|
|
216
|
+
| `repository.read` | `read_repository` / `read_api` / `api` | Дерево, файлы, коммиты, сравнение веток |
|
|
217
|
+
| `search.read` | `read_api` / `api` | Поиск по проектам, задачам, MR, коммитам, коду |
|
|
218
|
+
| `issues.read` | `read_api` / `api` | Задачи и комментарии к ним |
|
|
219
|
+
| `merge_requests.read` | `read_api` / `api` | MR, диффы, обсуждения, одобрения, пайплайны MR |
|
|
220
|
+
| `ci.read` | `read_api` / `api` | Пайплайны, джобы, логи джоб |
|
|
221
|
+
|
|
222
|
+
У GitLab нет отдельного read-scope на каждую область, поэтому `read_api` покрывает почти всё, а `read_repository` и `read_user` дают узкие наборы. Права токена не отменяются: GitLab всё равно применяет права своего пользователя. Возможность, появившаяся после выдачи нового scope, приходит в карточку выключенной. Запись (`POST`/`PUT`/`DELETE`), GraphQL, произвольный REST, admin-API, управление токенами, участниками и CI-переменными в surface отсутствуют; merge и запись в репозиторий — тоже.
|
|
223
|
+
|
|
224
|
+
Оператор стенда дополнительно решает, какие из инструментов видит модель: имена нужно добавить в tool allow-list пресета QA. Инструменты не принимают ни пользователя, ни credential, поэтому допуск к ним — решение оператора, а не модели.
|
|
225
|
+
|
|
226
|
+
## Возможности и скопы TeamCity
|
|
227
|
+
|
|
228
|
+
Подключение — персональный access token TeamCity. Адрес сервера задаёт оператор в конфигурации развёртывания (`teamcity.serverUrl`) — он один на всех, поэтому форма подключения спрашивает только токен, а карточка показывает адрес как справочную строку. Если адрес не задан, карточка говорит об этом вместо формы, которая всё равно не сохранится. Возможность появляется у пользователя, если её включил оператор (`teamcity.*Read`).
|
|
229
|
+
|
|
230
|
+
| Возможность | Что открывает |
|
|
231
|
+
| --- | --- |
|
|
232
|
+
| `identity.read` | Сервер TeamCity, его версия и подключённый пользователь |
|
|
233
|
+
| `projects.read` | Проекты |
|
|
234
|
+
| `buildConfigs.read` | Конфигурации сборки |
|
|
235
|
+
| `builds.read` | Сборки, карточка сборки, изменения в VCS |
|
|
236
|
+
| `failures.read` | Упавшие тесты и проблемы сборки |
|
|
237
|
+
| `logs.read` | Фрагмент лога сборки |
|
|
238
|
+
| `queue.read` | Очередь сборки |
|
|
239
|
+
| `investigations.read` | Расследования падений |
|
|
240
|
+
| `agents.read` | Агенты сборки |
|
|
241
|
+
| `artifacts.read` | Список артефактов и текст небольших текстовых файлов |
|
|
242
|
+
|
|
243
|
+
TeamCity, в отличие от GitLab и Bitrix24, не сообщает через API, какие именно права выданы конкретному токену: админ-скоупы невидимы снаружи, а «проверить» записью провайдер не имеет права. Поэтому сужение идёт только по деплой-флагам оператора, а права токена применяет сам TeamCity — отказ приходит как `ProviderPermissionDenied`, и провайдер никогда не пробует другой credential. Рекомендация пользователю в карточке прямая: создать токен с «Limit per project» и только теми правами чтения, которые нужны.
|
|
244
|
+
|
|
245
|
+
Запись в surface отсутствует: запуск, перезапуск, отмена сборки, комментарии и теги ждут confirmation-фреймворка; редактирование конфигураций, управление агентами, расследованиями и mute-ами — тоже. Параметры сборки (`/parameters`, `resulting-properties`) провайдер не запрашивает вообще, поэтому секретных значений в ответах нет по построению.
|
|
246
|
+
|
|
247
|
+
## Возможности и скопы Jira
|
|
248
|
+
|
|
249
|
+
Подключение — API-токен Atlassian и e-mail аккаунта, которому он принадлежит: Jira Cloud аутентифицирует такой токен через HTTP Basic (`email:token`). Сайты задаёт оператор в конфигурации развёртывания (`jira.sites`) — пользователь выбирает сайт из списка и вводит e-mail с токеном, произвольный хост ввести нельзя. Возможность появляется у пользователя, если её включил оператор (`jira.*Read`).
|
|
250
|
+
|
|
251
|
+
| Возможность | Что открывает |
|
|
252
|
+
| --- | --- |
|
|
253
|
+
| `identity.read` | Подключённый пользователь Atlassian и сайт, на котором он работает |
|
|
254
|
+
| `issues.read` | Поиск задач со всем словарём фильтров (включая историю изменений задачи и разрешение имени в accountId) и карточка задачи с описанием, связями и кастомными полями |
|
|
255
|
+
| `comments.read` | Комментарии задачи, включая ограниченные (с пометкой видимости) |
|
|
256
|
+
| `attachments.read` | Метаданные вложений задачи: имя, тип, размер, автор |
|
|
257
|
+
| `transitions.read` | Доступные переходы статуса и их обязательные поля |
|
|
258
|
+
| `projects.read` | Карточка проекта |
|
|
259
|
+
| `fields.read` | Схема полей сайта, включая кастомные, — она же источник id для фильтра по кастомному полю |
|
|
260
|
+
|
|
261
|
+
Jira, как и TeamCity, не сообщает через API, какие права выданы конкретному API-токену: токен действует от имени пользователя и наследует его права целиком, а «проверить» записью провайдер не имеет права. Поэтому сужение идёт только по деплой-флагам оператора, а права аккаунта применяет сама Jira — отказ приходит как `ProviderPermissionDenied` (задача, проект или поле закрыты схемой прав, issue security level или схемой ролей), и провайдер никогда не пробует другой credential. Единственная проверка, которую провайдер делает сам при подключении, — тип развёртывания: сайт, который отвечает `deploymentType`, отличным от `Cloud`, отклоняется, потому что Data Center — другой API, и молча считать его совместимым спецификация запрещает.
|
|
262
|
+
|
|
263
|
+
Запись в surface отсутствует: создание, правка, назначение, комментарии и переходы ждут pending actions и карточки подтверждения; удаление, администрирование проектов и workflow, произвольный REST и скачивание содержимого вложений — тоже. Провайдер читает только объявленный allow-list эндпоинтов `/rest/api/3` (гейт пакета падает на любом пути вне него), а легаси-эндпоинт `/rest/api/3/search`, удалённый Atlassian, не используется: поиск идёт через `/rest/api/3/search/jql`.
|
|
264
|
+
|
|
265
|
+
## Как подключается TeamCity
|
|
266
|
+
|
|
267
|
+
Адрес TeamCity задаёт оператор: сервер один на весь стенд, поэтому `teamcity.serverUrl` — обычная настройка развёртывания, а не поле формы. Пользователь вводит только токен, и токен тратится ровно по этому адресу. Рядом оператор задаёт **политику адресов**: какие адреса этот стенд готов набирать вообще (политика осталась от времён, когда адрес вводил пользователь, и закрывает переезд конфига на чужой хост).
|
|
268
|
+
|
|
269
|
+
```yaml
|
|
270
|
+
teamcity:
|
|
271
|
+
enabled: true
|
|
272
|
+
serverUrl: https://teamcity.example.internal
|
|
273
|
+
network:
|
|
274
|
+
mode: allowlist # allowlist | trusted-private
|
|
275
|
+
allowedHosts:
|
|
276
|
+
- teamcity.example.internal
|
|
277
|
+
- "*.corp.example"
|
|
278
|
+
allowedCidrs:
|
|
279
|
+
- 10.20.0.0/16 # только для адресов, записанных цифрами
|
|
280
|
+
allowedPorts:
|
|
281
|
+
- 443
|
|
282
|
+
- 8111
|
|
283
|
+
allowHttp: false
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Правила простые и проверяются дважды — при сохранении подключения и на каждом вызове инструмента, поэтому ужесточение политики закрывает и ранее сохранённые подключения:
|
|
287
|
+
|
|
288
|
+
- только `http`/`https`, HTTPS обязателен вне явного `allowHttp`; в URL не может быть credentials, query и fragment;
|
|
289
|
+
- имя хоста должно попасть в `allowedHosts` (точное имя или `*.суффикс`), а адрес, записанный цифрами, — в `allowedCidrs`;
|
|
290
|
+
- порт должен быть в `allowedPorts`: по умолчанию разрешён только порт схемы, поэтому TeamCity на своём стандартном `:8111` требует явного `allowedPorts: [8111]`;
|
|
291
|
+
- редиректы не отслеживаются (`redirect: "error"`), токен уходит только в заголовке `Authorization: Bearer`, в URL и теле его нет;
|
|
292
|
+
- `mode: trusted-private` — для доверенной корпоративной сети: имена хостов разрешены любые, а закрытые диапазоны (`10/8`, `172.16/12`, `192.168/16`, `127/8`) подставляются как `allowedCidrs` по умолчанию. Он предполагает, что стенд доверяет своему DNS; если это не так, нужен `allowlist`.
|
|
293
|
+
|
|
294
|
+
Пустая политика (`allowedHosts` и `allowedCidrs` пусты) — это не ошибка загрузки, а «ничего не подключить»: плагин пишет об этом предупреждение в лог при старте, а карточка отвечает пользователю отказом. Опечатки в самой политике — наоборот, падение на старте: молча выброшенный шаблон хоста оставил бы стенд без объяснения.
|
|
295
|
+
|
|
296
|
+
## Конфигурация TeamCity
|
|
297
|
+
|
|
298
|
+
```yaml
|
|
299
|
+
teamcity:
|
|
300
|
+
enabled: true
|
|
301
|
+
serverUrl: https://teamcity.example.internal # один адрес на весь стенд
|
|
302
|
+
network:
|
|
303
|
+
mode: allowlist
|
|
304
|
+
allowedHosts: [teamcity.example.internal]
|
|
305
|
+
allowedPorts: [443]
|
|
306
|
+
allowHttp: false
|
|
307
|
+
identityRead: true
|
|
308
|
+
projectsRead: true
|
|
309
|
+
buildConfigsRead: true
|
|
310
|
+
buildsRead: true
|
|
311
|
+
failuresRead: true
|
|
312
|
+
logsRead: true
|
|
313
|
+
queueRead: true
|
|
314
|
+
investigationsRead: true
|
|
315
|
+
agentsRead: true
|
|
316
|
+
artifactsRead: true
|
|
317
|
+
maxLogLines: 1000 # потолок строк в ответе по логу
|
|
318
|
+
maxLogBytes: 262144 # сколько лога вообще скачиваем
|
|
319
|
+
defaultArtifactBytes: 262144 # бюджет чтения артефакта по умолчанию
|
|
320
|
+
maxArtifactBytes: 1048576 # жёсткий потолок чтения артефакта
|
|
321
|
+
streamTimeoutMs: 30000 # таймаут для логов и артефактов
|
|
322
|
+
retries: 2 # повторы для 429/5xx и сетевых сбоев
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
Токен создаётся в TeamCity (Profile → Access Tokens), при желании с «Limit per project» и read-правами, вводится один раз в карточке и шифруется тем же конвертным хранилищем, что и остальные секреты.
|
|
326
|
+
|
|
327
|
+
## Чего в TeamCity-провайдере ещё нет
|
|
328
|
+
|
|
329
|
+
Спецификация `docs/SPEC-providers-teamcity.md` описывает целевую архитектуру; в этой версии реализована read-only фаза, как и у Bitrix24 с GitLab:
|
|
330
|
+
|
|
331
|
+
- **Запись** (§12.2): запуск, перезапуск, отмена сборки, комментарий и теги — вместе с ними отложены pending actions и карточка подтверждения (§24). Пока в каталоге нет ни одной операции, которая может изменить TeamCity.
|
|
332
|
+
- **Автоматический постраничный обход** (§18): сейчас один вызов — один ограниченный запрос, а `pagination.hasMore` сообщает модели, что страница обрезана. Пятистраничная агрегация потребовала бы ходить по `nextHref`, чего провайдер не делает.
|
|
333
|
+
- **Кэш** (§20) отсутствует полностью, поэтому и межпользовательской утечки через кэш быть не может.
|
|
334
|
+
- **Rate limiting** (§19): лимиты запросов в минуту и на сервер не считаются; вместо них — ограниченные размеры страниц и повторы с backoff для 429/5xx.
|
|
335
|
+
- **Свои CA и `tlsVerify: false`** (§8): самоподписанный сертификат TeamCity заканчивается понятным `TlsFailure`, а не тихой проверкой без доверия. Доверие к сертификату задаётся на уровне стенда.
|
|
336
|
+
- **Webhooks** (§21), запись расследований и mute-ов, одобрение сборок, admin-операции и плановые задания (§25–26) — не подключены.
|
|
337
|
+
- **Секретные параметры сборки** (§15) в surface не попадают, потому что провайдер их не читает; отдельной «показать скрытое» нет и не планируется.
|
|
338
|
+
|
|
339
|
+
## Как подключается Confluence
|
|
340
|
+
|
|
341
|
+
Сайты Confluence задаёт только оператор: пользователь выбирает из списка, вводит почту своего аккаунта Atlassian и вставляет API token. Произвольный хост ввести нельзя, и адрес не сохраняется в credential: он перечитывается из конфига на каждом вызове, поэтому удаление или переезд сайта немедленно закрывает доступ к сохранённому токену (`CredentialRevoked`), и подмены на другой сайт не происходит.
|
|
342
|
+
|
|
343
|
+
Почта не секрет, но она — вторая половина Basic-пары, поэтому лежит в том же зашифрованном credential, что и токен (`{ instanceId, email, token }`): пара «токен + аккаунт» не может быть собрана из разных записей. Redirect не отслеживается (`redirect: "error"`), секрет уходит только в заголовке `Authorization: Basic …`, в URL и теле его нет. Если сайтов нет вообще, карточка честно сообщает, что подключать нечего; если сайт один, выбор не показывается.
|
|
344
|
+
|
|
345
|
+
## Конфигурация Confluence
|
|
346
|
+
|
|
347
|
+
```yaml
|
|
348
|
+
confluence:
|
|
349
|
+
enabled: true
|
|
350
|
+
allowInsecureHttp: false # только для dev-стенда
|
|
351
|
+
instances:
|
|
352
|
+
- id: company
|
|
353
|
+
label: Company
|
|
354
|
+
baseUrl: https://company.atlassian.net
|
|
355
|
+
# токен со скоупами требует шлюза Atlassian:
|
|
356
|
+
# - id: company-scoped
|
|
357
|
+
# label: Company (scoped token)
|
|
358
|
+
# baseUrl: https://api.atlassian.com/ex/confluence/<cloudId>
|
|
359
|
+
identityRead: true
|
|
360
|
+
spacesRead: true
|
|
361
|
+
searchRead: true
|
|
362
|
+
contentRead: true
|
|
363
|
+
commentsRead: true
|
|
364
|
+
attachmentsRead: true
|
|
365
|
+
versionsRead: true
|
|
366
|
+
allowedSpaces: [] # ключи пространств; пусто = все, что видит аккаунт
|
|
367
|
+
defaultBodyChars: 20000 # бюджет тела страницы по умолчанию
|
|
368
|
+
maxBodyChars: 60000 # потолок бюджета, который может попросить модель
|
|
369
|
+
maxResults: 50 # строк в ответе любого списка (потолок для limit)
|
|
370
|
+
maxReplyParents: 10 # сколько комментариев могут принести ответы
|
|
371
|
+
retries: 2 # повторы для 429/5xx и сетевых сбоев
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
API token выпускается в профиле Atlassian (`Manage profile → Security → API tokens`), вводится один раз в карточке и шифруется тем же конвертным хранилищем, что и остальные секреты. Если стенду нужен OAuth-аккаунт Atlassian общего вида, а не персональный токен, — это отдельная фаза.
|
|
375
|
+
|
|
376
|
+
## Чего в Confluence-провайдере ещё нет
|
|
377
|
+
|
|
378
|
+
Спецификация `docs/SPEC-providers-confluence.md` описывает целевую архитектуру; в этой версии реализована read-only фаза, как и у остальных провайдеров:
|
|
379
|
+
|
|
380
|
+
- **OAuth 2.0 3LO** (раздел «Authentication»): подключение идёт API token плюс почта аккаунта, поэтому нет ни общего OAuth-приложения, ни refresh-цикла, ни общего слоя `providers/atlassian` с `accessible-resources`. Выбор ресурса сводится к выбору сайта из конфига оператора.
|
|
381
|
+
- **Запись** (раздел «Write operations»): создание и правка страниц, комментарии, резолв inline-комментариев — вместе с ними отложены pending actions, карточка подтверждения и оптимистичная блокировка по версии страницы. Пока в каталоге нет ни одной операции, которая может изменить Confluence.
|
|
382
|
+
- **Скачивание вложений** (раздел «Attachments»): сейчас возвращаются только метаданные и ссылки, которые отдал Confluence; ни байты, ни временное хранилище на пользователя не реализованы.
|
|
383
|
+
- **Произвольный CQL и произвольный REST** (разделы «CQL policy», «Tool surface»): поиск принимает только типизированные фильтры, инструментов `confluence_search_cql` и `confluence_rest_call` нет и не планируется в этой фазе.
|
|
384
|
+
- **Хлебные крошки** (раздел «MVP feature set»): эндпоинт предков страницы отдаёт только id и тип, а названия потребовали бы отдельного чтения каждой страницы, поэтому в ответе есть только `parentId`.
|
|
385
|
+
- **Чтение блогов** (раздел «Optional MVP+»): поиск умеет возвращать `blogpost`, но открыть его нечем — отдельного чтения блогов в surface нет.
|
|
386
|
+
- **Продолжение большого тела** (раздел «Response size controls»): тело режется бюджетом и помечается `truncated`, но сегментного чтения (`confluence_get_page_segment`) нет; страница, чей JSON на стороне Confluence больше `maxResponseBytes`, отвечает `ResultTooLarge`.
|
|
387
|
+
- **Кэш** (раздел «Caching») отсутствует полностью, поэтому и межпользовательской утечки через кэш быть не может; пагинация stateless, подписанных continuation-токенов нет.
|
|
388
|
+
- **Rate limiting** (раздел «Rate limiting»): лимиты по principal, ресурсу и глобальные не считаются; вместо них — ограниченные размеры ответов и повторы с backoff для 429/5xx.
|
|
389
|
+
- **Семантический индекс** (раздел «Optional semantic index»), **webhooks** и **Confluence Data Center** (раздел «Compatibility») — не подключены: провайдер работает только с Confluence Cloud.
|
|
390
|
+
|
|
391
|
+
## Как подключается GitLab
|
|
392
|
+
|
|
393
|
+
Инстансы GitLab задаёт только оператор: пользователь выбирает из списка и вставляет токен, произвольный хост ввести нельзя. Если инстанс один, выбор не показывается; если инстансов нет, карточка честно сообщает, что подключать нечего.
|
|
394
|
+
|
|
395
|
+
Правила адреса инстанса (то, что защищает брокер от SSRF): только `http`/`https`, HTTPS обязателен вне явного `allowInsecureHttp` для стенда; без credentials, query и fragment в URL; путь допустим (GitLab, смонтированный в подкаталог), хвостовой слэш срезается; id инстанса — стабильный ключ, который и хранит секрет. Адрес не сохраняется в credential: он перечитывается из конфига на каждом вызове, поэтому удаление или переезд инстанса немедленно закрывает доступ к сохранённому токену (`CredentialRevoked`), и подмены на другой инстанс не происходит. Redirect не отслеживается (`redirect: "error"`), токен уходит только в заголовке `PRIVATE-TOKEN`, в URL и теле его нет.
|
|
396
|
+
|
|
397
|
+
## Конфигурация GitLab
|
|
398
|
+
|
|
399
|
+
```yaml
|
|
400
|
+
gitlab:
|
|
401
|
+
enabled: true
|
|
402
|
+
allowInsecureHttp: false # только для dev-стенда
|
|
403
|
+
instances:
|
|
404
|
+
- id: gitlab-com
|
|
405
|
+
label: GitLab.com
|
|
406
|
+
baseUrl: https://gitlab.com
|
|
407
|
+
- id: corp
|
|
408
|
+
label: Corporate GitLab
|
|
409
|
+
baseUrl: https://gitlab.example.internal
|
|
410
|
+
identityRead: true
|
|
411
|
+
projectsRead: true
|
|
412
|
+
repositoryRead: true
|
|
413
|
+
searchRead: true
|
|
414
|
+
issuesRead: true
|
|
415
|
+
mergeRequestsRead: true
|
|
416
|
+
ciRead: true
|
|
417
|
+
maxFileBytes: 131072 # сколько тела файла отдаём модели
|
|
418
|
+
maxJobLogBytes: 262144 # сколько лога джобы отдаём модели
|
|
419
|
+
maxSearchResults: 50 # потолок per page у поиска
|
|
420
|
+
retries: 2 # повторы для 429/5xx и сетевых сбоев
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
OAuth-приложение для GitLab не нужно: подключение идёт персональным токеном. Токен создаётся в GitLab (`User settings → Access tokens`) с read-scope, вводится один раз в карточке, шифруется тем же конвертным хранилищем, что и вебхук Bitrix24, и после сохранения не показывается и не копируется.
|
|
424
|
+
|
|
425
|
+
## Чего в GitLab-провайдере ещё нет
|
|
426
|
+
|
|
427
|
+
Спецификация `docs/SPEC-providers-gitlab.md` описывает целевую архитектуру; в этой версии сознательно реализована только read-only фаза, как и у Bitrix24:
|
|
428
|
+
|
|
429
|
+
- **OAuth Authorization Code + PKCE** (§8.1) — вместо него PAT (§8.2). Для OAuth нужны callback-маршрут на хосте, одноразовый state и refresh-цикл; это отдельная фаза.
|
|
430
|
+
- **Пользовательская граница ресурсов** (§12): сейчас доступ ограничен правами токена и персональной политикой возможностей, но не выбранным набором проектов/групп.
|
|
431
|
+
- **Pending actions и подтверждения** (§15) — вместе с ними отложены все записи: комментарии, создание задач и MR, запуск и отмена пайплайнов.
|
|
432
|
+
- **Кэш** (§21) отсутствует полностью, поэтому и межпользовательской утечки через кэш быть не может; пагинация stateless, подписанных continuation-токенов нет.
|
|
433
|
+
- **Webhooks** (§23) и **официальный GitLab MCP** (§24) — не подключены; REST API v4 остаётся единственным бэкендом.
|
|
434
|
+
|
|
435
|
+
## Как подключается Jira
|
|
436
|
+
|
|
437
|
+
Сайты Jira задаёт только оператор: пользователь выбирает сайт из списка и вводит API-токен с e-mail, произвольный хост ввести нельзя. Если сайт один, выбор не показывается; если сайтов нет, карточка честно сообщает, что подключать нечего.
|
|
438
|
+
|
|
439
|
+
Правила адреса сайта (то, что защищает брокер от SSRF): только `http`/`https`, HTTPS обязателен вне явного `allowInsecureHttp` для стенда; без credentials, query и fragment в URL; путь допустим (Jira за обратным прокси в подкаталоге), хвостовой слэш срезается; id сайта — стабильный ключ, который и хранит секрет. Адрес не сохраняется в credential: он перечитывается из конфига на каждом вызове, поэтому удаление или переезд сайта немедленно закрывает доступ к сохранённому токену (`CredentialRevoked`), и подмены на другой сайт не происходит. Redirect не отслеживается (`redirect: "error"`), а токен уходит только в заголовке `Authorization: Basic …`, собранном из `email:token` — в URL и теле его нет.
|
|
440
|
+
|
|
441
|
+
## Конфигурация Jira
|
|
442
|
+
|
|
443
|
+
```yaml
|
|
444
|
+
jira:
|
|
445
|
+
enabled: true
|
|
446
|
+
allowInsecureHttp: false # только для dev-стенда
|
|
447
|
+
sites:
|
|
448
|
+
- id: company
|
|
449
|
+
label: company.atlassian.net
|
|
450
|
+
baseUrl: https://company.atlassian.net
|
|
451
|
+
- id: sandbox
|
|
452
|
+
label: Sandbox
|
|
453
|
+
baseUrl: https://sandbox.atlassian.net
|
|
454
|
+
fieldAliases: # имена кастомных полей ЭТОГО сайта: алиас → customfield_ id
|
|
455
|
+
product: customfield_10010 # id берётся из jira_get_fields; в репозитории их нет
|
|
456
|
+
identityRead: true
|
|
457
|
+
issuesRead: true
|
|
458
|
+
commentsRead: true
|
|
459
|
+
attachmentsRead: true
|
|
460
|
+
transitionsRead: true
|
|
461
|
+
projectsRead: true
|
|
462
|
+
fieldsRead: true
|
|
463
|
+
defaultSearchLimit: 20 # строк в ответе поиска, если модель не просила
|
|
464
|
+
maxSearchLimit: 100 # потолок страницы; больше Jira не отдаёт
|
|
465
|
+
maxCommentLimit: 100 # потолок страницы комментариев
|
|
466
|
+
maxTextChars: 20000 # бюджет одного описания, комментария или rich-поля
|
|
467
|
+
retries: 2 # повторы для 429/5xx и сетевых сбоев
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
OAuth-приложение для Jira не нужно: подключение идёт API-токеном. Токен создаётся в аккаунте Atlassian (`id.atlassian.com → Безопасность → API-токены`), вводится один раз в карточке и шифруется тем же конвертным хранилищем, что и остальные секреты — вместе с e-mail аккаунта, потому что Jira аутентифицирует пару `email:token`, а не токен отдельно. После сохранения ни то, ни другое не показывается и не копируется.
|
|
471
|
+
|
|
472
|
+
`fieldAliases` — тоже настройка развёртывания, а не знание провайдера: какие кастомные поля инстанса отвечают на «продукт», «команду» или «окружение» — это свойство конкретного сайта, поэтому в пакете нет ни одного такого id, а оператор объявляет свои имена алиасами и видит их в ответе `jira_get_fields`. Опечатка в алиасе роняет загрузку конфига, как и опечатка в списке сайтов: алиас, который молча никуда не указывает, отвечал бы «задач нет» вместо «нет такого поля». Значения алиасных полей также известны только инстансу — их читают из реальных задач (`jira_get_issue` с `include: ["custom_fields"]`), а не угадывают.
|
|
473
|
+
|
|
474
|
+
## Чего в Jira-провайдере ещё нет
|
|
475
|
+
|
|
476
|
+
Спецификация `docs/SPEC-providers-jira.md` описывает целевую архитектуру; в этой версии реализована read-only фаза, как и у Bitrix24, GitLab и TeamCity:
|
|
477
|
+
|
|
478
|
+
- **OAuth 2.0 3LO с ротацией refresh-токенов** (§Authentication): вместо него API-токен с Basic-аутентификацией. Для OAuth нужны callback-маршрут на хосте, одноразовый state с PKCE, per-credential lock на ротацию refresh-токена и `reauth_required` при `invalid_grant` — это отдельная фаза. Токен, отклонённый Jira (401), сейчас отвечает `CredentialRevoked`, а карточка предлагает заменить токен.
|
|
479
|
+
- **Общий слой Atlassian** (§Shared Atlassian account model): `providers/atlassian/` — общий аккаунт и ресурсы для Jira и Confluence, несколько сайтов на один аккаунт. Пока Jira самостоятельный каталог, как и остальные три провайдера, а сайт выбирается при подключении.
|
|
480
|
+
- **Привязка workspace → проект** (§Workspace binding): allowlist проектов на уровне рабочего пространства — дополнительное сужение, которого сейчас нет; доступ ограничен правами аккаунта и персональной политикой возможностей.
|
|
481
|
+
- **Raw JQL** (§JQL policy, advanced mode): модели доступны только типизированные фильтры. Отдельный JQL-инструмент потребовал бы валидации через parse-API Jira, лимитов на ширину запроса и аудита исходной и нормализованной строки.
|
|
482
|
+
- **Запись** (§Write operations): `jira_prepare_*` вместе с pending actions, payload hash, сроком годности и перепроверкой прав на подтверждении. Пока в каталоге нет ни одной операции, которая может изменить Jira, и ни одного инструмента со словом `prepare`.
|
|
483
|
+
- **Скачивание вложений** (§Attachments): сейчас только метаданные. Будущий `jira_get_attachment` обязан заново проверять видимость задачи, иметь лимит байт и allowlist типов.
|
|
484
|
+
- **Поиск по истории изменений**: историю одной задачи прочитать можно (`include: ["changelog_summary"]`), а вот отфильтровать задачи «где в истории встречается 3.8» — нет. Типизированный фильтр по истории потребовал бы JQL-операторов `WAS`/`CHANGED` с их отдельной валидацией; пока такой запрос сводится к чтению истории конкретных задач. Чтение кастомных полей идёт селектором `*all`, поэтому на сайте с очень большим числом полей такой ответ может упереться в `ResultTooLarge`.
|
|
485
|
+
- **Кэш** (§Caching) отсутствует полностью, поэтому и межпользовательской утечки через кэш быть не может: схема полей перечитывается на каждый такой вызов, а курсор поиска — это continuation-токен Jira, а не наше состояние.
|
|
486
|
+
- **Rate limiting** (§Rate limiting): лимитов на пользователя и на сайт нет; вместо них — ограниченные страницы, таймаут стенда (`timeoutMs`) и повторы с `Retry-After` для 429/5xx. Инвалидация по webhooks (§Future work) — тоже не подключена.
|
|
487
|
+
|
|
488
|
+
## Граница доверия
|
|
489
|
+
|
|
490
|
+
Интеграционный principal получается только из QA Surface:
|
|
491
|
+
|
|
492
|
+
1. браузер аутентифицируется штатным account token QA Surface;
|
|
493
|
+
2. `secureSession` проверяет владельца DSH-сессии;
|
|
494
|
+
3. интеграционный principal закрепляется только если текущий пользователь и владелец совпадают;
|
|
495
|
+
4. администраторский просмотр чужого чата, неаттестованная сессия и subagent не получают principal;
|
|
496
|
+
5. broker находит подключение по паре `ownerUserId + provider` и только внутри себя расшифровывает credential;
|
|
497
|
+
6. адрес внешнего сервиса приходит только из конфига оператора: у GitLab, Jira и Confluence это выбранный сайт из списка инстансов, у Bitrix24 — проверенный по доменному allowlist URL вебхука, у TeamCity — адрес, проверенный по политике стенда (и при сохранении, и на каждом вызове);
|
|
498
|
+
7. у Jira модели не достаётся и язык запросов: JQL собирается из типизированных аргументов внутри провайдера, а значения экранируются как строковые литералы;
|
|
499
|
+
8. справочник пользователей Jira читается только для того, чтобы превратить имя из фильтра в accountId: ответ справочника не попадает ни в результат тула, ни в лог, а неоднозначное имя — отказ, а не выбор человека за пользователя.
|
|
500
|
+
|
|
501
|
+
В логах и audit сохраняются только provider, operation, result и source session id. Тела CRM/чатов, HTTP-заголовки и секреты не журналируются. Постоянный cache данных провайдера отсутствует.
|
|
502
|
+
|
|
503
|
+
## Подготовка master key
|
|
504
|
+
|
|
505
|
+
Создайте отдельный 256-битный ключ вне БД и репозитория. Docker secret по умолчанию должен быть доступен Host как:
|
|
506
|
+
|
|
507
|
+
```text
|
|
508
|
+
/run/secrets/qa_integrations_master_key
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
Файл может содержать ровно 32 случайных байта, 64 hex-символа или base64 от 32 байт. Пример для Linux:
|
|
512
|
+
|
|
513
|
+
```bash
|
|
514
|
+
umask 077
|
|
515
|
+
openssl rand -base64 32 > qa_integrations_master_key
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
Пример для PowerShell:
|
|
519
|
+
|
|
520
|
+
```powershell
|
|
521
|
+
$keyBytes = [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
|
|
522
|
+
[Convert]::ToBase64String($keyBytes) | Set-Content -NoNewline qa_integrations_master_key
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
Не меняйте файл ключа поверх существующего deployment: старые записи перестанут расшифровываться. `KeyProvider` и `SecretStore.rewrap()` поддерживают контролируемую ротацию с одновременной доступностью старой и новой версии; операционный CLI ротации оставлен для hardening-фазы.
|
|
526
|
+
|
|
527
|
+
## Конфигурация
|
|
528
|
+
|
|
529
|
+
Плагин безопасно выключен в bundle patch, пока не смонтирован master key:
|
|
530
|
+
|
|
531
|
+
```yaml
|
|
532
|
+
- update:
|
|
533
|
+
id: qa-integrations
|
|
534
|
+
config:
|
|
535
|
+
enabled: true
|
|
536
|
+
dataPath: /var/lib/dsh/qa-integrations.db
|
|
537
|
+
auditRetentionDays: 90
|
|
538
|
+
masterKeyPath: /run/secrets/qa_integrations_master_key
|
|
539
|
+
masterKeyVersion: 1
|
|
540
|
+
timeoutMs: 15000
|
|
541
|
+
maxResponseBytes: 2000000
|
|
542
|
+
allowedPortalSuffixes:
|
|
543
|
+
- .bitrix24.ru
|
|
544
|
+
- .bitrix24.com
|
|
545
|
+
- .bitrix24.eu
|
|
546
|
+
bitrix24:
|
|
547
|
+
enabled: true
|
|
548
|
+
crmRead: true
|
|
549
|
+
chatRead: true
|
|
550
|
+
openlinesRead: true
|
|
551
|
+
userRead: true
|
|
552
|
+
departmentRead: true
|
|
553
|
+
tasksRead: true
|
|
554
|
+
calendarRead: true
|
|
555
|
+
diskRead: true
|
|
556
|
+
gitlab:
|
|
557
|
+
enabled: true
|
|
558
|
+
instances:
|
|
559
|
+
- id: gitlab-com
|
|
560
|
+
label: GitLab.com
|
|
561
|
+
baseUrl: https://gitlab.com
|
|
562
|
+
confluence:
|
|
563
|
+
enabled: true
|
|
564
|
+
instances:
|
|
565
|
+
- id: company
|
|
566
|
+
label: Company
|
|
567
|
+
baseUrl: https://company.atlassian.net
|
|
568
|
+
allowedSpaces:
|
|
569
|
+
- ENG
|
|
570
|
+
- PLATFORM
|
|
571
|
+
teamcity:
|
|
572
|
+
enabled: true
|
|
573
|
+
serverUrl: https://teamcity.example.internal
|
|
574
|
+
network:
|
|
575
|
+
mode: allowlist
|
|
576
|
+
allowedHosts:
|
|
577
|
+
- teamcity.example.internal
|
|
578
|
+
allowedPorts:
|
|
579
|
+
- 443
|
|
580
|
+
jira:
|
|
581
|
+
enabled: true
|
|
582
|
+
sites:
|
|
583
|
+
- id: company
|
|
584
|
+
label: company.atlassian.net
|
|
585
|
+
baseUrl: https://company.atlassian.net
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
`dataPath` по умолчанию — `$DSH_HOME/qa-integrations.db` (база SQLite). Прежний файл `qa-integrations.json`, оставшийся от релиза до 0.5.0, переносится при первом запуске и переименовывается в `qa-integrations.json.migrated-<ISO>`. На Unix новый файл создаётся с mode `0600`. Журнал обращений к сервисам хранится `auditRetentionDays` дней (по умолчанию 90; `0` — не ограничивать по возрасту) и в любом случае не длиннее 5000 записей. Разрешён только HTTPS URL вида `https://company.bitrix24.ru/rest/<user>/<secret>` без query, fragment, custom port или credentials в authority. Список доменных суффиксов задаётся оператором, а не пользователем.
|
|
589
|
+
|
|
590
|
+
## Пользовательский сценарий
|
|
591
|
+
|
|
592
|
+
1. В Bitrix24 создайте входящий вебхук и отметьте только нужные read scopes: `crm`, `im`, `imopenlines`, `user_brief` (или `user_basic`), `department`, `task`, `calendar`, `disk`. Урезанный набор вебхука — это и есть верхняя граница того, что увидит агент.
|
|
593
|
+
2. Откройте QA → Настройки → Интеграции.
|
|
594
|
+
3. Вставьте полный URL вебхука и нажмите «Сохранить и проверить». Плагин проверит профиль и прочитает выданные scopes.
|
|
595
|
+
4. После сохранения поле исчезнет: существующий токен нельзя показать или скопировать.
|
|
596
|
+
5. Отметьте, что именно разрешено агенту. Возможности, которых нет у вебхука, показаны как «Нет разрешения Bitrix24» и выключены.
|
|
597
|
+
6. Выдали в Bitrix24 новый scope — нажмите «Проверить», новая возможность появится в списке.
|
|
598
|
+
|
|
599
|
+
Для GitLab: создайте personal access token с read-scope, выберите инстанс (если их несколько), вставьте токен и нажмите «Сохранить и проверить». Плагин проверит профиль, прочитает scopes токена и покажет, что именно доступно агенту.
|
|
600
|
+
|
|
601
|
+
Для TeamCity: оператор задаёт адрес сервера (`teamcity.serverUrl`) и политику адресов, пользователь создаёт в профиле access token (по возможности с «Limit per project» и read-правами) и вставляет только его. Если адрес не задан, карточка говорит об этом и формы не показывает; если адрес не проходит политику — конфигурация стенда падает при загрузке, а не отвечает отказом пользователю. Плагин прочитает `/app/rest/server` и `/app/rest/users/current`, покажет версию сервера и подключённого пользователя, а список возможностей останется в границах, которые разрешил оператор: сам TeamCity не сообщает, какие права выданы токену.
|
|
602
|
+
|
|
603
|
+
Для Jira: оператор перечисляет сайты (`jira.sites`), пользователь создаёт API-токен в аккаунте Atlassian, выбирает сайт (если их несколько) и вводит e-mail аккаунта вместе с токеном. Плагин вызывает `/rest/api/3/myself`, показывает подключённого пользователя и сайт, а также проверяет, что сайт действительно Cloud: Data Center отвечает отказом на подключении, а не молчаливой несовместимостью. Кастомные поля задач приходят с именами из схемы сайта, а если прав на схему нет — с идентификаторами `customfield_*`.
|
|
604
|
+
|
|
605
|
+
Для Confluence: оператор задаёт сайты (`confluence.instances`) и, если нужно, список разрешённых пространств, пользователь выпускает API token в своём профиле Atlassian и вводит его вместе с почтой аккаунта. Если сайт один, выбор не показывается; если сайтов нет, карточка говорит об этом и формы не показывает. Плагин прочитает `/wiki/rest/api/user/current`, покажет подключённый аккаунт, а список возможностей останется в границах, которые разрешил оператор: сам Confluence не сообщает, какие права выданы API token.
|
|
606
|
+
|
|
607
|
+
Отключение атомарно удаляет локальный encrypted secret; дальнейшие tool calls получают `IntegrationNotConnected`. Запись и generic REST/MCP вызовы отсутствуют. OAuth и confirmation-based writes намеренно остаются следующими фазами спецификации для всех провайдеров.
|
|
608
|
+
|
|
609
|
+
## Проверка пакета
|
|
610
|
+
|
|
611
|
+
```bash
|
|
612
|
+
pnpm --filter @yadsh/dsh-qa-integrations check
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
Unit/integration набор проверяет AEAD, неверный ключ, rewrap, SSRF-ограничение webhook URL, адресов инстансов, политики адресов TeamCity и списка сайтов Jira, redaction (включая форму gitlab-токена и секреты, напечатанные в логе), escape locator-значений, нарезку и чистку логов, отказ по бинарным и архивным артефактам, отсутствие model-visible identity/secret selectors, отказ unowned/subagent-сессии, соответствие каждого tool операции каталога, read-only характер всех четырёх каталогов, сужение возможностей по scopes вебхука и токена, отображение ошибок GitLab, TeamCity и Jira в доменные коды, обрезку больших ответов и параллельную изоляцию Alice/Bob. Для Jira отдельно проверяются экранирование JQL (значение с кавычкой и `OR` остаётся значением), отказ поиска без фильтров, отказ имени там, где нужен accountId, allow-list читающих путей, рендер ADF в текст с сохранением структуры, отказ custom fields при выключенной схеме полей, потоковая отмена на не-Cloud сайт и то, что токен не попадает ни в URL, ни в результат тула. Отдельный гейт следит за границей провайдеров: `verify:package` падает, если в общем слое появится имя конкретной интеграции, а тест `provider boundary` — если брокер начнёт зависеть от Bitrix24.
|
|
616
|
+
|
|
617
|
+
Unit/integration набор проверяет AEAD, неверный ключ, rewrap, SSRF-ограничение webhook URL, адресов инстансов и политики адресов TeamCity, redaction (включая форму gitlab-токена и секреты, напечатанные в логе), escape locator-значений, нарезку и чистку логов, отказ по бинарным и архивным артефактам, отсутствие model-visible identity/secret selectors, отказ unowned/subagent-сессии, соответствие каждого tool операции каталога, read-only характер всех четырёх каталогов, сужение возможностей по scopes вебхука и токена, отображение ошибок GitLab, TeamCity и Confluence в доменные коды, обрезку больших ответов и параллельную изоляцию Alice/Bob. Для Confluence отдельно проверяются сборка CQL с экранированием литералов, разбор Atlassian Document Format с плейсхолдерами для макросов и медиа, отказ в пространстве вне allowlist и на поиске, и на прямом чтении, вложение `untrustedContent` в ответы со страницами и комментариями, а также отказ токену, чей сайт убрали из конфига. Отдельный гейт следит за границей провайдеров: `verify:package` падает, если в общем слое появится имя конкретной интеграции, а тест `provider boundary` — если брокер начнёт зависеть от Bitrix24. Собранный клиентский бандл проверяется отдельным тестом: он поднимается в песочнице как в браузере — через `window.__ModuleLoader__` с таблицей модулей, в которой есть только React, — регистрируется под полным именем пакета и монтирует карточку Confluence из секции, которую сам зарегистрировал.
|