SSHキーを使ってGitLabと通信します。

Git はディストリビューション・バージョン管理システムです。つまり、ローカルで作業して、その変更をサーバーに共有したりプッシュしたりすることができます。この場合、プッシュ先のサーバーはGitLabです。

GitLabはSSHプロトコルを使ってGitとセキュアに通信します。SSHキーでGitLabのリモートサーバーを認証すれば、毎回ユーザー名とパスワードを入力する必要はありません。

SSHキーとは？

SSH では公開鍵と秘密鍵の二つの鍵を使います。

  • 公開鍵はディストリビューションできます。
  • 秘密鍵は保護されるべきです。

公開鍵をアップロードすることで機密データを公開することはできません。SSH 公開鍵をコピーしたりアップロードしたりする必要があるときは、 誤って秘密鍵をコピーしたりアップロードしたりしないように注意してください。

秘密鍵を使ってコミットに署名することで、GitLabの利用やデータのセキュリティがさらに高まります。この署名は、公開鍵を使って誰でも検証することができます。

詳しくは、公開鍵暗号としても知られる非対称暗号をご覧ください。

前提条件

SSHを使ってGitLabと通信するには、以下のものが必要です：

  • GNU/Linux、MacOS、Windows 10にプリインストールされているOpenSSHクライアント。
  • SSHのバージョンは6.5以降。それ以前のバージョンはMD5署名を使用しており、セキュリティではありません。

システムにインストールされている SSH のバージョンを表示するには、ssh -V を実行してください。

サポートされているSSHキーの種類

GitLabと通信するために、以下のSSHキータイプを使用することができます：

管理者は、許可する鍵とその最小長を制限することができます。

ED25519 SSHキー

Practical Cryptography With Goという本によると、ED25519鍵は RSA 鍵よりもセキュリティと性能が高いそうです。

OpenSSH 6.5 では 2014 年に ED25519 SSH キーが導入されました。

ED25519_SK SSH キー

GitLab 14.8で導入されました。

GitLabでED25519_SK SSHキーを使用するには、ローカルクライアントとGitLabサーバーにOpenSSH 8.2以降がインストールされている必要があります。

ECDSA_SK SSHキー

GitLab 14.8で導入されました。

GitLab で ECDSA_SK SSH キーを使用するには、ローカルクライアントと GitLab サーバーにOpenSSH 8.2以降がインストールされている必要があります。

RSA SSHキー

GitLab 16.3でRSAキーの最大長を変更しました。

利用可能なドキュメントによると、ED25519はRSAよりもセキュリティが高いようです。

RSA 鍵を使用する場合、米国国立標準技術研究所の公開資料 800-57 Part 3(PDF)では、少なくとも 2048 ビットの鍵サイズを推奨しています。Goの制限により、RSA鍵は8192ビットを超えることはできません。

デフォルトの鍵サイズは、ssh-keygen のバージョンによって異なります。詳細については、インストールされているssh-keygen コマンドのman ページをレビューしてください。

既存の SSH キー・ペアがあるかどうか確認してください。

キー・ペアを作成する前に、キー・ペアがすでに存在するかどうかを確認します。

  1. ホーム・ディレクトリに移動します。
  2. .ssh/ サブディレクトリに .ssh/移動します。サブ.ssh/ ディレクトリが .ssh/存在しない場合は、ホームディレクトリにいないか、ssh を使ったことがないかのどちらかです。後者の場合、SSHキーペアを生成する必要があります。

  3. 以下のいずれかの形式のファイルが存在するか確認してください：

    アルゴリズム公開鍵秘密鍵
    ED25519（推奨）id_ed25519.pubid_ed25519
    ED25519_SKid_ed25519_sk.pubid_ed25519_sk
    ECDSA_SKid_ecdsa_sk.pubid_ecdsa_sk
    RSA（少なくとも2048ビットの鍵サイズ）id_rsa.pubid_rsa
    DSA（非推奨）id_dsa.pubid_dsa
    ECDSAid_ecdsa.pubid_ecdsa

SSHキーペアの生成

既存のSSHキー・ペアをお持ちでない場合は、新しいSSHキー・ペアを生成してください：

  1. ターミナルを開きます。

  2. ssh-keygen -t を実行し、キーの種類とオプションのコメントを入力します。このコメントは、作成される.pub ファイルの内部に含まれます。コメントにはメールアドレスを使用するとよいでしょう。

    例えば、ED25519の場合：

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

    2048ビットRSAの場合：

    ssh-keygen -t rsa -b 2048 -C "<comment>"

  3. Enterを押します。次のような出力が表示されます：

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

  4. デプロイ鍵を生成する場合や、他の鍵を保存する特定のディレクトリに保存する場合を除 き、提案されたファイル名とディレクトリを受け入れます。

    SSH キーペアを特定のホストに割り当てることもできます。

  5. パスフレーズを指定します：

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

    ファイルの保存場所に関する情報を含む確認が表示されます。

