Ключи SSH Bitbucket Cloud: доступ Git только для чтения для ИИ-агентов
Table of Contents
Ограниченный рабочий процесс агента разделяет чтение репозитория, чтение API, управление секретами и удаленную запись. Используйте Git через Secure Shell (SSH) для доступа к исходникам, ключ доступа Bitbucket только для чтения для автоматического checkout, REST API для метаданных и сервер Model Context Protocol (MCP) для разрешенных инструментов. Храните закрытые ключи и API-токены в 1Password. Оставляйте запись за этапом подтверждения человеком.
Основные выводы
- По умолчанию только чтение: используйте ключ доступа к репозиторию или проекту для checkout агента. Ни один из них не дает права push.
- Личная идентичность: используйте личный SSH-ключ для интерактивной работы, связанной с учетной записью пользователя.
- Хранение секретов: используйте 1Password SSH Agent, чтобы Git выполнял разрешенное подписание без чтения закрытого ключа.
- Значение CLI: считайте
git,curlи небольшой проверенный API-wrapper практическими инструментами командной строки Bitbucket. - Граница MCP: предоставляйте узкий набор инструментов чтения. Отключайте инструменты записи или защищайте их отдельным процессом подтверждения.
- Контроль записи: разрешите агенту проверять, сравнивать и подготавливать изменение. Требуйте подтверждения человеком перед push, pull request, слиянием или изменением настроек.
Перед началом
Предварительные требования: доступ к Bitbucket Cloud, Git, клиент OpenSSH, 1Password 8, 1Password CLI, авторизованная CLI или разрешенная служебная учетная запись, а также MCP-хост с управлением разрешениями серверов. Выделите 45 минут. Сложность: средняя.
Для первого запуска используйте тестовый репозиторий. Замените все заполнители в примерах. Команды ниже приведены как непроверенные примеры. Они не относятся к действующей учетной записи или репозиторию Bitbucket.
Версии: в статье приведены проектные рекомендации, а не инструкция для конкретных версий. Перед тестированием проверьте установленные версии Git, OpenSSH, 1Password CLI, Teamwork Graph CLI, MCP-хоста и MCP-сервера. Настройте 1Password SSH Agent для текущей ОС перед использованием ssh-add -l.
Не помещайте учетные данные в оболочки, журналы, URL, удаленные адреса Git и исходные файлы. Используйте заполнители, например <workspace>, <repository>, <api-token> и <socket-path>. Не вставляйте настоящий закрытый ключ в журнал терминала.
Выберите границу доступа
Bitbucket Cloud поддерживает ключи доступа на уровне репозитория, проекта и рабочей области. Область действия определяет последствия копирования ключа. В официальном сравнении ключей доступа прямо описаны различия в разрешениях.
| Способ доступа | Область | Возможность записи | Подходит для |
|---|---|---|---|
| Ключ доступа к репозиторию | Один репозиторий | Нет | Стандартный checkout агента |
| Ключ доступа к проекту | Репозитории в одном проекте | Нет | Задания только для чтения в небольшой группе репозиториев |
| Ключ доступа к рабочей области | Репозитории в одной рабочей области | Да | Управляемая автоматизация службы с отдельным планом записи |
| Личный SSH-ключ | Репозитории, разрешенные одному пользователю | Следует учетной записи | Интерактивное администрирование |
| API-токен | Области API и доступ учетной записи пользователя | Зависит от областей | Чтение через REST API или временная задача записи |
Начните с наименьшей подходящей границы. Выберите ключ репозитория, если достаточно одного репозитория. Выберите ключ проекта, если несколько репозиториев входят в один проект и хватает чтения. Считайте ключ рабочей области идентификатором с правом записи, а не удобным вариантом по умолчанию.
Создайте и зарегистрируйте ключ с минимальной областью действия в соответствующих настройках Bitbucket:
- Для одного репозитория откройте Repository settings, Access keys и Add key. Вставьте открытый ключ и оставьте доступ только для чтения.
- Откройте Project settings, Access keys и Add key, если нескольким репозиториям нужен единый ключ чтения на уровне проекта.
- Используйте ключ рабочей области только в общей рабочей области с утвержденным планом записи. Личные рабочие области не предоставляют такой же вариант на уровне области.
- Запишите метку ключа, область, отпечаток открытого ключа, владельца и дату ротации. Храните закрытый ключ в 1Password.
После регистрации выполните точную проверку соединения только для чтения:
git ls-remote [email protected]:<workspace>/<repository>.git HEAD
Ожидаемый результат: одна ссылка на commit для HEAD. Непроверенный пример. Успешный результат подтверждает, что одна разрешенная SSH-идентичность достигла указанного репозитория. Он не подтверждает выбор зарегистрированного ключа или наличие прав записи. Повторите проверку после настройки отдельного ключа для каждого репозитория.
Сведения о хранении закрытых ключей и согласии 1Password SSH Agent см. в статье 1Password CLI и SSH Agent: защита SSH-ключей для ИИ-агентов .
Правильно определите «Bitbucket CLI»
Термин Bitbucket CLI часто объединяет три разных интерфейса. Разделяйте их.
- Git CLI:
git cloneиgit fetchпередают данные репозитория по SSH или HTTPS.git diffсравнивает локальные файлы или ревизии. - REST-клиент:
curlили проверенный wrapper вызывает Bitbucket Cloud Representational State Transfer (REST) API. API — программный интерфейс для запросов данных или действий. В справочнике Bitbucket Cloud REST API перечислены ресурсы репозиториев, исходников, веток, pull request, pipeline и статусов. - Atlassian CLI:
acli— официальная командная строка Atlassian. Введение описывает продукт, а справочник команд перечисляет разделыadmin,jira,feedbackиrovodev. Справочник не документирует команды Bitbucket Cloud.
Официальный справочник команд acli от Atlassian не документирует команды Bitbucket Cloud. Не придумывайте команду вроде acli bitbucket clone. Используйте Git для операций Git и REST API для данных Bitbucket Cloud.
Необязательный Teamwork Graph CLI
Atlassian также выпускает Teamwork Graph CLI, или twg. Его
обзор
и
каталог команд
описывают семейства команд Bitbucket. Команда настройки:
twg setup
Команда настройки изменяет локальное состояние аутентификации. Следуйте подсказкам установленной версии для необязательной настройки токена Bitbucket. Путь токена Bitbucket CLI отделен от Atlassian OAuth. Сверяйте синтаксис с установленной версией и текущим каталогом команд. Используйте отдельный профиль, ограниченный токен, проверенные установленные навыки и подтверждение человеком для команд, меняющих данные.
Ожидаемый результат, не проверено: изолированный профиль получает настройки аутентификации Bitbucket. Перед настройкой запишите прежнее состояние профиля. Для отката удалите сохраненные учетные данные согласно документированной процедуре выхода или удаления конфигурации установленной версии.
Если сторонний проект называет себя Bitbucket CLI, проверьте исходный код, процесс выпуска, контрольные суммы, путь обновления, поток аутентификации, запрашиваемые области, сетевые назначения, обработку журналов и команды записи. Знакомое имя бинарного файла не подтверждает поддержку поставщика или безопасность разрешений.
Храните SSH-ключи под контролем 1Password
1Password SSH Agent предоставляет Git и SSH-клиентам ключи, хранящиеся в 1Password. Клиент выполняет разрешенный запрос подписи. Закрытый ключ остается в приложении 1Password, которое запрашивает согласие, прежде чем одобренный клиент использует ключ.
Справочник 1Password CLI
выполняет другую задачу. Используйте op для контролируемого доступа к элементам, API-токенам, учетным записям служб и настройкам автоматизации. Для SSH-подписания используйте SSH Agent. Не экспортируйте закрытый ключ во временный файл только ради упрощения работы агента.
Проверьте состояние локальной CLI и агента командами только для чтения:
op --version
ssh-add -l
Ожидаемый результат: версия 1Password CLI и один или несколько отпечатков открытых ключей активного агента. Непроверенный пример. Пустой вывод ssh-add -l означает, что выбранный сокет агента не предоставляет ключ.
Для нового ключа создайте элемент Ed25519 SSH Key в 1Password или импортируйте ключ, созданный доверенным локальным процессом. Присвойте метку по назначению, области и дате ротации. Добавляйте в Bitbucket Cloud только открытый ключ. В руководстве по ключам доступа к репозиторию в Linux описаны настройки репозитория и ограничение только для чтения.
Сначала проверьте ключ хоста Bitbucket
Аутентификация пользователя SSH не подтверждает личность сервера. Клиент должен проверить ключ хоста Bitbucket Cloud до отправки запроса аутентификации. Руководство Atlassian по SSH и двухэтапной проверке содержит открытые ключи хостов и официальный endpoint для получения записей known-hosts.
Получите общедоступные данные ключа хоста для сравнения:
curl --fail --silent --show-error https://bitbucket.org/site/ssh
Ожидаемый результат: строки OpenSSH known_hosts для bitbucket.org. Непроверенный пример. Перед добавлением строки в ~/.ssh/known_hosts сравните возвращенный ключ или отпечаток с независимой доверенной копией.
После добавления утвержденной записи включите строгую проверку хоста:
Host bitbucket.org
StrictHostKeyChecking yes
UserKnownHostsFile ~/.ssh/known_hosts
Не принимайте измененный ключ хоста во время запуска агента. Остановите запуск, проверьте актуальную запись ключа хоста Bitbucket Cloud и просмотрите локальную запись known_hosts. Автоматическое принятие устраняет границу безопасности ключа.
Выберите один ключ на репозиторий
На одном устройстве часто хранятся несколько ключей Bitbucket. Широкий SSH-агент предлагает несколько идентичностей в рамках одного соединения. Сервер или политика с небольшим лимитом попыток аутентификации могут отклонить нужный ключ после неудачных попыток с предыдущими.
В
руководстве Atlassian по нескольким ключам доступа к репозиториям
используется core.sshCommand в файле Git-конфигурации репозитория и includeIf в глобальной конфигурации Git. Применяйте тот же шаблон: один ключ на репозиторий.
Переносимый пример с ключом в файле:
# .gitconfig inside one local repository
[core]
sshCommand = ssh -o IdentitiesOnly=yes -i ~/.ssh/<repository-automation-key>
# ~/.gitconfig
[includeIf "gitdir:~/src/<repository>/"]
path = ~/src/<repository>/.gitconfig
Приведенный блок — исключение с файловым закрытым ключом для отдельной идентичности автоматизации. Он не настраивает 1Password SSH Agent. Для 1Password SSH Agent задайте значение IdentityAgent или SSH_AUTH_SOCK для вашей платформы из
руководства по настройке 1Password
. Некоторые конфигурации OpenSSH используют файл .pub как селектор идентичности агента. Перед применением проверьте поддержку платформы. В конфигурации с файлом нужен соответствующий путь к закрытому ключу. Не передавайте файл .pub команде, ожидающей закрытый ключ, и не экспортируйте личный закрытый ключ.
Используйте явную конфигурацию репозитория, если локальному клону нужен один ключ. Используйте includeIf, если в каталоге хранятся несколько клонов с общей границей доступа.
Руководство по нескольким ключам
показывает обе настройки в рабочем процессе Bitbucket.
Клонируйте через Git по SSH:
git clone [email protected]:<workspace>/<repository>.git <local-directory>
Ожидаемый результат: Git создает <local-directory> и получает репозиторий через bitbucket.org. Непроверенный пример. Ключ доступа к репозиторию разрешает только клонирование и получение данных.
Используйте API-токены для ограниченного чтения REST
Для транспорта Git используйте SSH. Для метаданных и операций вне Git используйте REST API. В
руководстве по разрешениям API-токенов
перечислены области репозитория Read, Write, Admin и Delete. Repository Read соответствует read:repository:bitbucket и не включает доступ к pull request.
Для автоматизации чтения предпочтительнее токен доступа Bitbucket для репозитория или проекта, если конечная точка поддерживает его. Пользовательский API-токен сохраняет более широкий доступ учетной записи. Используйте токен рабочей области только тогда, когда задача указывает на более широкую границу. Перед выбором типа токена изучите руководство по токенам доступа Bitbucket .
Для чтения агентом начните с read:repository:bitbucket. Добавляйте read:pullrequest:bitbucket, только если агенту нужны данные pull request. Области рабочей области или pipeline добавляйте лишь после того, как задача назовет конечную точку и результат. Для записи и администрирования требуется отдельный процесс подтверждения.
Создавайте каждый API-токен для одной цели, задавайте срок действия, записывайте его в журнал ротации и заменяйте токен до истечения срока. Руководство Atlassian по созданию API-токена требует имя, срок действия, выбор приложения и области. После создания токен показывается один раз.
Храните значение в 1Password или управляемом секрете среды выполнения. Не помещайте его в URL удаленного репозитория. Передавайте bearer-токен через переменную среды только процессу, которому нужен один запрос на чтение:
op run --env-file=/path/to/agent.env -- \
sh -c 'curl --fail --silent --show-error \
--request GET \
--url "https://api.bitbucket.org/2.0/repositories/<workspace>/<repository>" \
--header "Authorization: Bearer ${BITBUCKET_API_TOKEN}" \
--header "Accept: application/json"'
Храните /path/to/agent.env вне репозитория. Сохраните в нем ссылку вида BITBUCKET_API_TOKEN=op://synthetic-vault/synthetic-api-token/credential. op run разрешает ссылку и предоставляет значение дочернему процессу curl на время подпроцесса. Это не мешает дочернему процессу читать значение переменной среды или записывать его в журнал. Не заменяйте заполнитель буквальным токеном.
Ожидаемый результат: JSON-метаданные выбранного репозитория. Непроверенный пример. Заполнитель не должен превращаться в настоящий токен в коммите или журнале.
Для более длительной автоматизации используйте внедрение секрета 1Password в среду процесса через поддерживаемую CLI или поток служебной учетной записи. Срок действия токена должен соответствовать задаче. Отзывайте токен, если задача завершилась раньше срока или сменился владелец хоста.
Ограничьте поверхность чтения MCP
При проверке нового сервера используйте текущую спецификацию MCP и ее правила авторизации . HTTP-серверам необходима проверка аудитории токена и понятная обработка ответов 401 и 403.
Хост MCP получает согласие пользователя. Клиент поддерживает соединение с одним сервером. Сервер предоставляет инструменты, ресурсы или prompts. Считайте сервер недоверенным кодом, пока не проверите источник, транспорт, учетную запись и разрешения.
URL спецификации 2025-06-18 в следующем абзаце относится к исторической версии. Для новых проверок используйте актуальную версию 2026-07-28.
Спецификация MCP определяет взаимодействие между хостом, клиентом и сервером MCP. Сервер предоставляет инструменты, ресурсы или prompts через протокол. MCP стандартизирует формат подключения. Хост, реализация сервера, учетная запись, область токена и политика подтверждения по-прежнему определяют доступ вызова.
Используйте сервер MCP как узкий адаптер для Git и REST API Bitbucket Cloud.
Защитите адаптер от передачи токенов, подделки запросов на стороне сервера (SSRF) и проблемы confused deputy. SSRF позволяет серверу отправлять запросы в непредусмотренные места. Проблема confused deputy возникает, когда сервер использует более широкие права от имени вызывающего. Также защитите систему от вредоносных локальных серверов, небезопасных переадресаций OAuth и чрезмерно больших ответов с исходными данными. Зафиксируйте разрешенные источники Bitbucket и идентификаторы репозиториев. Запускайте локальные серверы в песочнице под отдельной учетной записью ОС. Маскируйте секреты в результатах инструментов и журналах.
В этом разделе описан проект, а не проверенная конфигурация MCP. Здесь не зафиксированы клиент, сервер, транспорт, версия или fixture. Проверьте один сервер только для чтения в отдельном тестовом профиле до подключения агента к рабочему репозиторию.
Примеры инструментов чтения:
| Инструмент | Ограниченный результат |
|---|---|
get_repository_metadata |
Возвращает метаданные одного репозитория |
read_source_file |
Читает один путь в заданной ревизии |
list_branches |
Выводит список веток репозитория |
get_pull_request |
Возвращает один pull request, если токен имеет область чтения pull request |
get_build_status |
Возвращает данные статуса одного commit |
Эти имена описывают проект. Это не команды Atlassian. Не разрешайте серверу принимать произвольные URL, команды оболочки, необработанные токены, запросы на экспорт закрытых ключей или неограниченные идентификаторы репозиториев.
Настройте разрешения на четырех уровнях:
- Bitbucket Cloud: ключ чтения репозитория или проекта для Git и минимальные области API-токена для чтения REST.
- 1Password: один vault или служебная учетная запись для задачи без возможности экспорта закрытого ключа.
- Сервер MCP: список разрешенных инструментов чтения, фиксированные конечные точки Bitbucket Cloud, проверка входных данных, ограничения времени ожидания и маскированные журналы.
- Хост MCP: согласие пользователя на сервер и каждое действие записи; инструменты записи отключены в профиле по умолчанию.
Список инструментов MCP подтверждает их обнаружение. Он не доказывает авторизацию, правильную область, безопасную обработку входных данных или корректный результат.
Спланируйте рабочий процесс агента
Сделайте рабочий процесс явным. Каждый этап предоставляет данные для следующего.
| Этап | Действие агента | Разрешение | Подтверждение человеком |
|---|---|---|---|
| Подготовка | Прочитать конфигурацию, запись ключа хоста, метку ключа, область токена и срок действия | Локальное чтение | Утвердить запись настройки |
| Проверка | Клонировать или получать данные через Git по SSH и запрашивать метаданные REST | Чтение репозитория и API | Не требуется после настройки |
| Анализ | Читать файлы, ветки, pull request и статус сборки через разрешенные инструменты | Инструменты MCP только для чтения | Не требуется для ограниченных запросов |
| Подготовка изменения | Создать патч, план ветки или черновик pull request в локальной рабочей области | Только локальная запись | Проверить diff и цель |
| Разрешение записи | Представить точное удаленное действие, область и способ отката | Удаленная запись еще не выполняется | Подтверждение человека |
| Выполнение записи | Отправить ветку, создать pull request или вызвать конечную точку записи | Краткосрочная идентичность с правом записи | Подтвердить каждое действие |
| Проверка результата | Прочитать полученный commit, pull request или статус | Снова только чтение | Подтвердить ожидаемый результат |
Профиль агента по умолчанию должен останавливаться после этапа Анализ или Подготовка изменения. Для отдельного профиля записи используйте другой токен или ключ, короткий срок действия, фиксированную цель и запрос подтверждения. Ключ доступа к репозиторию не позволяет выполнить этап записи, что создает полезную техническую границу.
Откат и удаление
Начните откат с удаления доступа, затем очистите локальную конфигурацию:
- Удалите ключ доступа к репозиторию, проекту или рабочей области в соответствующих настройках Bitbucket.
- Отзовите API-токен репозитория, проекта, рабочей области или пользователя на соответствующей странице безопасности Bitbucket.
- Удалите сохраненные учетные данные Teamwork Graph согласно документированной процедуре аутентификации установленной версии CLI. Предыдущие учетные данные храните только в разрешенном менеджере секретов. Убедитесь, что изолированный профиль больше не показывает тестовые учетные данные.
- После завершения теста удалите
.gitconfigрепозитория и записьincludeIf. Не меняйте несвязанную конфигурацию Git. - Удалите только проверенную запись ключа хоста Bitbucket, добавленную для теста. Сохраните остальные разрешенные ключи хоста.
- Удалите внешний файл
agent.envи временный вывод. Удалите запись MCP-сервера из конфигурации хоста и перезапустите хост.
Запишите каждое удаление, исполнителя и время. Замените ключ или токен, если значение попало в неожиданный журнал, запись процесса или расшифровку.
Цикл удаленного чтения и обновления локальных ссылок
Для регулярной проверки репозитория используйте небольшой цикл:
LOCAL_REPO="<local-directory>"
git -C "$LOCAL_REPO" fetch --no-tags
git -C "$LOCAL_REPO" status --short --branch
git -C "$LOCAL_REPO" log -1 --format='%H %ad %s' --date=iso-strict
HEAD означает текущую проверенную ссылку репозитория. Успешный результат подтверждает, что одна разрешенная SSH-идентичность достигла указанного репозитория. Он не подтверждает выбранный ключ или наличие доступа push.
Ожидаемый результат: результат fetch, статус ветки и одна строка commit. Непроверенный пример. fetch не выполняет запись на удаленном сервере, но обновляет локальные ссылки и FETCH_HEAD. Цикл не выполняет push и не меняет ветки.
Сервер MCP должен предоставлять ту же границу чтения через именованные операции. Локальный wrapper оболочки или инструмент MCP должен отклонять глагол записи до отправки запроса. Записывайте имя инструмента, заполнитель репозитория, ревизию, класс результата и длительность. Маскируйте токены, cookies, личные пути и содержимое файлов, если задача явно не требует чтения одного файла.
Устранение неполадок
Permission denied (publickey)
Проверьте активный сокет агента, выбранный открытый ключ, запись ключа доступа репозитория и IdentitiesOnly. Ключ репозитория должен быть зарегистрирован в целевом репозитории или проекте. Личный ключ требует разрешения учетной записи. Ключ рабочей области имеет другую границу записи.
Предлагается неверный ключ репозитория
Используйте один ключ на репозиторий через core.sshCommand или объедините клоны в каталоге, контролируемом includeIf. Просмотрите ключи агента командой ssh-add -l. Если доступно много ключей 1Password, используйте явный селектор идентичности или закладку SSH 1Password. В
руководстве 1Password Agent
описаны ограничения количества ключей и закладки.
SSH сообщает об измененном ключе хоста
Остановите агента. Не удаляйте known_hosts в качестве первого шага. Сравните текущую запись ключа хоста Bitbucket Cloud с локальной через независимый канал. Удаляйте или заменяйте запись только после успешного сравнения.
API возвращает 401 или 403
Проверьте срок действия токена, тип токена, область конечной точки и границы учетной записи или рабочей области. Область чтения репозитория не включает pull request. Конечная точка записи требует области записи и утвержденного профиля записи. Не расширяйте области, пока не определена неудачная конечная точка.
API возвращает данные репозитория, но не pull request
Добавьте минимальную область чтения pull request в новый или ротированный токен. Не используйте повторно широкий токен пользователя для сервера MCP только для чтения.
Сервер MCP показывает инструменты, но вызов завершается ошибкой
Разделяйте регистрацию сервера, подключение, обнаружение инструментов, выполнение и проверку результата. Просмотрите журнал сервера, не раскрывая токен. Проверьте endpoint и формат входных данных. Повторите запрос один раз после проверки подключения. Отметьте операцию незавершенной, если второй запрос тоже не удался.
Сторонний Bitbucket CLI запрашивает широкий доступ
Остановите установку. Сравните запрашиваемый доступ с описанием задачи. Проверьте исходный код, подписи или контрольные суммы выпусков, сетевые назначения, хранение секретов и действия записи. Официальный справочник команд Atlassian CLI не подтверждает поддержку стороннего бинарного файла Bitbucket.
Следующие шаги
Создайте краткую запись доступа с областью репозитория или проекта, меткой ключа, датой проверки ключа хоста, областями API, сроком действия токена, владельцем 1Password, списком разрешенных инструментов MCP, политикой журналов и утверждающим запись.
Выполните одно клонирование только для чтения, одно чтение метаданных REST и одно чтение через инструмент MCP, используя заполнители в журнале. Сравните результаты. Оставьте профиль агента только для чтения, пока запись и журналы не пройдут проверку.
При поступлении задачи записи сначала подготовьте локальный diff. Укажите целевую ветку, измененные пути, запрашиваемый метод API, область токена и шаг отката. Используйте отдельную краткосрочную идентичность записи только после того, как человек одобрит точное действие.