# Установка

> Бинарь или образ, проверка подписи, привилегии для интеграций и среда, в которой они работают.

Агент — один самодостаточный исполняемый файл. Ставьте его на любую машину в вашей
сети, у которой есть доступ к вашему git-серверу (и к трекеру, если ставите
интеграцию) и исходящий доступ в интернет.

## Что нужно на машине

| | Зачем | Без этого |
|---|---|---|
| **git** | агент вызывает его для работы с репозиториями | git-мост не работает; в Docker-образе git уже есть |
| **root или CAP_SETUID** | интеграция запускается под отдельным пользователем ОС | git-мост работает, интеграции не поднимаются |
| **Python 3.11+**, доступный другим пользователям | интеграции написаны на Python | git-мост работает, интеграции не поднимаются |
| исходящий HTTPS | связь с платформой и каталогом | агент не привяжется |

Портов наружу открывать не нужно: агент только звонит сам. Приёмник событий —
[отдельная и необязательная](/docs/connector/trackers#события-опрос-и-вебхуки)
настройка.

## Бинарный файл

Скачайте файл для вашей ОС и архитектуры на **[странице загрузок](/downloads)**:

- Linux — `connector-linux-amd64` / `connector-linux-arm64`
- macOS — `connector-darwin-arm64` / `connector-darwin-amd64`
- Windows — `connector-windows-amd64.exe` / `connector-windows-arm64.exe`

Рядом лежат `SHA256SUMS` и открытый ключ `cosign.pub`. Проверьте контрольную сумму и
подпись **до** запуска:

```bash
sha256sum -c SHA256SUMS --ignore-missing
cosign verify-blob --key cosign.pub \
  --signature connector-linux-amd64.sig connector-linux-amd64
chmod +x connector-linux-amd64 && sudo mv connector-linux-amd64 /usr/local/bin/connector
connector version
```

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

## Docker

Образ мультиарх (amd64/arm64) и уже содержит `git`:

```bash
docker run -d --name buff-connector \
  -v /srv/connector:/etc/connector \
  -v buff-connector-state:/var/lib/connector \
  registry.buff.systems/buff/connector:latest
```

Том состояния (`/var/lib/connector`) хранит ключ агента, токены и установленные
интеграции — смонтируйте его, чтобы они пережили перезапуск контейнера. Для разовых
команд переопределите аргументы:

```bash
docker run --rm -v /srv/connector:/etc/connector \
  registry.buff.systems/buff/connector:latest \
  pair --config /etc/connector/connector.yaml --code bufc_…
```

<Callout type="warn">
Контейнер, запущенный с `--user`, **не сможет изолировать интеграции**: смена
пользователя требует привилегий, которых у такого процесса нет. Для git-моста это
безразлично, для интеграций — нет.
</Callout>

## Привилегии: почему интеграции требуют root

Каждое подключение работает **своим процессом под своим пользователем ОС** — именно
это отделяет интеграцию от ключа коннектора и от ваших токенов
([подробно](/docs/connector/isolation)). Завести такой процесс может только тот, кто
умеет менять пользователя: root или процесс с `CAP_SETUID`.

Если привилегий нет, агент **не запускает интеграции вовсе** и говорит об этом на
своей локальной странице. Это не деградация «работает, но без изоляции»: без
изоляции это другое обещание безопасности, и мы его не даём.

Git-мост при этом работает полностью. Коннектор, который переносит репозитории и
ничего больше, можно держать под обычной учётной записью.

## Среда выполнения интеграций

Интеграции написаны на Python. Коннектор берёт интерпретатор в таком порядке:

1. **Свой, развёрнутый рядом с состоянием** — `<state_dir>/runtime/python/bin/python3`.
   Он предпочтительнее: версия зафиксирована, посторонних библиотек в нём нет.
2. **Системный** — первый `python3` в `PATH` версии **3.11 или новее**, до которого
   может дотянуться пользователь подключения.

Локальная страница показывает, какой интерпретатор используется, а если подходящего
нет — говорит об этом прямо, вместо того чтобы уронить подключение с «permission
denied».

<Callout type="warn">
Интерпретатор должен быть доступен **другому пользователю**, а не только root:
интеграция работает под собственным пользователем ОС. Python, установленный в
домашний каталог root (`/root/…`, права `700`), не подойдёт, каким бы новым он ни
был — коннектор такой пропустит и скажет почему.
</Callout>

Развернуть собственную среду, если системный Python старый или его нет:

```bash
STATE=/var/lib/connector                  # ваш state_dir
mkdir -p "$STATE/runtime"
# самодостаточная сборка CPython 3.12 (python-build-standalone), архив install_only:
curl -L -o /tmp/py.tar.gz "<ссылка со страницы релизов проекта>"
tar xzf /tmp/py.tar.gz -C "$STATE/runtime"      # даст $STATE/runtime/python
chmod -R a+rX "$STATE/runtime"                  # подключение работает под другим пользователем
"$STATE/runtime/python/bin/python3" --version
```

Имя файла в релизах меняется от версии к версии, поэтому ссылку берите со страницы
релизов. Важно выбрать правильную сборку: **gnu** — для обычного хоста, **musl** — для
Docker-образа (он на alpine). Перепутанная сборка падает с «no such file or
directory», и это про загрузчик ELF, а не про отсутствующий файл.

## Обновление агента

Скачайте новую версию, [проверьте подпись](#бинарный-файл) и замените исполняемый файл
(или потяните свежий образ и перезапустите контейнер). Каталог состояния и конфиг
сохраняются: установленные интеграции, подключения и их секреты остаются на месте.
Версия агента видна в приложении, в разделе «Коннекторы».

## Дальше — настройка

- [Локальная страница](/docs/connector/web-setup) — формы в браузере.
- [Терминал](/docs/connector/cli-setup) — то же самое командами.
- [YAML вручную](/docs/connector/yaml) — для Ansible и CI.