公開鍵と秘密鍵が生成されます。公開SSHキーをGitLabアカウントに追加し、秘密鍵は安全に保管してください。

SSH が別のディレクトリを指すように設定します。

SSHキー・ペアをデフォルト・ディレクトリに保存していない場合は、SSHクライアントが秘密鍵を保存しているディレクトリを指すように設定します。

  1. ターミナルを開き、次のコマンドを実行してください：

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

  2. これらの設定を~/.ssh/config ファイルに保存します。例えば

    # 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 設定マニュアルのman ssh_config ページを参照してください。

公開SSHキーはあなたのアカウントにバインドされるため、GitLabに固有でなければなりません。SSHキーは、SSHでコードをプッシュするときに持つ唯一の識別子です。それは一意に単一のユーザーにマップされなければなりません。

SSHキーのパスフレーズを更新してください。

SSHキーのパスフレーズを更新することができます：

  1. ターミナルを開き、次のコマンドを実行してください：

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

  2. プロンプトでパスフレーズを入力し、Enter.

RSAキー・ペアをよりセキュリティの高い形式にアップグレードします。

OpenSSH のバージョンが 6.5 から 7.8 までの場合は、 RSA SSH の秘密鍵をより安全な OpenSSH 形式で保存することができます：

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

あるいは、以下のコマンドで、より安全な暗号化形式で新しい RSA 鍵を生成することもできます：

ssh-keygen -o -t rsa -b 4096 -C "<comment>"

FIDO2ハードウェアセキュリティキー用のSSHキーペアの生成

ED25519_SK または ECDSA_SK SSH キーを生成するには、OpenSSH 8.2 以降を使用する必要があります：

  1. ハードウェア・セキュリティ・キーをコンピュータに挿入します。
  2. ターミナルを開きます。

  3. ssh-keygen -t を実行し、キーの種類とオプションのコメントを入力します。このコメントは、作成される.pub ファイルの内部に含まれます。コメントにはメールアドレスを使用するとよいでしょう。

    例えば、ED25519_SKの場合：

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

    ECDSA_SKの場合：

    ssh-keygen -t ecdsa-sk -C "<comment>"

    セキュリティキーが FIDO2 の常駐キーをサポートしている場合、SSH キーを作成するときにこれを有効にできます：

    ssh-keygen -t ed25519-sk -O resident -C "<comment>"

    -O resident は、鍵が FIDO 認証機自体に保存されていることを示します。常駐鍵はセキュリティキーからssh-add -K またはssh-keygen -Kで直接読み込むことができるため、新しいコンピュータへのインポートが簡単です。

  4. Enterを押します。次のような出力が表示されます：

    Generating public/private ed25519-sk key pair.
You may need to touch your authenticator to authorize key generation.

  5. ハードウェア・セキュリティ・キーのボタンをタッチします。

  6. 提案されたファイル名とディレクトリを受け入れます：

    Enter file in which to save the key (/home/user/.ssh/id_ed25519_sk):

  7. パスフレーズを指定します：

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

    ファイルの保存場所に関する情報を含む確認が表示されます。

公開鍵と秘密鍵が生成されます。公開SSHキーをGitLabアカウントに追加します。

パスワードマネージャーを使ってSSHキーペアを生成します。

1PasswordでSSHキーペアを生成

1Passwordと 1Passwordブラウザ拡張機能を使って、以下のことができます：

  • 新しいSSHキーを自動的に生成します。
  • GitLabで認証するために、1Password保管庫にある既存のSSHを使用します。
  1. GitLab にサインインします。
  2. 左のサイドバーで、自分のアバターを選択してください。
  3. プロフィールの編集を選択します。
  4. 左側のサイドバーで、SSHキーを選択します。
  5. キーを選択すると、1Passwordヘルパーが表示されます。
  6. 1Passwordアイコンを選択し、1Passwordのロックを解除します。
  7. その後、SSHキーの作成を選択するか、既存のSSHキーを選択して公開キーを入力します。
  8. タイトル] ボックスに、Work Laptop またはHome Workstation のような説明を入力します。
  9. オプション。キーの「Usage Type（使用法）」を選択します。これは、Authentication またはSigning のいずれか、または両方に使用できます。Authentication & Signing がデフォルト値です。
  10. オプション。デフォルトの有効期限を変更するには、[UpdateExpiration date (有効期限の更新)] を選択します。
  11. Add keyを選択します。

