Настройка SSH-ключей для Git на Linux: полное руководство

Введение / Зачем это нужно

Работа с Git-репозиториями по протоколу HTTPS требует постоянного ввода логина и пароля (или токена). Это неудобно и небезопасно. SSH-ключи решают обе проблемы:

• Безопасность: Используется пара криптографических ключей вместо пароля. Приватный ключ хранится только у вас.
• Удобство: После однократной настройки ssh-agent не нужно вводить никакие учетные данные при каждом git push, git pull или git clone.

Это руководство предназначено для пользователей Linux (Ubuntu, Debian, Fedora, Arch и др.) и поможет настроить бесшовную и безопасную работу с любым Git-хостингом, поддерживающим SSH (GitHub, GitLab, Bitbucket, собственный сервер).

Требования / Подготовка

Перед началом убедитесь, что:

1. У вас есть установленный Git (версии 2.30+). Проверить: git --version.
2. У вас есть аккаунт на GitHub, GitLab или другом сервисе, куда вы планируете пушить код.
3. У вас есть доступ к терминалу (консоли) Linux с правами вашего обычного пользователя.
4. Пакет openssh-client установлен. Обычно он есть по умолчанию. Проверить можно командой:

   ssh -V
   

   Если команда не найдена, установите пакет:
   • Ubuntu/Debian: sudo apt update && sudo apt install openssh-client
   • Fedora: sudo dnf install openssh-clients
   • Arch: sudo pacman -S openssh

Пошаговая инструкция

Шаг 1: Сгенерируйте новую SSH-ключевую пару

Рекомендуется использовать современный и безопасный алгоритм ED25519. Если ваша система очень старая и не поддерживает его, используйте RSA (минимум 4096 бит).

1. Откройте терминал.
2. Выполните команду генерации. Вам будет предложено выбрать место сохранения файла (по умолчанию ~/.ssh/id_ed25519) и задать парольную фразу (passphrase).

   ssh-keygen -t ed25519 -C "your_email@example.com"
   

   • -t ed25519 — тип ключа.
   • -C "your_email@example.com" — комментарий, обычно указывают email, привязанный к аккаунту на Git-хостинге. Это удобно для идентификации.
3. Настройте парольную фразу (passphrase):
   • Сильная парольная фраза (рекомендуется): Защитит ваш приватный ключ, если кто-то получит физический доступ к вашему диску. Вам нужно будет ввести её один раз при запуске ssh-agent.
   • Пустая парольная фраза: Ключ не будет защищен паролем. Удобно для автоматизации, но менее безопасно. Нажимайте Enter дважды, чтобы оставить поле пустым.
   
   В результате в директории ~/.ssh/ появятся два файла:
   • id_ed25519 — приватный ключ. НИКОМУ НЕ ПОКАЗЫВАТЬ.
   • id_ed25519.pub — публичный ключ. Его вы будете загружать на сервер.

Шаг 2: Запустите и добавьте ключ в ssh-agent

ssh-agent — это программа-посредник, которая хранит ваш разблокированный приватный ключ в памяти и подписывает запросы от вашего имени. Это избавляет от необходимости вводить парольную фразу при каждой операции с Git.

1. Запустите агент (в большинстве современных дистрибутивов он запускается автоматически при входе в систему, но лучше убедиться):

   eval "$(ssh-agent -s)"
   

   
   Вывод должен быть примерно таким: Agent pid 12345.
2. Добавьте ваш приватный ключ в агент:

   ssh-add ~/.ssh/id_ed25519
   

   
   Если вы задали парольную фразу, система запросит её сейчас. После успешного добавления вы увидите сообщение Identity added: /home/username/.ssh/id_ed25519 (your_email@example.com).

Шаг 3: Скопируйте публичный ключ в буфер обмена

Вам нужно передать содержимое файла ~/.ssh/id_ed25519.pub (целиком, включая ssh-ed25519 ... comment) в настройки вашего аккаунта на Git-хостинге.

Используйте команду cat для вывода и перенаправление вывода в буфер обмена (или скопируйте вручную):

