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

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

Для автоматизированных установок конфиг задаётся напрямую. Это равноправный путь:
[локальная страница](/docs/connector/web-setup) и [команды](/docs/connector/cli-setup)
правят тот же файл, под той же проверкой.

## Пример

```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 не хранятся** — только ссылка на переменную окружения или файл. Так
конфиг можно копировать, сравнивать и держать в системе контроля версий.

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

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

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

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

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

<Callout type="warn">
Секция, которой агент не знает, **сохраняется нетронутой** и не используется — так
конфиг от более новой версии не теряется при откате. Именно поэтому старая секция
`jira:` остаётся в файле и о ней написано на локальной странице: она не работает и не
мешает.
</Callout>

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

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