SSHキーで1Passwordを使用する詳細については、1Passwordのドキュメントを参照してください。

GitLabアカウントにSSHキーを追加します。

  • GitLab 15.4で導入された鍵の推奨されるデフォルトの有効期限。
  • GitLab 15.7で追加されたSSHキーの使用タイプ。

GitLabでSSHを使うには、公開鍵をGitLabアカウントにコピーしてください：

  1. 公開鍵ファイルの内容をコピーします。手動でもスクリプトでも構いません。例えば、ED25519鍵をクリップボードにコピーする場合：

    MacOS

    tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

    Linux(xclip パッケージが必要)

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

    WindowsのGit Bash

    cat ~/.ssh/id_ed25519.pub | clip

    id_ed25519.pub をファイル名に置き換えてください。例えば、RSAにはid_rsa.pub 。

  2. GitLab にサインインします。
  3. 左のサイドバーで、自分のアバターを選択してください。
  4. プロフィールの編集を選択します。
  5. 左側のサイドバーで、SSHキーを選択します。
  6. Add new keyを選択します。
  7. 鍵」ボックスに、公開鍵の内容を貼り付けます。手動で鍵をコピーした場合は、ssh-rsa 、ssh-dss 、ecdsa-sha2-nistp256 、ecdsa-sha2-nistp384、ecdsa-sha2-nistp521、ssh-ed25519、sk-ecdsa-sha2-nistp256@openssh.com、sk-ssh-ed25519@openssh.comで始まり、コメントで終わる鍵全体をコピーしてください。
  8. タイトル] ボックスに、Work Laptop またはHome Workstation のような説明を入力します。
  9. オプション。キーの「Usage Type（使用法）」を選択します。これは、Authentication またはSigning のいずれか、または両方に使用できます。Authentication & Signing がデフォルト値です。
  10. オプション。デフォルトの有効期限を変更するには、[UpdateExpiration date (有効期限の更新)] を選択します。で指定します：
    • GitLab 13.12以前では、有効期限は情報提供のみです。鍵の使用を妨げるものではありません。管理者は有効期限を見ることができ、鍵を削除する際の参考にすることができます。
    • GitLabは毎日午前2時（UTC）に全てのSSHキーをチェックします。現在の日付で期限切れになるSSHキーはすべて、メールで期限切れ通知を送ります。(GitLab 13.11で導入)。
    • GitLabは毎日01:00 AM UTCに全てのSSHキーをチェックします。7日後に期限切れとなるSSHキーの期限切れ通知をEメールで送信します。(GitLab 13.11で導入)。
  11. Add keyを選択します。

接続できることを確認します。

SSHキーが正しく追加されていることを確認してください。

以下のコマンドでは、ホスト名の例gitlab.example.com を使っています。この例のホスト名を、あなたの GitLab インスタンスのホスト名、例えばgit@gitlab.com に置き換えてください。

  1. 正しいサーバーに接続していることを確認するには、サーバーの SSH ホストキーのフィンガープリントをチェックしてください。例えば
    • GitLab.com の場合は、SSH host keys fingerprintsドキュメントを参照してください。
    • GitLab.comまたは他のGitLabインスタンス、gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints 。ここでgitlab.example.com はgitlab.com （GitLab.comの場合）またはGitLabインスタンスのアドレスです。

  2. ターミナルを開き、gitlab.example.com を GitLab インスタンスの URL に置き換えてこのコマンドを実行します：

    ssh -T git@gitlab.example.com

  3. 初めて接続する場合は、GitLabホストの信頼性を確認する必要があります。もしこのようなメッセージが表示されたら

    The authenticity of host 'gitlab.example.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.example.com' (ECDSA) to the list of known hosts.

    yes と入力し、Enterを押してください。

  4. もう一度ssh -T git@gitlab.example.com コマンドを実行します。Welcome to GitLab,@username! というメッセージが表示されるはずです。

歓迎メッセージが表示されない場合は、ssh を verbose モードで実行することでトラブルシューティングを行うことができます：

ssh -Tvvv git@gitlab.example.com

リポジトリごとに異なるキーを使用してください。

リポジトリごとに異なるキーを使用できます。

ターミナルを開き、次のコマンドを実行してください：

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

このコマンドはSSHエージェントを使わず、Git 2.10以降が必要です。ssh コマンドのオプションについての詳細は、ssh とssh_config のman のページを参照ください。

自分のアカウントのSSHキーを見る

  1. GitLab にサインインします。
  2. 左のサイドバーで、自分のアバターを選択してください。
  3. プロフィールの編集を選択します。
  4. 左側のサイドバーで、SSHキーを選択します。

