Решение распространенных ошибок аутентификации Git с помощью SSH и токенов
Исправьте распространенные ошибки аутентификации Git, сопоставив удаленный URL с SSH-ключами, токенами HTTPS и помощниками по учетным данным.
Решение распространенных ошибок аутентификации Git с помощью SSH и токенов
Большинство проблем с аутентификацией Git сводятся к несоответствию между удаленным URL, учетными данными, которые Git пытается использовать, и разрешениями на учетной записи хостинга Git. Текст ошибки может выглядеть драматично, но исправление обычно механическое, как только вы узнаете, какой путь использует Git.
Начните с удаленного URL:
git remote -v
Если вы видите https://github.com/org/repo.git, Git использует HTTPS и потребует имя пользователя плюс токен или помощник по учетным данным, который может его предоставить. Если вы видите [email protected]:org/repo.git, Git использует SSH и потребует закрытый ключ, соответствующий открытому ключу, зарегистрированному на хосте.
Не смешивайте их при устранении неполадок. Выберите HTTPS или SSH, сделайте удаленный URL соответствующим, а затем протестируйте этот путь напрямую.
Читайте ошибку буквально
fatal: Authentication failed for 'https://...' обычно означает, что Git достиг сервера, но не предоставил действительные учетные данные HTTPS. Старые учетные данные могли быть кэшированы, токен мог истечь или токен может не иметь доступа к этому репозиторию.
remote: Permission to org/repo denied или 403 Forbidden обычно означает, что ваша личность была распознана, но у нее нет разрешения на выполнение операции. Например, вы можете использовать токен от неправильной учетной записи, токен без права записи или SSH-ключ, привязанный к другому пользователю.
Permission denied (publickey) означает, что SSH не предложил ключ, который принимает сервер.
Повторяющийся запрос имени пользователя/пароля через HTTPS обычно означает, что Git продолжает получать отказ и снова запрашивает. Многократный ввод пароля учетной записи не поможет на хостах, требующих токены для операций Git.
Исправление HTTPS с помощью персонального токена доступа
Для удаленных репозиториев HTTPS создайте персональный токен доступа в настройках учетной записи вашего хостинга Git. Точные названия меню различаются между GitHub, GitLab, Bitbucket и самостоятельными платформами, но суть одна: создайте токен, предоставьте ему доступ к репозиторию, установите срок действия, соответствующий политике вашей организации, и скопируйте его немедленно.
Когда Git запросит, используйте ваше обычное имя пользователя и вставьте токен в качестве пароля:
Username: your-username
Password: <paste-token-here>
Используйте самые узкие разрешения, которые работают. Для частного репозитория, в который вы отправляете изменения, вам нужен доступ на чтение и запись к репозиторию. Для клонирования публичных репозиториев токен может вообще не понадобиться. Детализированные токены и правила SSO организации могут добавить еще один слой: токен может существовать, но все еще требовать одобрения или авторизации SSO, прежде чем сможет получить доступ к корпоративному репозиторию.
Если Git никогда не запрашивает новый токен, вероятно, он использует старые кэшированные учетные данные. Очистите сохраненную запись для хоста, а затем попробуйте снова.
На macOS проверьте Связку ключей на наличие записей, связанных с вашим хостингом Git, таких как github.com или git:https://github.com.
На Windows откройте Диспетчер учетных данных и удалите соответствующую общую учетную запись для хоста.
На Linux проверьте настроенный помощник:
git config --global --get credential.helper
git config --show-origin --get-all credential.helper
Помощник cache хранит учетные данные временно в памяти. Помощник store записывает их на диск в открытом виде, если вы не настроите более безопасный уровень хранения, поэтому используйте его осторожно. Система помощников по учетным данным Git предназначена для запроса учетных данных у помощников и сохранения успешных; безопасность зависит от выбранного помощника.
Полезная последовательность сброса HTTPS:
git remote -v
git config --show-origin --get-all credential.helper
# удалить старые учетные данные из хранилища учетных данных ОС
git ls-remote origin
git ls-remote origin — это чистый тест, потому что он связывается с удаленным репозиторием без изменения вашего рабочего дерева.
Исправление SSH с помощью ключей
Для удаленных репозиториев SSH сначала проверьте, есть ли у вас уже ключи:
ls -al ~/.ssh
Общие имена ключей включают id_ed25519, id_rsa и специфичные для хоста имена, такие как github_work_ed25519. Файл .pub — это открытый ключ, который вы загружаете на хостинг Git. Файл без .pub является закрытым и не должен распространяться.
Если вам нужен новый ключ, Ed25519 — хороший выбор по умолчанию на современных системах:
ssh-keygen -t ed25519 -C "[email protected]"
Используйте парольную фразу, если только ваша среда не имеет особой причины для автоматизации без нее. Затем добавьте открытый ключ в вашу учетную запись хостинга Git или настройки ключа развертывания:
cat ~/.ssh/id_ed25519.pub
Проверьте соединение напрямую:
ssh -T [email protected]
Для GitLab или Bitbucket замените имя хоста. Успешный тест обычно выводит приветствие или сообщение о том, что доступ к оболочке не предоставлен. Это нормально; аутентификация Git-over-SSH все равно может работать.
Если SSH все еще не работает, спросите SSH-клиент, что он делает:
ssh -vT [email protected]
Ищите строки, показывающие, какие ключи предлагаются. Если ваш ключ не предлагается, загрузите его в агент:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
Для нескольких учетных записей на одном хосте используйте ~/.ssh/config, чтобы Git знал, какой ключ принадлежит какому удаленному репозиторию:
Host github-work
HostName github.com
User git
IdentityFile ~/.ssh/github_work_ed25519
IdentitiesOnly yes
Затем укажите репозиторию на этот псевдоним:
git remote set-url origin git@github-work:org/repo.git
Это позволяет избежать распространенной проблемы, когда SSH предлагает ваш личный ключ для рабочего репозитория.
Чистое переключение протоколов
Если ваша команда стандартизирует SSH, измените удаленный репозиторий HTTPS следующим образом:
git remote set-url origin [email protected]:ORG/REPO.git
Если ваша компания блокирует SSH или требует проверки HTTPS, переключитесь другим способом:
git remote set-url origin https://github.com/ORG/REPO.git
После изменения URL протестируйте операцию чтения:
git fetch origin
Затем протестируйте действие, которое не удалось:
git push origin HEAD
Если fetch работает, а push не удается, аутентификация, вероятно, действительна, а проблема в авторизации. Проверьте защиту веток, роль репозитория, область действия токена и правила SSO организации.
Среды CI и серверов
На агентах сборки и серверах по возможности избегайте использования личного токена человека. Предпочитайте ключи развертывания, машинных пользователей или встроенное хранилище учетных данных вашей системы CI. Храните секреты вне истории команд и журналов. Не вставляйте токены в удаленные URL, подобные этому, если вы не находитесь в контролируемой одноразовой среде:
https://[email protected]/org/repo.git
Такой стиль может просочиться через журналы, списки процессов, историю оболочки и файлы конфигурации.
Для Jenkins, раннеров GitHub Actions, раннеров GitLab и подобных систем храните учетные данные в секретном механизме платформы и внедряйте их только для задания, которое в них нуждается.
Краткий контрольный список
Выполните их по порядку, когда застрянете:
git remote -v
git ls-remote origin
Если URL — HTTPS, очистите старые кэшированные учетные данные и используйте текущий токен с правильными разрешениями репозитория.
Если URL — SSH, выполните:
ssh -T git@your-hostname
ssh -vT git@your-hostname
Убедитесь, что ожидаемый ключ предлагается и что его открытая половина зарегистрирована в правильной учетной записи.
Если аутентификация прошла успешно, но push не удается, ищите правила авторизации: защищенные ветки, отсутствующая роль записи, истекшая авторизация SSO, ключи развертывания только для чтения или токены без разрешения на запись.
Надежное исправление — не пробовать случайные пароли. Сопоставьте удаленный протокол с типом учетных данных, удалите устаревшие кэшированные учетные данные, проверьте соединение напрямую, а затем проверьте разрешения на репозиторий.