Генерация ключа, настройка

Для начала надо сгенерировать ключ командой:

ssh-keygen

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

~/.ssh/

т.е. в скрытую директорию .ssh в домашней папке текущего юзера, это верно и для винды тоже, при условии что вы пользуетесь Git Bash. Там же ключи скорее всего будет искать ваш SSH-клиент. Если ваши ключи по какой-то причине попали в корень домашней папки или куда-то ещё, обязательно переместите их в  .ssh или нихрена не будет работать.

SSH-ключи — это файлы. Как любые файлы, их удобно называть сообразно их назначению, особенно если ключей несколько. т.е. лучше называть ключи так, чтобы вы поняли, от чего они. Например, gitea или git.coders-teaparty.cafe . Если ключ нестандартно называется, SSH-клиент его не узнает, пока вы не добавите его в конфиг, или вручную не укажете в команде подключения по SSH ключом -i  (см. полезный тред на SO о нестандартных именах ключей). Лучше использовать конфиг, в нем масса полезных возможностей, и настраивать его совсем просто.

Создаём файл config без расширения в папке ~/.ssh (на винде это C:/Users/<имя пользователя>/.ssh), и добавляем туда следующее:

Host <имя ключа>
  IdentityFile ~/.ssh/<название файла приватного ключа>

Здесь имя ключа — это человеко-читаемое название ключа для вас, SSH оно интересует чисто как идентификатор. IdentityFile — это как раз путь к файлу приватного ключа (который без расширения .pub) как бы он у вас не назывался.  Строго говоря, ключи можно хранить где угодно, и указать кастомную директорию тем же способом что кастомное имя, но я бы посоветовал придерживаться стандартной, т.к. её можно легко загуглить, если забыли. В конфиге можно указать много полезных опций вроде адреса сервера, нестандартного порта SSH, юзера от имени которого происходит SSH-соединение, но в данном сценарии нам это всё не нужно, т.к. будет автоматически сгенерировано и добавлено в адрес репозитория, который мы потом копируем в git remote, о чем далее по тексту.

Добавление ключа в аккаунт Gitea

Добавление ключа

Нужно перейти во вкладку Settings > SSH / GPG Keys вашего аккаунта, и нажать добавление нового SSH-ключа. Первое поле это имя ключа, с ним всё просто, опять же нужно название которое вам будет однозначно указывать, откуда будет использоваться этот ключ. Второе поле — это публичный ключ, который вы привязываете к аккаунту. Публичный ключ должен быть под тем же именем что и приватный с расширением .pub. Копируем текст ключа во второе поле и сохраняем. Потом ключ необходимо будет верифицировать.

Верификация ключа

Скопируйте себе куда-нибуть(например в блокнот) следующую команду:

echo -n '<токен>' | ssh-keygen -Y sign -n gitea -f <путь к файлу приватного ключа>

Заменяя <путь к файлу приватного ключа> на полный путь к файлу приватного ключа включая его имя.

Жмем кнопку verify. Теперь надо действовать быстро — у верификации есть таймаут и он довольно короткий. Вам дадут токен и команду, почти точно такую же, как вы уже выписали в блокнот. Токен копируем в блокнот вместо <токен> и выполняем в консоли на клиенте (на винде это будет Git Bash, вероятно, или консоль в IDE). На выходе будет длинный код который нужно скопировать обратно в поле ввода в админке Gitea. При каждой попытке верификации токен разный, так что если не успели или словили ошибки нужно будет получить новый токен и сгенерировать новый код.

Как только ключ добавлен и верифицирован, его уже можно проверить.

Первичная проверка ключа

Для первичной проверки корректности настроек репозиторий нам не нужен. Достаточно подключиться к серверу по SSH в духе:

ssh -T git@git.coders-teaparty.cafe -p <порт>

где git это пользователь, а git.coders-teaparty.cafe — сервер. Очевидно, пользователь git не может выполнять команд, но может установить SSH-соединение, и факта успешной установки SSH-соединения нам достаточно.

В выводе должно мелькать сообщение:

Hi there, <username>! You’ve successfully authenticated with the key named <имя ключа>, but Gitea does not provide shell access.

Если git всё равно просит пароль или выдаёт ошибки, нужно подключиться с ключом -v (подробный вывод) и почитать этапы выполнения команды:

ssh -vT git@git.coders-teaparty.cafe -p <порт>

Например — ошибка Error: Permission denied (publickey) с хорошим шансом значит, что ключ не найден — например вы используете нестандартное имя файла ключа, которого нет в конфиге, или ключ не в той папке, в которой SSH-клиент его ищет. Внимательно ищите опечатки, убедитесь, что ключ действительно там, где надо, убедитесь в корректности remote. SSH штука довольно капризная, но это цена безопасности. Внимательно читаем вывод команды выше и отлаживаем. Очень помогают руководства зловредных корпоратов.

Использование

Важно всегда помнить указывать в git remote адрес SSH, а не HTTPS:

В старых репах remote можно обновить командой:

git remote set-url origin <NEW_GIT_URL_HERE>

Полезные ссылки

Больше руководств — не меньше руководств:

1. Об отладке SSH в вики Gitea
2. Как сменить remote репозитория (Stack Overflow)
3. Руководства зловредных корпоратов (отдельной ссылкой)
4. Похожее руководство, есть ещё полезные команды