# Для систем с xclip (Ubuntu/Debian: sudo apt install xclip)
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard
echo "Публичный ключ скопирован в буфер обмена."

# Альтернатива: просто выведите на экран и скопируйте мышкой
cat ~/.ssh/id_ed25519.pub

Шаг 4: Добавьте публичный ключ в аккаунт сервиса

Процесс почти идентичен для GitHub, GitLab и других сервисов.

Для GitHub:

1. В правом верхнем углу нажмите на аватар → Settings.
2. В меню слева выберите SSH and GPG keys.
3. Нажмите New SSH key.
4. В поле Title дайте ключу осмысленное имя (например, "Ноутбук - Ubuntu 22.04").
5. В поле Key вставьте содержимое из буфера обмена (то, что вы скопировали на предыдущем шаге).
6. Нажмите Add SSH key. Может потребоваться ввести пароль от аккаунта для подтверждения.

Для GitLab:

1. Нажмите на аватар → Preferences.
2. В меню слева выберите SSH Keys.
3. В поле Key вставьте ключ. Поле Title заполните по желанию.
4. Нажмите Add key.

Шаг 5: Протестируйте подключение

Перед тем как клонировать или работать с репозиториями, проверьте, что аутентификация проходит успешно.

Для GitHub:

ssh -T git@github.com

Для GitLab (gitlab.com):

ssh -T git@gitlab.com

Для GitLab (самохост):

ssh -T git@<ваш-домен-гитлаба>

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

  Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.
  

  Или для GitLab:

  Welcome to GitLab, @username!
  

Если вы видите сообщение Permission denied (publickey), вернитесь к шагу 2 и проверьте, что ключ добавлен в ssh-agent (ssh-add -l), и что вы скопировали публичный ключ (.pub), а не приватный.

Проверка результата

Теперь попробуйте клонировать любой публичный репозиторий по его SSH-URL (а не HTTPS!). Например:

git clone git@github.com:FixPedia/example-repo.git

Процесс должен пройти без запросов пароля или токена. Если клонирование прошло успешно, и вы можете делать git push в свои репозитории — настройка завершена!

Возможные проблемы

1. Ошибка Permission denied (publickey) при тесте или клонировании

• Причина: Сервер не видит ваш ключ или ssh-agent не предлагает его.
• Решение:
  1. Проверьте, что ключ добавлен в агент: ssh-add -l. Если список пуст или ключа нет — добавьте заново: ssh-add ~/.ssh/id_ed25519.
  2. Убедитесь, что вы загрузили публичный ключ (id_ed25519.pub) в настройки аккаунта на сервере (GitHub/GitLab).
  3. Проверьте, что в ~/.ssh/config (если он есть) нет ошибочных настроек для хоста github.com или gitlab.com.

2. Неправильные права на файлы в ~/.ssh/

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

  chmod 700 ~/.ssh
  chmod 600 ~/.ssh/id_ed25519
  chmod 644 ~/.ssh/id_ed25519.pub
  

3. Проблемы с ssh-agent после перезагрузки

• Причина: Агент завершает работу при выходе из системы.
• Решение: Настройте автоматический запуск ssh-agent и добавление ключа при старте сессии. Часто это делается через файл ~/.bashrc или ~/.zshrc:

  # Автозапуск агента, если он не запущен
  if ! pgrep -u "$USER" ssh-agent > /dev/null; then
      eval "$(ssh-agent -s)"
  fi
  # Добавление ключа, если он еще не добавлен
  ssh-add -l > /dev/null || ssh-add ~/.ssh/id_ed25519 2>/dev/null
  

  После добавления выполните source ~/.bashrc (или перезайдите в систему).

4. Сервер использует нестандартный порт SSH (не 22)

• Причина: Некоторые корпоративные или самохостенные Git-серверы используют порт, отличный от 22 (например, 2222).
• Решение: Настройте SSH для конкретного хоста через конфигурационный файл ~/.ssh/config:

  Host gitlab-company
      HostName gitlab.yourcompany.com
      Port 2222
      User git
      IdentityFile ~/.ssh/id_ed25519_company
  

  Затем используйте в URL короткое имя хоста: git@gitlab-company:group/project.git.