GitLab和SSH密钥

Git是一个分布式版本控制系统，这意味着您可以在本地工作。此外，您还可以将更改共享或“推送”到其他服务器。GitLab支持使用SSH密钥在Git及其服务器之间进行安全通信。

SSH协议提供了这种安全性，并允许您向GitLab远程服务器进行身份验证，而无需每次都提供用户名或密码。

该页面可帮助您配置安全的SSH密钥，可用于帮助保护与GitLab存储库的连接。

要求

为了支持SSH，GitLab需要安装OpenSSH客户端，该客户端已预安装在GNU / Linux和macOS上，但未预先安装在Windows上。

确保您的系统包括SSH 6.5或更高版本，因为它不包括现在不安全的MD5签名方案。以下命令返回系统上安装的SSH版本：

ssh -V

尽管GitLab不支持在Microsoft Windows上进行安装，但是您可以设置SSH密钥以将Windows设置为客户端。

SSH密钥选项

GitLab支持使用RSA，DSA，ECDSA和ED25519密钥。

提示：提示： 现有文档表明ED25519更安全。如果使用RSA密钥，则美国国家科学技术研究院在出版物800-57第3部分（PDF）中建议密钥大小至少为2048位。

因此，我们的文档着重于ED25519和RSA密钥的使用。

管理员可以限制应允许的密钥及其最小长度。

查看现有的SSH密钥

如果您已有SSH密钥，则可以使用它们来帮助保护与GitLab存储库的连接。默认情况下，Linux和macOS系统上的SSH密钥存储在用户主目录的.ssh/子目录中。下表包含每种SSH密钥算法的默认文件名：

算法公钥私钥
ED25519（首选）id_ed25519.pubid_ed25519
RSA（至少2048位密钥大小）id_rsa.pubid_rsa
DSA（已弃用）id_dsa.pubid_dsa
ECDSAid_ecdsa.pubid_ecdsa

有关建议，请参阅SSH密钥的选项。

生成新的SSH密钥对

如果要创建：

ED25519 SSH密钥

《Go实用密码学》一书 建议ED25519密钥比RSA密钥更安全，性能更高。

随着OpenSSH 6.5在2014年引入ED25519 SSH密钥，它们应该在任何当前操作系统上都可用。

您可以使用以下命令创建和配置ED25519密钥：

ssh-keygen -t ed25519 -C "<comment>"

该-C标志带有带引号的注释，例如电子邮件地址，是标记SSH密钥的一种可选方式。

您将看到类似于以下内容的响应：

Generating public/private ed25519 key pair. Enter file in which to save the key (/home/user/.ssh/id_ed25519):

要获得指导，请继续执行常见步骤。

RSA SSH密钥

如果您将RSA密钥用于SSH，则美国国家标准技术研究院建议您使用至少2048位的密钥大小。默认情况下，该ssh-keygen命令创建一个1024位RSA密钥。

您可以使用以下命令创建和配置RSA密钥，如果需要的话，可以使用建议的最小密钥大小替换2048：

ssh-keygen -t rsa -b 2048 -C "email@example.com"

该-C标志带有带引号的注释，例如电子邮件地址，是标记SSH密钥的一种可选方式。

您将看到类似于以下内容的响应：

Generating public/private rsa key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa):

要获得指导，请继续执行常见步骤。

注意：注意： 如果您具有OpenSSH 7.8或更低版本，请考虑与encoding相关的问题。

生成SSH密钥对的常见步骤

无论是创建ED25519还是创建RSA密钥，都已从ssh-keygen命令开始。此时，您将在命令行中看到以下消息（用于ED25519键）：

Generating public/private ed25519 key pair. Enter file in which to save the key (/home/user/.ssh/id_ed25519):

如果您还没有SSH密钥对并且没有生成部署密钥，请接受建议的文件和目录。您的SSH客户端无需额外配置即可使用生成的SSH密钥对。

或者，您可以将新的SSH密钥对保存在其他位置。您可以分配您选择的目录和文件名。您还可以将SSH密钥对专用于特定主机。

分配文件以保存SSH密钥后，您可以为SSH密钥设置密码：

Enter passphrase (empty for no passphrase): Enter same passphrase again:

如果成功，您将看到ssh-keygen命令保存您的标识和私钥的位置的确认。

需要时，可以使用以下命令更新密码：

