Полный справочник файла настроек: провайдеры, приёмник событий и подключения интеграций.

Для автоматизированных установок конфиг задаётся напрямую. Это равноправный путь: локальная страница и команды правят тот же файл, под той же проверкой.

Пример

# middleware_url можно не указывать — адрес relay уже вшит в агент.
state_dir: /var/lib/connector

providers:
  - kind: gitlab
    base_url: https://gitlab.corp.local
    token_env: GITLAB_TOKEN            # токен из переменной окружения
    repos:
      - group/app
      - group/lib
  - kind: bitbucket-server
    base_url: https://bitbucket.corp.local
    token_file: /run/secrets/bb.token  # …или из файла
    repos:
      - PROJ/service

# Приёмник вебхуков — один на весь коннектор. Пусто — выключен, работает опрос.
# Обязателен для комментариев к коммитам GitLab и для Figma без списка файлов и проектов
# (для Figma — адрес, доступный из интернета).
webhooks:
  listen: 0.0.0.0:8766
  host: connector.corp.local:8766

plugins:
  - id: 8GXN8BECS24D392A          # GUID; коннектор выдаст его сам, если не указать
    plugin: jira
    version: 1.4.1
    alias: Jira прод
    slug: jira_prod               # выводится из alias, если не указан
    dev_project: backend
    enabled: true
    config:                       # проверяется по схеме интеграции
      base_url: https://jira.corp.local
      project_keys: [PROJ, OPS]
      mention_alias: buff
    credentials:
      - name: api
        kind: bearer
        token_file: /var/lib/connector/secrets/jira-8GXN8BECS24D392A-api.token
    webhook: true
    webhook_secret: 1BXYNH8PA7ZYNZGN

Верхний уровень

Поле	Описание
`middleware_url`	Опционально. Адрес relay Buff — вшит в агент; задавайте только для собственной инсталляции.
`state_dir`	Каталог для ключа агента, секретов, установленных интеграций и их рабочих каталогов. Должен переживать перезапуски.
`providers`	git-провайдеры, которые обслуживает мост.
`webhooks`	Приёмник событий: `listen` — адрес и порт на этой машине, `host` — как этот порт виден трекеру. Пусто — приёмник выключен.
`plugins`	Подключения интеграций.

`providers[]`

Поле	Описание
`kind`	`github`, `ghe`, `gitlab`, `gitea`, `bitbucket`, `bitbucket-server`.
`base_url`	Адрес вашего git-сервера (или облачного провайдера).
`repos`	Репозитории (`owner/name`, у Bitbucket Server — `PROJECT/slug`).
`token_env` / `token_file`	Откуда взять токен: переменная окружения или файл. Ровно одно из двух.

Интеграция — это код, подключение — это связь. Две Jira — это два подключения одной интеграции: тот же код, разные учётные данные, разные разрешённые адреса, разная ссылка вебхука, разный пользователь ОС.

Поле	Описание
`id`	GUID подключения. К нему привязаны ссылка вебхука, рабочий каталог и списания, поэтому он не меняется при переименовании. Не указали — коннектор выдаст.
`plugin`	Имя интеграции в каталоге (`jira`, `github`, `redmine`, …). У своего сервера пусто: вместо `plugin`/`version` у него блок `mcp`.
`version`	Версия, к которой закреплено подключение. Обязательна: «последняя» — это не конфигурация, а лотерея.
`alias`	Человеческое название. Меняется свободно и ничего не ломает.
`slug`	Короткое имя: попадает в имена инструментов, которые видит модель. Выводится из `alias`, если не задан; должен быть уникален.
`dev_project`	Проект разработки или пространство в Buff, куда попадает работа. Имя внутри организации, без организации и без косой черты.
`enabled`	`false` — подключение настроено, но не запускается. По умолчанию включено.
`config`	Настройки самой интеграции. Проверяются по её схеме: лишний ключ или неверное значение — ошибка, а не молчаливое сохранение. Поле, у которого в манифесте есть значение по умолчанию (например адрес API Figma), можно не писать — коннектор подставит его сам, одинаково для формы, командной строки и правил выхода наружу.
`credentials[]`	Ссылки на секреты (см. ниже). Значения в YAML не попадают.
`webhook`	Принимает ли подключение вызовы. Куда коннектор слушает — в `webhooks` выше.
`webhook_secret`	Секрет в ссылке. Коннектор минтит его сам; переживает переименование, чтобы ссылку, вставленную в трекер, не пришлось менять.
`poll_seconds`	Как часто читать это подключение. Пусто — как предлагает интеграция, иначе умолчание коннектора.
`ai_notes`	Пояснения для ИИ: свободный текст о том, что модели стоит знать про эту систему. Уходит модели вместе с описанием инструментов подключения. До 2048 символов, пока не снят предел.
`ai_notes_unbounded`	`true` снимает предел длины `ai_notes`. Это ваше согласие с риском: избыточный текст ухудшает работу модели и увеличивает стоимость; коннектор ничего не обрезает. Файл с `ai_notes` длиннее предела и без этого флага загружен не будет.

