# Каталог и установка интеграции

> Что видно до установки, как проверяется подпись, как выбираются версии и что значит отзыв.

Интеграция — это **подписанный комплект кода**, который коннектор скачивает из
каталога и запускает у себя. Ядро агента при этом не меняется: новая интеграция не
требует ни обновления агента, ни доверия к тому, чего вы не видели.

## Что видно до установки

Каталог показывает по каждой версии ровно то, что решает вопрос «пускать ли это в
свою сеть»:

| | |
|---|---|
| **Куда сможет ходить** | не список адресов, а **правило**: «по адресу из поля `base_url` этого подключения», плюс разрешённые методы и префиксы путей. Конкретный адрес появляется только когда вы заполните форму |
| **Какие учётные данные попросит** | их имена и вид (токен, пара «учётная запись + секрет», собственный заголовок трекера) |
| **Принимает ли вебхуки** | и в каком виде: разбирает содержимое вызова или только просыпается по нему |
| **Инструменты** | полный список с пометкой, какие только читают |
| **Издатель, версия, host API, размер** | и цифровой отпечаток комплекта |

_Иллюстрация: Каталог коннектора: границы доступа и инструменты — до того, как код окажется на машине._

Те же факты — на публичной витрине: [каталог интеграций](/marketplace) собирается из
того же подписанного каталога, что читает ваш агент, так что страница не может обещать
больше, чем сделает коннектор.

В терминале то же самое:

```bash
connector catalog show jira --config /etc/connector/connector.yaml
```

## Подпись и откуда берётся код

Каталог и каждый комплект подписаны нашим ключом; **открытый ключ вшит в бинарь
агента**. Проверка идёт до распаковки: комплект с чужой или испорченной подписью не
попадает на диск.

Сам каталог лежит **в реестре контейнеров** (`registry.buff.systems`), а не на
отдельном хосте. Это сделано ради закрытых периметров: реестр — то, что у вас уже
умеют зеркалировать в свой Harbor или Nexus, сканировать и разрешать по списку. Тогда
единственная правка — адрес зеркала; подписи проверяются те же, потому что реестр
здесь только транспорт.

## Установка

На [локальной странице](/docs/connector/web-setup#каталог) — кнопка **«Установить»**;
в терминале:

```bash
connector install jira --config /etc/connector/connector.yaml        # последняя совместимая
connector install jira@1.4.1 --config /etc/connector/connector.yaml  # конкретная версия
```

Установка **не создаёт подключение** и ничего не запускает: на машину лёг код, дальше
вы решаете, к какой системе его подключить. Один установленный код обслуживает сколько
угодно подключений.

## Версии

- **Подключение закреплено за версией.** Появление новой ничего не меняет само собой:
  «работало вчера — работает сегодня» важнее свежести.
- **`install` без версии** ставит последнюю, **совместимую с этой сборкой агента**.
  Интеграция, которой нужен более новый коннектор, не поставится — и скажет почему.
- **Обновление — отдельное решение.** Когда для подключения есть более свежая
  установленная версия, у него появляется кнопка **«Обновить до …»**. Перед
  переключением коннектор проверяет, что **настройки этого подключения подходят новой
  версии**: если версия требует поле, которого у вас нет, обновление не состоится и
  скажет, чего не хватает, — вместо подключения, упавшего после обновления.
- **Версия — это байты.** Одна и та же версия всегда означает один и тот же комплект:
  это то, что защищает подпись каталога. Изменилось содержимое — вышла новая версия.

## Отзыв версии

Если в версии нашлась проблема, мы помечаем её отозванной в списке отзывов — он
подписан и читается вместе с каталогом.

- Поставить отозванную версию нельзя.
- Уже работающее подключение не выключается молча: коннектор отмечает его как
  работающее на отозванной версии, и это видно и на локальной странице, и в приложении
  — чтобы решение о переходе принимали вы, а не выключатель у нас.

Отзыв версии — не то же самое, что [отзыв самого коннектора](/docs/connector/manage#отзыв-доступа):
второй прекращает связь агента с платформой.

## Что интеграция может, а чего не может

Полностью это описано в [«Изоляции и границах доступа»](/docs/connector/isolation),
коротко:

- работает **своим процессом под своим пользователем ОС**;
- **не видит** ключа коннектора, ваших токенов и файлов других подключений;
- **не открывает сеть сама** — исходящий запрос делает коннектор, по объявленному
  правилу и с подставленными учётными данными;
- отдаёт модели **только те инструменты, которые объявила**, и пишущие из них
  недоступны на стадиях, где модель только читает.