ssh-keygen -p -f /path/to/ssh_key

6.5至7.8版的RSA密钥和OpenSSH

在OpenSSH 7.8之前，RSA密钥的默认公共密钥指纹基于MD5，因此不安全。

如果您的OpenSSH版本介于6.5至7.8（含）之间，请运行ssh-keygen该-o选项，以更安全的OpenSSH格式保存您的私有SSH密钥。

如果您已经具有可用于GitLab的RSA SSH密钥对，请考虑对其进行升级以使用更安全的密码加密格式。您可以使用以下命令进行操作：

ssh-keygen -o -f ~/.ssh/id_rsa

或者，您可以使用以下命令以更安全的加密格式生成新的RSA密钥：

ssh-keygen -o -t rsa -b 4096 -C "email@example.com"

注意：注意： 如ssh-keygen手册页所述，ED25519已经将密钥加密为更安全的OpenSSH格式。

将SSH密钥添加到您的GitLab帐户

现在，您可以将创建的SSH密钥复制到您的GitLab帐户。这样做，请按照下列步骤操作：

  1. 将您的公共SSH密钥复制到以文本格式保存信息的位置。以下选项将ED25519键的信息保存到指定操作系统的剪贴板中：

    苹果系统：

    pbcopy < ~/.ssh/id_ed25519.pub

    Linux（需要xclip软件包）：

    xclip -sel clip < ~/.ssh/id_ed25519.pub

    Windows上的Git Bash：

    cat ~/.ssh/id_ed25519.pub | clip

    如果您使用的是RSA密钥，请相应地进行替换。

  2. 导航https://gitlab.com并登录。

  3. 选择右上角的头像，然后单击设置

  4. 单击“ SSH密钥”。

  5. 将复制的公共密钥粘贴到“密钥”文本框中。

  6. 确保您的密钥在“标题”文本框中包含描述性名称，例如“工作笔记本电脑”或“ 家用工作站”。

  7. 在“到期时间”部分下包含密钥的（可选）到期日期。（在GitLab 12.9中引入。）

  8. 单击添加键按钮。

使用此过程“过期”的SSH密钥在GitLab工作流程中有效。由于GitLab配置的到期日期不包含在SSH密钥本身中，因此您仍然可以根据需要导出公共SSH密钥。

注意：注意： 如果您手动复制了公共SSH密钥，请确保复制了整个密钥ssh-ed25519（以（或ssh-rsa）开头，以电子邮件地址结尾）。

测试所有设置是否正确

要测试是否正确添加了SSH密钥，请在终端中运行以下命令（替换gitlab.com为GitLab的实例域）：

ssh -T git@gitlab.com

首次通过SSH连接到GitLab时，应验证所连接的GitLab主机的真实性。例如，当连接到GitLab.com时，请回答yes将GitLab.com添加到受信任主机的列表中：

The authenticity of host 'gitlab.com (35.231.145.151)' can't be established. ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts.

注意：注意： 对于GitLab.com，请查阅 SSH主机密钥指纹一节，以确保您连接到正确的服务器。例如，您可以在链接的部分中看到上面显示的ECDSA密钥指纹。

一旦添加到已知主机列表中，您应该再次验证GitLab主机的真实性。再次运行以上命令，您应该只会收到一个欢迎使用GitLab的信息@username！信息。

如果未出现欢迎消息，则可以通过ssh 使用以下命令在详细模式下运行来解决问题：

ssh -Tvvv git@gitlab.com

使用非默认SSH密钥对路径

如果您为GitLab SSH密钥对使用了非默认文件路径，则将SSH客户端配置为指向GitLab私有SSH密钥。

要进行这些更改，请运行以下命令：

eval $(ssh-agent -s) ssh-add <path to private SSH key>

现在将这些设置保存到~/.ssh/config文件中。这里显示了两个专用于GitLab的SSH密钥示例：

# GitLab.com Host gitlab.com   Preferredauthentications publickey   IdentityFile ~/.ssh/gitlab_com_rsa  # Private GitLab instance Host gitlab.company.com   Preferredauthentications publickey   IdentityFile ~/.ssh/example_com_rsa

公用SSH密钥必须绑定到您的帐户，因此对于GitLab来说必须是唯一的。SSH密钥是通过SSH推送代码时唯一的标识符，这就是为什么它需要唯一地映射到单个用户的原因。