既存のSSHキーがページ下部に一覧表示されます。情報には以下が含まれます：

  • 鍵の
    • 名前
    • 公開指紋
    • 有効期限
    • 許可された使用タイプ
  • 鍵が最後に使われた時間。GitLab.comではこの値は利用できず、SSHキーがいつ使われたかを確認することはできません。詳しくは、イシュー324764 をご覧ください。

SSHキーを完全に削除するには、Deleteを選択します。

一つのGitLabインスタンスで異なるアカウントを使用する場合

GitLab のひとつのインスタンスに複数のアカウントで接続することができます。これは、前のトピックのコマンドを使うことで可能です。ただし、IdentitiesOnly をyes に設定しても、Host ブロックの外部にIdentityFile が存在する場合はサインインできません。

代わりに、~/.ssh/config ファイルでホストにエイリアスを割り当てることができます。

  • Host にはuser_1.gitlab.com やuser_2.gitlab.com のようなエイリアスを使います。高度な設定はメンテナーが難しくなるので、これらの文字列はgit remote のようなツールを使うとわかりやすくなります。
  • IdentityFile には、秘密鍵のパスを使用します。
# 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>

user_1 用のリポジトリをクローンするには、git clone コマンドでuser_1.gitlab.com を使用します：

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

以前にクローンしたリポジトリのエイリアスを更新するには、origin ：

git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
note
秘密鍵と公開鍵には機密データが含まれています。ファイルの権限が、自分には読めるが他人にはアクセスできないものであることを確認してください。

二要素認証（2FA）の設定

SSH を使った Git の二要素認証 (2FA) を設定することができます。ED25519_SKあるいはECDSA_SKの SSH キーを使うことをお勧めします。

EclipseでEGitを使う

EGitを使用している場合、SSHキーをEclipseに追加することができます。

Microsoft WindowsでSSHを使う

Windows 10 を使っている場合は、git とssh の両方がプリインストールされているWSL 2でWindows Subsystem for Linux(WSL)を使うか、Git for Windowsをインストールして PowerShell で SSH を使うことができます。

WSLで生成されたSSHキーは、Git for Windowsでは直接利用できません：

  • どちらもホームディレクトリが異なるからです：/home/<user>
  • Git for Windows：C:\Users\<user>

.ssh/ ディレクトリをコピーして同じ鍵を使うか、環境ごとに鍵を生成します。

Windows 11 を使っていてOpenSSH for Windows を使っている場合は、HOME 環境変数が正しく設定されていることを確認してください。そうしないと、あなたのSSH秘密鍵が見つからないかもしれません。

代替ツールには以下があります：

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/user/ssh.md#overriding-ssh-settings-on-the-gitlab-server
  Please fix the error above and rerun the checks.

できるだけ早くカスタム設定を削除してください。これらのカスタマイズは明示的にサポートされておらず、いつ動かなくなるかわかりません。

トラブルシューティング

TLS：サーバーが8192ビットより大きいRSAキーを含む証明書を送信しました。

GitLab 16.3以降では、GoはRSAキーを最大8192ビットに制限しています。鍵の長さを確認するには

openssl rsa -in <your-key-file> -text -noout | grep "Key:"

8192ビットより長い鍵は、より短い鍵に置き換えてください。

パスワードプロンプトgit clone

git cloneを実行すると、git@gitlab.example.com's password: のようにパスワードの入力を求められることがあります。これはSSHの設定に何か問題があることを示しています。

  • SSHキー・ペアを正しく生成し、公開SSHキーをGitLabプロファイルに追加したことを確認してください。
  • ssh-agent を使って手動でSSH秘密鍵を登録してみてください。
  • ssh -Tv git@example.com を実行して接続をデバッグしてみてください。example.com を GitLab の URL に置き換えてください。
  • Use SSH on Microsoft Windows に書かれているすべての指示に従ったことを確認してください。

Could not resolve hostname エラー

接続できるかどうかを確認する際に、以下のエラーが表示される場合があります：

ssh: Could not resolve hostname gitlab.example.com: nodename nor servname provided, or not known

このエラーが表示された場合は、ターミナルを再起動してコマンドを再試行してください。

Key enrollment failed: invalid format エラー

FIDO2ハードウェアセキュリティキーのSSHキーペアを生成する際に、以下のエラーが発生する場合があります：

Key enrollment failed: invalid format

この場合、以下を試してトラブルシューティングを行うことができます：

  • sudo を使用してssh-keygen コマンドを実行します。
  • FIDO2 ハードウェアセキュリティキーが提供されたキータイプをサポートしていることを確認します。
  • ssh -Vを実行して、OpenSSHのバージョンが8.2以上であることを確認してください。