`credentials[]`

Поле	Описание
`name`	Имя, которое просит интеграция (обычно `api`).
`kind`	`bearer`, `basic` или `header` — как трекер принимает секрет; `service_account` (JSON-ключ сервисного аккаунта) или `oauth2` (свой OAuth-клиент и refresh-токен) — виды, для которых коннектор выпускает токены сам. Берётся из манифеста интеграции; где интеграция предлагает несколько видов, выбирается в форме или флагом `--kind`.
	У своего сервера: `env` — секрет попадает серверу переменной окружения под именем `name`; `secret` — только там, где на него есть `${user_config.name}`; `header` — заголовок `Authorization` удалённого сервера.
`username`	Учётная запись для `basic` (например почта Jira Cloud). Не секрет.
`header`	Имя заголовка для вида `header` (например `X-Redmine-API-Key`).
`token_env` / `token_file`	Откуда взять секрет. Для `service_account` — JSON-ключ целиком; для `oauth2` — JSON `{"client_id","client_secret","refresh_token"}`, где refresh-токен дописывает сам коннектор после входа.
`password_env` / `password_file`	Пароль для `basic`, если он лежит отдельно от токена.

Секреты в YAML не хранятся — только ссылка на переменную окружения или файл. Так конфиг можно копировать, сравнивать и держать в системе контроля версий.

Проще всего записать секрет командой — она сама поставит нужный вид доступа из манифеста:

connector instance secret jira_prod --secret api \
  --config /etc/connector/connector.yaml < /run/secrets/jira-token

`mcp` — свой сервер

Подключение к серверу MCP, который вы принесли сами. Такое подключение не называет plugin и version; что запускать, описано здесь. Ровно одно из command и url.

plugins:
  - id: 7QK3M9XBWZ0FVT2H
    alias: Погода
    slug: weather_mcp
    dev_project: backend
    config:
      units: metric
    credentials:
      - name: api_key
        kind: secret
        token_file: /var/lib/connector/secrets/mcp-7QK3M9XBWZ0FVT2H-api_key.token
    mcp:
      source: archive
      origin: weather-mcp.mcpb
      name: weather-mcp
      version: 1.0.0
      command: node
      args: ["${__dirname}/server/index.js"]
      env:
        API_KEY: ${user_config.api_key}
        UNITS: ${user_config.units}
      read_only: [forecast]
      accepted: true

Поле	Описание
`source`	Откуда сервер: `archive`, `github`, `url`, `command`.
`origin`	Имя архива или адрес репозитория — для вас, коннектор его не использует.
`name`, `version`	Как сервер назвала его упаковка. Запустившийся сервер представляется сам, и в отчёте — его слова.
`command`, `args`, `env`	Что запустить. `node`, `npx`, `python`, `uvx` коннектор заменит на найденные на машине; `${__dirname}` — каталог с кодом, `${user_config.имя}` — значение из `config` или секрет из `credentials`. Настройка, которой нет, — ошибка запуска с её именем.
`url`	Адрес удалённого сервера (Streamable HTTP) вместо `command`. Заголовок `Authorization` — учётные данные вида `header`.
`read_only`	Инструменты, которые вы отметили как читающие. Только они доходят до модели; слово самого сервера — подсказка на странице, не решение. Меняется без перезапуска.
`accepted`	`true` — ваше согласие: код не проверялся, сеть не ограничивается. Без него подключение не запускается, даже вписанное руками.

Что коннектор дописывает сам

Файл — не только ваш: агент нормализует его при сохранении. Он выдаёт id, выводит slug, минтит webhook_secret и приводит ссылки на секреты к файлам, которые сам создал. Правки применяются на лету: агент следит за файлом, перезапуск не нужен.

Две интеграции, названные одинаково, не конфликтуют: слаг делается уникальным автоматически, а GUID у каждой свой.

Секция, которой агент не знает, сохраняется нетронутой и не используется — так конфиг от более новой версии не теряется при откате. Именно поэтому старая секция jira: остаётся в файле и о ней написано на локальной странице: она не работает и не мешает.

Привязка и запуск

connector pair --config /etc/connector/connector.yaml --code bufc_…
connector run  --config /etc/connector/connector.yaml --admin 127.0.0.1:8765

Конфиг вручную (YAML)