# Коннектор

> Агент в вашей сети: git-мост и хост интеграций. Токены, ключи и доступ в сеть остаются у вас.

Коннектор — небольшой агент, который вы запускаете **на своей машине, в своей сети**.
Он делает две вещи:

- **git-мост** — переносит репозитории, недоступные из интернета, к нам и возвращает
  обратно pull request'ы;
- **хост интеграций** — запускает [плагины](/docs/connector/marketplace) из нашего
  каталога: [трекеры задач](/docs/connector/trackers) и
  [базы знаний](/docs/connector/knowledge), а в будущем и другие ваши системы.

_Иллюстрация: Раздел «Коннекторы» в приложении: агенты, их статус, обслуживаемые репозитории и установленные интеграции._

## Что он собой представляет

Ядро коннектора — **только git-мост**. Оно намеренно маленькое: его можно прочитать
целиком перед тем, как впустить в свою сеть, и оно не растёт от каждой новой
интеграции. Всё остальное — плагины: подписанные комплекты, которые коннектор
скачивает из каталога, проверяет по подписи и запускает **отдельными процессами под
отдельными пользователями ОС**.

```
      ваша сеть                                 │        наша сторона
                                                │
 ваш git ◀──локально──┐                         │
                      │                         │
 ваш трекер ◀─локально┤   КОННЕКТОР             │
                      ├── ядро: git-мост   ─────┼──исходящее──▶ платформа Buff
 (Jira, GitLab, …)    └── плагин ──┐            │
                          плагин ──┴─ свои uid, │
                                     свои адреса│
```

Три свойства этой картинки держат всё остальное:

1. **Только исходящие соединения.** Коннектор звонит наружу сам; к вам в сеть ничего
   не подключается. Открывать порт наружу не требуется — даже для событий трекера
   ([опрос работает всегда](/docs/connector/trackers#события-опрос-и-вебхуки)).
2. **Секреты не пересекают периметр.** Токен git, токен трекера и ключ самого агента
   лежат на вашей машине. Плагин их тоже **не видит**: исходящий запрос собирает
   коннектор и подставляет туда учётные данные сам —
   [как именно](/docs/connector/isolation#учётные-данные-плагин-их-не-видит).
3. **Границы объявлены заранее.** Куда плагину разрешено ходить и какие инструменты он
   отдаёт модели, видно **до установки**, в каталоге, и потом — в приложении.

## Что уходит наружу, а что нет

| | |
|---|---|
| **Не уходит никогда** | токены доступа (git, трекер), ключ агента, содержимое ваших секретов, любые адреса и системы, которых нет в списке разрешённых |
| **Уходит по вашей команде** | содержимое репозиториев, которые вы отметили: импорт переносит их в ваше изолированное пространство у нас — без этого разрабатывать нечего |
| **Уходит, когда к боту обратились** | текст обращения, заголовок и ссылка на тикет, имя автора обращения, ключ тикета и — для вопроса из pull request — имя ветки |
| **Уходит постоянно** | состояние агента: версия, онлайн/офлайн, список обслуживаемых репозиториев, список подключений с их инструментами и разрешёнными адресами |

Ничего из этого не собирается «на всякий случай»: события трекера читаются только в
отмеченных проектах и только при прямом обращении к боту, а отчёт о состоянии — это
ровно то, что видно в приложении в разделе «Коннекторы».

## С чего начать

1. [Скачайте и установите агент](/docs/connector/install) на машину, у которой есть
   доступ к вашему git и исходящий доступ в интернет.
2. В приложении Buff откройте **«Коннекторы» → «Добавить коннектор»** и получите
   одноразовый код привязки.

_Иллюстрация: Код привязки действует 15 минут и используется один раз._

3. Настройте агент — через [локальную страницу](/docs/connector/web-setup) или
   [терминал](/docs/connector/cli-setup): провайдер git, токен, репозитории и код
   привязки.
4. Нужен трекер — поставьте интеграцию [из каталога](/docs/connector/marketplace) и
   создайте подключение. Как это работает со стороны команды — в разделе
   [«Интеграции с трекерами»](/docs/connector/trackers).

Добавить репозиторий, сменить токен или поправить подключение можно потом **без
перезапуска** — изменения применяются на лету.

## Разделы

| Страница | О чём |
|---|---|
| [Установка](/docs/connector/install) | бинарь и образ, проверка подписи, привилегии, среда выполнения плагинов |
| [Локальная страница](/docs/connector/web-setup) | пять разделов страницы настройки: обзор, подключение, репозитории, каталог, интеграции |
| [Терминал](/docs/connector/cli-setup) | то же самое командами — полный справочник, без графики |
| [Каталог и установка плагина](/docs/connector/marketplace) | что видно до установки, подпись, версии, обновление, отзыв |
| [Изоляция и границы доступа](/docs/connector/isolation) | процесс на подключение, отдельный uid, разрешённые адреса, учётные данные |
| [Инструменты и модель](/docs/connector/tools) | как инструменты плагина попадают модели и почему пишущие недоступны при чтении |
| [Интеграции с трекерами](/docs/connector/trackers) | обращения, команды, область видимости, ветка pull request, события |
| [Источники знаний](/docs/connector/knowledge) | Confluence и Figma как контекст для ответов: инструменты чтения, вопросы на странице и на макете, параметры вместо картинок |
| [Jira](/docs/connector/jira) | Data Center, Server и Cloud: версии, доступы, особенности |
| [Конфиг вручную (YAML)](/docs/connector/yaml) | полный справочник файла настроек для Ansible и CI |
| [Управление и удаление](/docs/connector/manage) | проверка связи, журнал, обновление, выключение, отзыв |