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

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

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

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

Портов наружу открывать не нужно: агент только звонит сам. Приёмник событий — отдельная и необязательная настройка.

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

Скачайте файл для вашей ОС и архитектуры на странице загрузок:

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. Проверьте контрольную сумму и подпись до запуска:

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:

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) хранит ключ агента, токены и установленные интеграции — смонтируйте его, чтобы они пережили перезапуск контейнера. Для разовых команд переопределите аргументы:

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

Контейнер, запущенный с --user, не сможет изолировать интеграции: смена пользователя требует привилегий, которых у такого процесса нет. Для git-моста это безразлично, для интеграций — нет.

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

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

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

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

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

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

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

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

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

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

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, а не про отсутствующий файл.

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

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

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

Локальная страница — формы в браузере.
Терминал — то же самое командами.
YAML вручную — для Ansible и CI.

Установка