# Локальная страница настройки

> Пять разделов страницы агента: обзор, подключение, репозитории, каталог, интеграции.

Агент поднимает страницу настройки **только на локальном адресе** (`127.0.0.1`). Она
не видна из сети, и ничего с неё не уходит: провайдеры, токены и интеграции
настраиваются на той же машине, где всё это и остаётся.

```bash
connector setup --config /etc/connector/connector.yaml
```

Команда печатает адрес с токеном в ссылке — откройте его в браузере. Токен нужен
потому, что эта страница устанавливает код и пишет секреты: одного `127.0.0.1` для
такого мало. По умолчанию он генерируется при каждом запуске; в автоматизации его
можно закрепить переменной `BUFF_ADMIN_TOKEN`. Настраиваете удалённый сервер — пробросьте порт:

```bash
ssh -L 8765:127.0.0.1:8765 user@ваш-сервер
```

_Иллюстрация: Проверка доступа и выбор репозиториев галочками — токен вводится один раз и остаётся на этой машине._

Чтобы страница работала **вместе с** агентом (правки применяются на лету, без
перезапуска), запускайте его так:

```bash
connector run --config /etc/connector/connector.yaml --admin 127.0.0.1:8765
```

<Callout>
Разделы «Каталог» и «Интеграции» появляются только у запущенного агента
(`run --admin`): установка плагина и запуск подключений — это работа агента, а не
страницы. `setup` без агента настраивает git-мост и выполняет привязку.
</Callout>

## Обзор

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

- **«Интеграции не будут запущены»** — у процесса нет привилегий, чтобы поместить
  интеграцию под отдельного пользователя ОС ([почему так](/docs/connector/install#привилегии-почему-интеграции-требуют-root)).
- **«Интеграции не на чем запускать»** — на машине нет подходящего Python
  ([какого](/docs/connector/install#среда-выполнения-интеграций)). Когда он есть,
  страница показывает, какой именно интерпретатор используется.

Git-мост в обоих случаях продолжает работать.

## Подключение

Три вещи, которые касаются агента целиком, а не отдельной интеграции.

**Связь с платформой.** Адрес relay уже вшит в агент — менять его нужно только для
собственной инсталляции. Рядом — **каталог состояния** (`state_dir`): там лежат ключ
агента, токены, установленные интеграции и их рабочие каталоги. Он должен переживать
перезапуски.

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

- **«Слушать на»** — адрес и порт на этой машине (например `0.0.0.0:8766`). Пусто —
  приёмник выключен, и это рабочее состояние: опрос идёт всегда.
- **«Адрес, по которому до него достучится ваш трекер»** — как этот порт виден снаружи.
  Агент не может это угадать: за NAT или обратным прокси адрес другой.

_Иллюстрация: Приёмник событий — у коннектора: один адрес на все подключения._

**Привязка.** Вставьте одноразовый код из приложения Buff и нажмите **«Привязать и
подключить»**. Код действует 15 минут и используется один раз; после этого агент
получает собственный ключ и больше кодов не требует.

## Репозитории

Раздел git-моста. Добавьте провайдера — тип (GitLab, GitHub, GitHub Enterprise, Gitea,
Bitbucket, Bitbucket Server), адрес и токен доступа — и нажмите **«Проверить доступ»**:
агент сходит к вашему провайдеру и покажет, что он видит.

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

Токен записывается в файл с правами `600` в каталоге состояния; в конфиг попадает
только ссылка на файл. К нам он не уходит — платформа видит лишь список репозиториев,
которые вы отметили, и признак «доступ есть / нет».

## Каталог

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

_Иллюстрация: Каталог: что интеграция сможет делать, видно до того, как она окажется на машине._

**«Установить»** скачивает подписанный комплект, проверяет подпись и распаковывает его
к себе. Подробнее — [«Каталог и установка плагина»](/docs/connector/marketplace).

## Интеграции

Здесь живут **подключения** — связи с конкретными системами. Одна установленная
интеграция может обслуживать несколько: прод и песочница, две площадки, два проекта
разработки.

**«Добавить подключение»** открывает форму, которая строится **по схеме самой
интеграции**: коннектор не знает ничего про поля Jira или GitHub, он рисует то, что
интеграция о себе объявила.

_Иллюстрация: Форма строится по схеме, которую интеграция объявляет о себе._

Общие поля у всех:

| Поле | Что это |
|---|---|
| **Название** | как подключение называется у вас. Переименование ничего не ломает: ни списания, ни ссылка вебхука к названию не привязаны |
| **Проект разработки** | проект в Buff, куда попадают вопросы и задачи. Имя проекта **внутри вашей организации**, без организации и без косой черты |
| **Учётные данные** | токен, а где трекер входит парой (Jira Cloud, Bitbucket Cloud) — ещё и учётная запись. Пишутся в файл с правами `600`; форма никогда не показывает их обратно |
| **Принимать вебхуки** | выключатель; ссылку с секретом выдаёт коннектор сам |

Остальные поля — от интеграции: адрес системы, список репозиториев или ключей
проектов, псевдоним бота и прочее.

Сохранённое подключение сразу запускается своим процессом и показывает, что оно отдало
модели и куда ему разрешено ходить:

_Иллюстрация: Подключение работает: свой процесс, свой набор инструментов, свой разрешённый адрес._

У каждого подключения есть четыре действия: **«Проверить связь»**, **«Журнал»**,
**«Настроить»** и **«Удалить»**; когда в каталоге появляется более свежая версия —
ещё и **«Обновить до …»**. Что они делают — в разделе
[«Управление и удаление»](/docs/connector/manage).

## Пустое поле — это «не менять»

Секреты страница не показывает: в форме они всегда пустые. Пустое поле при сохранении
означает «оставить как было», а не «стереть». Поэтому поправить название проекта или
список репозиториев можно, не вводя токен заново.