Конфиг вручную (YAML)
Полный справочник файла настроек: провайдеры, приёмник событий и подключения интеграций.
Для автоматизированных установок конфиг задаётся напрямую. Это равноправный путь: локальная страница и команды правят тот же файл, под той же проверкой.
Пример
# 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
# Приёмник вебхуков — один на весь коннектор. Пусто — выключен, работает опрос.
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 | Откуда взять токен: переменная окружения или файл. Ровно одно из двух. |
plugins[] — подключения
Интеграция — это код, подключение — это связь. Две Jira — это два подключения одной интеграции: тот же код, разные учётные данные, разные разрешённые адреса, разная ссылка вебхука, разный пользователь ОС.
| Поле | Описание |
|---|---|
id | GUID подключения. К нему привязаны ссылка вебхука, рабочий каталог и списания, поэтому он не меняется при переименовании. Не указали — коннектор выдаст. |
plugin | Имя интеграции в каталоге (jira, github, redmine, …). |
version | Версия, к которой закреплено подключение. Обязательна: «последняя» — это не конфигурация, а лотерея. |
alias | Человеческое название. Меняется свободно и ничего не ломает. |
slug | Короткое имя: попадает в имена инструментов, которые видит модель. Выводится из alias, если не задан; должен быть уникален. |
dev_project | Проект в Buff, куда попадает работа. Имя внутри организации, без организации и без косой черты. |
enabled | false — подключение настроено, но не запускается. По умолчанию включено. |
config | Настройки самой интеграции. Проверяются по её схеме: лишний ключ или неверное значение — ошибка, а не молчаливое сохранение. Поле, у которого в манифесте есть значение по умолчанию (например адрес API Figma), можно не писать — коннектор подставит его сам, одинаково для формы, командной строки и правил выхода наружу. |
credentials[] | Ссылки на секреты (см. ниже). Значения в YAML не попадают. |
webhook | Принимает ли подключение вызовы. Куда коннектор слушает — в webhooks выше. |
webhook_secret | Секрет в ссылке. Коннектор минтит его сам; переживает переименование, чтобы ссылку, вставленную в трекер, не пришлось менять. |
credentials[]
| Поле | Описание |
|---|---|
name | Имя, которое просит интеграция (обычно api). |
kind | bearer, basic или header — как трекер принимает секрет. Берётся из манифеста интеграции; вручную задавать не нужно. |
username | Учётная запись для basic (например почта Jira Cloud). Не секрет. |
header | Имя заголовка для вида header (например X-Redmine-API-Key). |
token_env / token_file | Откуда взять секрет. |
password_env / password_file | Пароль для basic, если он лежит отдельно от токена. |
Секреты в YAML не хранятся — только ссылка на переменную окружения или файл. Так конфиг можно копировать, сравнивать и держать в системе контроля версий.
Проще всего записать секрет командой — она сама поставит нужный вид доступа из манифеста:
connector instance secret jira_prod --secret api \
--config /etc/connector/connector.yaml < /run/secrets/jira-tokenЧто коннектор дописывает сам
Файл — не только ваш: агент нормализует его при сохранении. Он выдаёт 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