每个存储库SSH密钥

如果要根据正在使用的存储库使用不同的密钥，则可以在存储库中发出以下命令：

git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"

它不使用SSH代理，并且至少需要Git 2.10。

一个GitLab实例上有多个帐户

在每个仓库的方法也适用于单个GitLab实例中使用多个帐户。

另外，也可以直接为中的主机分配别名 ~.ssh/config。SSH和（如果有扩展名的话）Git无法登录，如果Git中IdentityFile的某个Host块之外没有设置.ssh/config。这是由于SSH组装IdentityFile条目的方式，因此无法通过设置IdentitiesOnly为来更改yes。IdentityFile条目应指向SSH密钥对的私钥。

注意：注意： 私钥和公用密钥应仅由用户读取。通过运行做到这一点对Linux和MacOS：chmod 0400 ~/.ssh/<example_ssh_key>和 chmod 0400 ~/.ssh/<example_sh_key.pub>。

# User1 Account Identity Host <user_1.gitlab.com>   Hostname gitlab.com   PreferredAuthentications publickey   IdentityFile ~/.ssh/<example_ssh_key1>  # User2 Account Identity Host <user_2.gitlab.com>   Hostname gitlab.com   PreferredAuthentications publickey   IdentityFile ~/.ssh/<example_ssh_key2>

注意：注意： 示例Host别名被定义为user_1.gitlab.com和， user_2.gitlab.com以提高效率和透明度。高级配置更难以维护。使用此类别名使使用其他工具（如git remote子命令）时更容易理解。SSH因此可以将任何字符串理解为Host别名，Tanuki1并且Tanuki2尽管很少提供有关它们指向的上下文，但它也可以使用。

克隆gitlab存储库通常如下所示：

git clone git@gitlab.com:gitlab-org/gitlab.git

要为其克隆user_1，请替换gitlab.com为SSH别名user_1.gitlab.com：

git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git

使用git remote命令修复先前克隆的存储库。

以下示例假定远程存储库的别名为origin。

git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git

部署密钥

阅读有关部署密钥的文档。

应用领域

蚀

如果使用的是EGit，则可以将SSH密钥添加到Eclipse。

GitLab服务器上的SSH

GitLab与系统安装的SSH守护程序集成，指定一个用户（通常名为git）来处理所有访问请求。通过SSH连接到GitLab服务器的用户由其SSH密钥而不是其用户名标识。

在GitLab服务器上执行的SSH客户端操作以该用户身份执行。尽管可以修改此用户的SSH配置，例如，提供一个私有SSH密钥来验证这些请求，但是这种做法不受支持，并且强烈建议这样做，因为这样做会带来严重的安全风险。

GitLab检查过程包括对这种情况的检查，并且如果您的服务器配置如下，则将您定向到本节，例如：

$ gitlab-rake gitlab:check  Git user has default SSH configuration? ... no   Try fixing it:   mkdir ~/gitlab-check-backup-1504540051   sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051   sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051   For more information see:   doc/ssh/README.md in section "SSH on the GitLab server"   Please fix the error above and rerun the checks.

尽快删除自定义配置。这些自定义项明确不受支持，并且可能随时停止工作。

Microsoft Windows的选项

如果您运行的是Windows 10，适用于Linux的Windows子系统（WSL）及其最新的WSL 2版本，则支持安装不同的Linux发行版，其中包括Git和SSH客户端。

对于当前版本的Windows，您还可以通过Git for Windows安装Git和SSH客户端 。

替代工具包括：

故障排除

如果在Git克隆上，系统会提示您输入密码，例如git@gitlab.com's password: SSH设置有问题。

  • 确保您正确生成了SSH密钥对，并将公共SSH密钥添加到了GitLab配置文件

  • 尝试使用ssh-agent本文档前面所述的方法手动注册私有SSH密钥

  • 尝试通过运行来调试连接ssh -Tv git@example.com （替换example.com您的GitLab域）





注意：

测试使用

ssh -T git@pandatv.com

非22端口(如2222)使用下面的命令测试

ssh -Tvvv  -p2222  git@pandatv.com

本地设置

cat>~/.ssh/config

Host gitlab.xxx.com  //此处是你的项目访问

hostUser git   //用户名称

Port 2222   //自定义端口

IdentityFile /home/yourname/.ssh/id_rsa //你的id_rsa路径