---

GitLab SSHキーを簡単に登録！安全・快適な接続設定マニュアル

はじめに：GitLabとSSHキーについて

GitLabとは？

GitLabは、ソフトウェア開発プロジェクトのバージョン管理、ソースコード管理、CI/CD (継続的インテグレーション/継続的デリバリー)、課題管理、Wiki機能などを統合的に提供するWebベースのDevOpsプラットフォームです。個人開発から大企業のチーム開発まで、幅広く利用されています。

GitLabでコードを管理するには、ローカル環境のGitクライアントとGitLabサーバー間で通信を行う必要があります。この通信方法には主にHTTPSとSSHの2種類があります。

なぜSSHキーを使うのか？ HTTPSとの比較

コードをGitLabサーバーにプッシュしたり、サーバーから取得（プル/クローン）したりする際に、認証が必要になります。

• HTTPS:

  • 通常、ユーザー名とパスワード（またはパーソナルアクセストークン）を使って認証を行います。
  • 設定が比較的簡単で、ファイアウォールなどの制約を受けにくいというメリットがあります。
  • しかし、操作のたびにパスワード（またはトークン）の入力を求められる場合があり、特に二要素認証を有効にしている場合は煩雑になることがあります。また、パスワードを扱うため、フィッシングなどによる漏洩のリスクも存在します。

• SSH (Secure Shell):

  • 公開鍵暗号方式を用いたキーペア（公開鍵と秘密鍵）を使って認証を行います。
  • 一度設定してしまえば、以降のGit操作（プッシュ、プルなど）においてパスワード入力を求められることなく、安全に通信できます。これは、セキュリティと利便性を両立する優れた方法です。
  • 初期設定の手間はHTTPSよりかかりますが、開発ワークフローの効率を大幅に向上させることができます。

この記事では、このSSH接続をGitLabで利用するためのSSHキーの生成方法から、GitLabへの登録、そして実際の接続確認・操作方法までを、初心者の方でも迷わず行えるように、詳細かつ丁寧に解説します。

この記事の目的

この記事は、GitLabをSSHで利用したいすべての方を対象としています。

• SSHキーとは何か？
• SSHキーの生成方法（Windows, macOS, Linux共通のコマンドを中心に）
• 生成した公開鍵をGitLabに登録する方法
• SSH接続が正しく機能しているかの確認方法
• SSH接続を使ったGit操作
• 複数のSSHキーを使い分ける高度な設定
• SSHエージェントを利用してパスフレーズの手間を省く方法
• SSHキーの管理とセキュリティに関する注意点
• よくあるトラブルとその解決方法

これらの内容を網羅することで、GitLabでの開発環境をより安全かつ効率的に構築できるようになることを目指します。

約5000語の詳細な解説を通じて、SSHキーを使ったGitLab接続設定のすべてをマスターしましょう。

1. SSHキーの基本理解

SSHキーを使った認証は、公開鍵暗号方式に基づいています。この方式では、「公開鍵」と「秘密鍵」というペアの鍵を使用します。

1.1 公開鍵と秘密鍵のペア

• 秘密鍵 (Private Key): あなただけが知っている、あるいは持っているべき鍵です。この鍵は絶対に他人に知られてはいけません。通常、あなたのコンピュータ上にファイルとして保存されます。
• 公開鍵 (Public Key): 秘密鍵とペアになって生成される鍵で、誰にでも公開しても安全な鍵です。この鍵を、認証を受けたいサーバー（今回の場合はGitLab）に登録します。

この2つの鍵は数学的に関連付けられており、「公開鍵で暗号化されたデータは、ペアとなる秘密鍵でのみ復号できる」「秘密鍵で署名されたデータは、ペアとなる公開鍵でその署名が正しいことを検証できる」という性質を持ちます。

1.2 SSHキーを使った認証の流れ

GitLabにSSHで接続する場合、認証は以下の流れで行われます。

1. 接続要求: あなたのGitクライアント（ローカルコンピュータ）がGitLabサーバーにSSH接続を要求します。
2. 認証方式の提案: GitLabサーバーは、クライアントに対して利用可能な認証方式（パスワード認証、公開鍵認証など）を提案します。
3. 公開鍵認証の選択: クライアントは公開鍵認証を選択し、使用したい公開鍵の情報をサーバーに伝えます。
4. サーバー側の確認: GitLabサーバーは、クライアントから伝えられた公開鍵が、自分のデータベースに登録されている公開鍵の中に存在するかを確認します。
5. チャレンジ: サーバーは、その公開鍵の持ち主（クライアント）だけが応答できるような「チャレンジ（問いかけ）」を生成し、クライアントに送り返します。このチャレンジは通常、ランダムなデータを含み、クライアントの公開鍵に対応する秘密鍵で署名しないと正しく応答できません。
6. 秘密鍵による署名: クライアントは、受け取ったチャレンジデータを自分の秘密鍵で署名します。
7. 応答の送信: クライアントは署名済みの応答をサーバーに送り返します。
8. サーバー側の検証: GitLabサーバーは、クライアントから送られてきた応答を、自身が持つクライアントの公開鍵を使って検証します。
9. 認証成功/失敗: 検証が成功すれば、サーバーはクライアントの秘密鍵の持ち主であると判断し、認証成功となります。秘密鍵が一致しない場合や、署名が正しくない場合は認証失敗となります。

この一連の流れの中で、秘密鍵がネットワーク上を流れることはありません。公開鍵は公開されても安全であり、秘密鍵だけを安全に管理することで、高度なセキュリティを保ちながら認証を行うことができます。

1.3 GitLabとSSHキーの関係

GitLabは、あなたのユーザーアカウント設定の一部として、複数のSSH公開鍵を登録できます。GitLabサーバーは、接続してきたクライアントが提示する公開鍵が、いずれかのユーザーアカウントに登録されている公開鍵と一致するかをチェックします。一致した場合、そのユーザーとして認証が成功し、対応するプロジェクトへのアクセス権に基づいて操作（クローン、プル、プッシュなど）が可能になります。

したがって、SSHでGitLabに接続するためには、以下の2つのステップが必要です。

1. ローカルPCでSSHキーペア（公開鍵と秘密鍵）を生成する。
2. 生成した公開鍵をGitLabの自分のアカウントに登録する。

次のセクションから、これらの具体的な手順を解説していきます。

2. SSHキーの生成

SSHキーペア（公開鍵と秘密鍵）を生成するには、ssh-keygen というコマンドを使用します。このコマンドは、macOS、Linux、そしてWindows 10以降のPowerShellまたはWSL (Windows Subsystem for Linux) に標準で含まれているOpenSSHクライアントで利用できます。

2.1 ssh-keygen コマンドの実行

ターミナルまたはコマンドプロンプトを開き、以下のコマンドを入力して実行します。

bash
ssh-keygen -t ed25519 -C "[email protected]"

このコマンドの意味は以下の通りです。

• ssh-keygen: SSHキーペアを生成するためのコマンドです。
• -t ed25519: 生成するキーのタイプを指定します。ed25519 は比較的新しい方式ですが、より安全で高速であるため現在推奨されています。古いシステムとの互換性が必要な場合は rsa -b 4096 を使用することもできますが、特段の理由がなければ ed25519 が良いでしょう。
• -C "[email protected]": 生成される公開鍵ファイルにコメントを追加します。通常は自分のメールアドレスを設定しますが、必須ではありません。キーの識別に役立ちます。

コマンドを実行すると、いくつか質問が表示されます。

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

2.1.1 キーペアの保存場所

最初の質問は「キーペアをどこに保存するか」です。

Enter file in which to save the key (~/.ssh/id_ed25519):

括弧 () 内に表示されているのはデフォルトの保存場所とファイル名です。
* ~: これはユーザーのホームディレクトリを表します（Windowsの場合は C:\Users\YourUsername、macOS/Linuxの場合は /home/yourusername または /Users/yourusername）。
* .ssh: ホームディレクトリの直下にある隠しディレクトリです。SSH関連の設定ファイルやキーは通常このディレクトリに保存されます。
* id_ed25519: 生成される秘密鍵のデフォルトのファイル名です。公開鍵はこれに .pub が付いた id_ed25519.pub となります。

特に理由がなければ、デフォルトの場所とファイル名で問題ありません。Enterキーを押して、デフォルトを受け入れます。

もし、すでに同じ名前のファイルが存在する場合（以前にSSHキーを生成したことがある場合）、上書きするかどうかを尋ねられます。

~/.ssh/id_ed25519 already exists.
Overwrite (y/n)?

既存のキーを上書きすると、以前そのキーを使っていたサービスへの接続ができなくなります。通常は「n」を入力して上書きを避け、別のファイル名を指定して新しいキーを生成するのが良いでしょう。別のファイル名を指定する場合は、例えば ~/.ssh/id_ed25519_gitlab のように入力します。

2.1.2 パスフレーズの設定

次にパスフレーズの設定を求められます。

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

• Enter passphrase (empty for no passphrase):: 秘密鍵を使用する際にパスフレーズの入力を求めるかどうかを設定します。パスフレーズを設定すると、秘密鍵が漏洩した場合でも、パスフレーズを知らなければ不正に使用されるリスクを軽減できます。セキュリティを高めるために、パスフレーズを設定することを強く推奨します。パスフレーズは、GitLabアカウントのパスワードとは異なるものを設定してください。画面には入力したパスフレーズは表示されませんが、そのまま入力してEnterキーを押します。
• Enter same passphrase again:: 確認のため、もう一度同じパスフレーズを入力します。

パスフレーズを設定しない場合は、何も入力せずにEnterキーを2回押します。パスフレーズなしのキーは、秘密鍵が漏洩すると誰でも簡単に利用できてしまうため、非推奨です。ただし、自動化されたスクリプトなどでパスフレーズの入力を回避したい場合など、特別な事情がある場合は選択肢となり得ます。

パスフレーズの設定または省略が完了すると、キーペアの生成が終了します。

Your identification has been saved in ~/.ssh/id_ed25519
Your public key has been saved in ~/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:........................................... [email protected]
The key's randomart image is:
+--[ED25519 256]--+
| . =+*BO. |
| . +.*.= |
| o +.+o |
| + *.. |
| E S + |
| . . + . |
| . . . |
| . |
| |
+----[SHA256]-----+

Your identification has been saved in ... で秘密鍵の保存場所、Your public key has been saved in ... で公開鍵の保存場所が表示されます。
「key fingerprint」は、公開鍵を短くハッシュ化したもので、公開鍵が正しいものであるかを確認する際に利用されます。

2.2 生成されたファイルの確認

SSHキーペアが正しく生成されたかを確認してみましょう。デフォルトの保存場所 (~/.ssh/) を見てみます。

ターミナルで以下のコマンドを実行します。

bash
ls -l ~/.ssh/

生成されたキーペアファイルが表示されるはずです。例えば、ED25519キーをデフォルト名で生成した場合：

-rw------- 1 yourusername staff 411 Mar 10 10:30 id_ed25519
-rw-r--r-- 1 yourusername staff 96 Mar 10 10:30 id_ed25519.pub

ファイル名の説明：
* id_ed25519: これが秘密鍵ファイルです。拡張子はありません。
* id_ed25519.pub: これが公開鍵ファイルです。.pub という拡張子が付いています。

パーミッション（ファイル名の前にある -rw------- や -rw-r--r--）にも注目してください。
* 秘密鍵 (id_ed25519) のパーミッションは -rw------- となっているはずです。これは「所有者（あなた）のみ読み書き可能、他のユーザーは一切不可」を意味します。秘密鍵は非常に重要な情報なので、このように厳重なパーミッションになっていることを確認してください。もしこれ以外のパーミッションになっている場合は、chmod 600 ~/.ssh/id_ed25519 コマンドで修正してください。
* 公開鍵 (id_ed25519.pub) のパーミッションは -rw-r--r-- となっているはずです。これは「所有者読み書き可能、他のユーザーは読み取り可能」を意味します。公開鍵は公開しても安全なので、このパーミッションで問題ありません。

2.3 公開鍵ファイルの確認

GitLabに登録するのは、この公開鍵ファイル (.pub 拡張子が付いている方) の中身です。公開鍵ファイルの中身を確認してみましょう。

bash
cat ~/.ssh/id_ed25519.pub

実行すると、以下のような文字列が表示されます。

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOm+6zF7Q2x...xXkXy+rYt [email protected]

この ssh-ed25519 から始まり、[email protected] (または指定したコメント) までを含む文字列全体が、あなたの公開鍵です。GitLabに登録するのは、まさにこの文字列です。

これでSSHキーペアの生成は完了です。次に、この公開鍵をGitLabに登録する手順に進みます。

3. GitLabへの公開鍵登録

生成した公開鍵（.pub ファイルの中身）を、あなたのGitLabアカウントに登録します。

3.1 GitLabへのログイン

ウェブブラウザでGitLabのサイト（gitlab.com、または所属組織のGitLabインスタンスのURL）にアクセスし、あなたのユーザーアカウントでログインします。

3.2 ユーザー設定画面への移動

ログイン後、画面右上に表示されているあなたのユーザーアイコンをクリックします。ドロップダウンメニューが表示されるので、「Settings」（設定）を選択します。

（参考画像：GitLab公式ドキュメントより）

3.3 SSH Keys 設定画面への移動

左側のサイドバーメニューが表示されます。その中の「SSH Keys」を選択します。

（参考画像：GitLab公式ドキュメントより）

3.4 新しいSSHキーの追加

「SSH Keys」画面には、現在登録されているSSHキーの一覧が表示されます。初めての場合は何も表示されないかもしれません。

新しいキーを登録するために、「Add new key」（または類似のボタン/リンク）をクリックします。

（参考画像：GitLab公式ドキュメントより）

新しいキーを追加するためのフォームが表示されます。ここには通常、以下のフィールドがあります。

• Key: ここに、先ほど生成した公開鍵ファイル (.pub ファイル) の中身全体を貼り付けます。
• Title: このSSHキーを識別するための任意のタイトル（名前）を設定します。例えば、「My Laptop ED25519 Key」、「Work PC SSH Key」のように、どの端末のどのキーか分かるように設定しておくと、後々管理しやすくなります。通常、Keyフィールドに公開鍵を貼り付けると、公開鍵のコメント部分（ssh-keygen -C で指定したもの）が自動的にTitleとして入力されますが、必要に応じて編集できます。
• Expires at (オプション): このSSHキーの有効期限を設定できます。セキュリティ上の理由から、定期的にキーを交換することを推奨されている環境では、有効期限を設定しておくと管理が容易になります。必須ではありません。

3.5 公開鍵の内容を貼り付け

先ほど cat ~/.ssh/id_ed25519.pub コマンドで表示させた公開鍵の文字列をコピーし、GitLabの「Key」フィールドに貼り付けます。

公開鍵の文字列をコピーするには、以下のいずれかの方法が便利です（OSによってコマンドが異なります）。

macOS:

bash
pbcopy < ~/.ssh/id_ed25519.pub

このコマンドを実行すると、~/.ssh/id_ed25519.pub ファイルの内容がmacOSのクリップボードにコピーされます。

Linux (xclip または xsel がインストールされている場合):

• xclip を使用する場合:
  bash
xclip -sel clip < ~/.ssh/id_ed25519.pub
• xsel を使用する場合:
  bash
xsel --clipboard < ~/.ssh/id_ed25519.pub
  これらのコマンドを実行すると、公開鍵の内容がLinuxのクリップボードにコピーされます。xclipやxselがインストールされていない場合は、お使いのディストリビューションのパッケージマネージャーでインストールしてください (例: sudo apt-get install xclip または sudo yum install xclip)。

Windows (PowerShell):

powershell
Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard

このコマンドを実行すると、~/.ssh/id_ed25519.pub ファイルの内容がWindowsのクリップボードにコピーされます。

Windows (コマンドプロンプト):

cmd
type %USERPROFILE%\.ssh\id_ed25519.pub | clip

このコマンドを実行すると、公開鍵の内容がWindowsのクリップボードにコピーされます。

手動でコピーする場合:

ターミナルに表示された公開鍵の文字列を、マウスで選択してコピー＆ペーストすることももちろん可能です。ただし、文字列が非常に長いため、忘れずに全体を選択・コピーするように注意してください。先頭の ssh-ed25519 (または ssh-rsa など) から末尾のコメントまで、すべてを含める必要があります。

コピーした公開鍵の文字列を、GitLabの「Key」フィールドに貼り付けます。

3.6 タイトルと有効期限の設定

「Title」フィールドには、キーを識別しやすい名前を入力します。自動入力されたタイトルで問題なければそのままでOKです。

必要に応じて、「Expires at」フィールドで有効期限を設定します。カレンダーピッカーが表示されるので、日付を選択します。

3.7 キーの追加と確認

すべてのフィールドの入力が完了したら、「Add key」ボタンをクリックします。

（参考画像：GitLab公式ドキュメントより）

画面が更新され、「SSH Keys」の一覧に今登録したキーが追加されていることが確認できます。ここには、登録したキーのTitle、フィンガープリント、作成日、そして最後に使用された日時などが表示されます。フィンガープリントは、ローカルで ssh-keygen -lf ~/.ssh/id_ed25519.pub のようにコマンドで確認できるフィンガープリントと一致するはずです。

これで、GitLabへの公開鍵の登録は完了です。あなたのローカルPCの秘密鍵と、GitLabに登録された公開鍵のペアを使って認証できるようになりました。

4. SSH接続の確認

SSHキーが正しく設定され、GitLabに接続できるかを確認しましょう。これは、GitLabのSSHサーバーに対して認証のみを試みるコマンドで簡単に行えます。

ターミナルまたはコマンドプロンプトを開き、以下のコマンドを実行します。

bash
ssh [email protected]

このコマンドは、ユーザー名 git として gitlab.com というホストにSSH接続を試みます。GitLabのSSHサーバーは、どのユーザーが接続してきたかをSSHキーによって識別するため、接続時のユーザー名は常に git となります。

4.1 初回接続時のフィンガープリント確認

gitlab.com に対して初めてSSH接続を行う場合、以下のようなメッセージが表示されます。

The authenticity of host 'gitlab.com (172.65.251.78)' can't be established.
ED25519 key fingerprint is SHA256:...........................................
Are you sure you want to continue connecting (yes/no, [fingerprint])?

これは、接続しようとしているホスト（gitlab.com）が本当に意図したサーバーであるかを確認するためのものです。表示されている「フィンガープリント (fingerprint)」が、公式なGitLabサーバーのフィンガープリントと一致するかを確認することが重要です。これにより、中間者攻撃（Man-in-the-Middle Attack）を防ぐことができます。

GitLabの公式なフィンガープリントは、GitLabの公式ドキュメントで確認できます。「GitLab SSH host fingerprint」などのキーワードで検索すると見つかります。表示されたフィンガープリントが公式のものと一致することを確認してください。

一致していれば、yes と入力してEnterキーを押します。

Warning: Permanently added 'gitlab.com' (ED25519) to the list of known hosts.

このメッセージが表示されれば、GitLabサーバーのホスト情報とフィンガープリントが ~/.ssh/known_hosts ファイルに保存されました。次回以降、同じサーバーに接続する際にはこの確認は表示されません。

4.2 認証成功メッセージ

フィンガープリントの確認後、SSHキーによる認証が試みられます。

• パスフレーズ付きの秘密鍵を使用している場合: SSHエージェントにキーが登録されていない場合は、秘密鍵のパスフレーズの入力を求められます。正確なパスフレーズを入力してEnterキーを押してください。
• パスフレーズなしの秘密鍵を使用している場合、またはSSHエージェントにキーが登録済みの秘密鍵を使用している場合: パスフレーズの入力はスキップされます。

認証に成功すると、以下のようなメッセージが表示されます。

Welcome to GitLab, @yourusername!

@yourusername の部分はあなたのGitLabユーザー名です。このメッセージが表示されれば、SSHキーを使ったGitLabへの接続認証は成功しています！

注意: この ssh [email protected] コマンドは認証の確認だけを行うものであり、シェルにログインするわけではありません。認証成功後、しばらくすると自動的に接続が閉じられ、元のターミナルに戻ります。

4.3 認証失敗の場合のトラブルシューティングの切り分け

もし認証が成功せず、以下のようなエラーメッセージが表示された場合は、SSH接続の設定に問題があります。

Permission denied (publickey).

このエラーは、GitLabサーバーがあなたの提示したSSH公開鍵を認証できなかったことを意味します。原因としては、いくつか考えられます。

• GitLabに公開鍵が登録されていない、または登録されている公開鍵が間違っている: GitLabのWeb UIで、あなたのユーザー設定の「SSH Keys」に公開鍵が正しく登録されているか再度確認してください。コピー＆ペースト時に公開鍵文字列の一部が欠けていないか、余計な空白や改行が入っていないかも重要です。
• ローカルの秘密鍵のパスが間違っている: SSHクライアントが使用しようとしている秘密鍵ファイルが、実際に存在するファイルと異なっている可能性があります。デフォルト以外のファイル名でキーを生成した場合や、複数のキーがある場合は、~/.ssh/config の設定を確認してください（後述）。
• 秘密鍵ファイルのパーミッションが厳密でない: 秘密鍵ファイル (~/.ssh/id_ed25519 など) のパーミッションが -rw------- (chmod 600) 以外になっていると、SSHクライアントがセキュリティ上の理由で使用を拒否することがあります。ls -l ~/.ssh/ でパーミッションを確認し、必要なら chmod 600 ~/.ssh/id_ed25519 のように修正してください。
• パスフレーズが間違っている: パスフレーズを求められているのに正しく入力できない場合。
• SSHエージェントの問題: SSHエージェントを使用している場合、エージェントが起動していないか、秘密鍵がエージェントに追加されていない可能性があります（後述）。

ssh コマンドに -v オプションを追加すると、デバッグ情報が表示され、問題の特定に役立ちます。

bash
ssh -v [email protected]

出力される詳細なログを確認し、「debug1: Authentications that can continue: publickey,keyboard-interactive」のような行や、どのキーを試行しているか (Trying private key: /path/to/your/key) といった情報から、どこで認証が失敗しているのか手がかりを得ることができます。

5. Gitリポジトリのクローンと操作 (SSH接続)

SSH接続による認証が確認できたら、実際にGitLab上のリポジトリをクローンしたり、プッシュ/プルしたりする操作をSSH経由で行ってみましょう。

5.1 プロジェクトのSSH URLを取得

GitLab上のプロジェクトページを開きます。プロジェクトのトップページに、クローンまたはダウンロードするためのURLが表示されている場所があります。通常、「Clone」ボタンや入力フィールドの横に表示されています。

（参考画像：GitLab公式ドキュメントより）

ここで、「Clone with SSH」または「SSH」と表示されている方のURLを選択してコピーします。SSHのURLは通常 [email protected]:username/projectname.git のような形式になっています。（HTTPSの場合は https://gitlab.com/username/projectname.git のような形式です）。

5.2 SSH URLを使ってリポジトリをクローン

ターミナルまたはコマンドプロンプトで、リポジトリをクローンしたいディレクトリに移動し、以下のコマンドを実行します。

bash
git clone [email protected]:username/projectname.git

git clone コマンドに続けて、先ほどGitLabからコピーしたSSHのURLを貼り付けます。

正しいSSHキーが設定されていれば、パスワードやパスフレーズの入力を求められることなく、リポジトリのクローンが開始されます。

Cloning into 'projectname'...
remote: Enumerating objects: XX, done.
remote: Counting objects: 100% (XX/XX), done.
... (クローン処理の進捗)

クローンが完了したら、指定したプロジェクト名のディレクトリが作成され、その中にリポジトリの内容がダウンロードされています。

5.3 プッシュ/プル操作の確認

クローンしたリポジトリのディレクトリに移動し、ファイルを追加・編集してコミットし、プッシュを試みます。

“`bash
cd projectname

ファイルを編集または追加

…

git add .
git commit -m “Add some changes”
git push origin main # または master など、あなたのブランチ名に合わせてください
“`

プッシュの際も、パスワードやパスフレーズの入力を求められることなく、変更がGitLabにプッシュされれば成功です。

同様に、リモートリポジトリに変更があった場合に git pull コマンドを実行しても、パスワード入力なしで最新の変更を取得できるはずです。

これで、GitLabでの日常的なGit操作を、安全かつスムーズにSSH接続で行えるようになりました。

6. 複数のSSHキーとGitLab (~/.ssh/config)

個人用と仕事用など、複数のGitLabアカウントを持っている場合や、GitLab Enterprise Editionの複数のインスタンスを利用している場合など、異なるアカウントやホストに対して異なるSSHキーを使用したい場合があります。

このような状況では、SSHクライアントがどのキーファイルを使用すべきかを判断できるように設定する必要があります。これには、SSHコンフィグファイル (~/.ssh/config) を使用するのが一般的です。

6.1 ~/.ssh/config ファイルの作成と編集

~/.ssh/config ファイルは、SSHクライアントの接続設定をカスタマイズするためのファイルです。このファイルが存在しない場合は、テキストエディタで新規作成します。

“`bash

ファイルが存在するか確認

ls ~/.ssh/config

存在しない場合は作成 (touch またはエディタで新規保存)

touch ~/.ssh/config

ファイルを開いて編集 (例: nano, vim, VS Codeなど)

nano ~/.ssh/config

“`

~/.ssh/config ファイルは、以下のような形式で設定を記述します。

“`config

設定の例

デフォルトのGitLabアカウント

Host gitlab.com
Hostname gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519_personal # このホストに接続する際に使用する秘密鍵

仕事用のGitLabアカウント (gitlab.com 上で別のユーザーアカウント)

Host gitlab.com-work # 任意のエイリアス名
Hostname gitlab.com # 実際のホスト名
User git
IdentityFile ~/.ssh/id_ed25519_work # 仕事用として生成した秘密鍵

別のGitLabインスタンス (セルフホストなど)

Host private.gitlab.com # 実際のホスト名
Hostname private.gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519_private # このインスタンス用の秘密鍵
Port 2222 # もしSSHポートがデフォルトの22以外の場合
“`

各設定ブロックは Host エイリアスで始まります。

• Host: このブロックで定義する設定に付ける任意の名前（エイリアス）です。SSH接続コマンドやGitのURLで使用する際に、このエイリアス名を指定します。例えば、ssh [email protected] のように使います。オリジナルのホスト名（例: gitlab.com）をそのまま指定することも可能です。
• Hostname: 実際に接続するサーバーのホスト名またはIPアドレスを指定します。Host でエイリアス名を指定した場合でも、ここに実際のホスト名を記述します。
• User: SSH接続時に使用するユーザー名を指定します。GitLabの場合は常に git です。
• IdentityFile: このホストに接続する際に使用する秘密鍵ファイルのパスを指定します。これは ~/.ssh/id_ed25519 のような秘密鍵ファイルのパスです。.pub 拡張子は付けません。
• Port (オプション): もしSSHサーバーが標準のTCPポート22番以外で稼働している場合に指定します。通常は指定不要です。

6.2 複数のキーを使う場合のキー生成と登録

複数のSSHキーを使いたい場合は、それぞれのキーペアを異なるファイル名で生成します。例えば、個人用は id_ed25519_personal、仕事用は id_ed25519_work のように生成します。

“`bash

個人用キーの生成 (デフォルト名以外を指定する場合)

ssh-keygen -t ed25519 -C “[email protected]” -f ~/.ssh/id_ed25519_personal

仕事用キーの生成

ssh-keygen -t ed25519 -C “[email protected]” -f ~/.ssh/id_ed25519_work
“`

それぞれのコマンドで生成された公開鍵 (id_ed25519_personal.pub, id_ed25519_work.pub) を、対応するGitLabアカウントに登録します。個人用アカウントには個人用キーの公開鍵を、仕事用アカウントには仕事用キーの公開鍵を登録します。

6.3 config ファイルを使ったGitクローン

~/.ssh/config ファイルを設定したら、GitLabからプロジェクトをクローンする際に、config ファイルで定義した Host エイリアスを使用します。

例えば、上記の設定例で gitlab.com-work というエイリアスを設定した場合、仕事用アカウントのプロジェクトをクローンする際は、以下のようにします。

GitLabのプロジェクトページで表示されるSSH URLは通常 [email protected]:username/projectname.git ですが、これを config ファイルで定義したエイリアスに置き換えます。

“`bash

元のSSH URL: [email protected]:work-username/work-project.git

config 設定 (Host gitlab.com-work) を使ってクローン

git clone [email protected]:work-username/work-project.git
“`

SSHクライアントは、gitlab.com-work というエイリアスを見て、~/.ssh/config ファイルを参照し、Hostname に指定された gitlab.com に接続し、IdentityFile に指定された ~/.ssh/id_ed25519_work を使って認証を試みます。

このように config ファイルを使うことで、複数のGitLabアカウントやホストに対して、適切なSSHキーを自動的に使い分けることができるようになります。

注意: ~/.ssh/config ファイルのパーミッションも重要です。秘密鍵ファイルと同様に、所有者以外が読み書きできないように chmod 600 ~/.ssh/config と設定することをお勧めします。

7. SSHエージェントの使用

SSHエージェントは、秘密鍵をメモリ上に保持し、SSH接続が必要になった際にパスフレーズの入力を肩代わりしてくれるプログラムです。パスフレーズ付きの秘密鍵を使用している場合、接続のたびにパスフレーズを入力するのは手間ですが、SSHエージェントを使うことで、一度パスフレーズを入力すれば、エージェントを再起動するまで（通常はPCの再起動まで）、パスフレーズなしでSSH接続が可能になります。

セキュリティのためパスフレーズを設定しつつ、利便性も確保したい場合に非常に役立ちます。

7.1 SSHエージェントの起動と秘密鍵の追加

SSHエージェントの起動方法とキーの追加方法はOSや環境によって若干異なりますが、基本的な流れは同じです。

1. SSHエージェントを起動する。
2. 秘密鍵をSSHエージェントに追加する (ssh-add)。 このとき、秘密鍵のパスフレーズを入力します。

7.1.1 macOS

macOSでは、ログイン時にssh-agentが自動的に起動し、キーチェーンと連携してパスフレーズを管理するようになっています。通常、ターミナルを開いてそのまま ssh-add コマンドを実行すれば、キーチェーンに登録されているキーや、デフォルトの場所に存在するキーをエージェントに追加できます。

“`bash
ssh-add -K ~/.ssh/id_ed25519 # キーチェーンにパスフレーズを保存してエージェントに追加

パスフレーズの入力を求められたら入力

“`

-K オプションは、パスフレーズをmacOSのキーチェーンに保存するようssh-addに指示します。これにより、macOSにログインしている間はパスフレーズの再入力を求められることがなくなります。

追加されたキーを確認するには ssh-add -l コマンドを使います。

bash
ssh-add -l

登録されているキーのフィンガープリントが表示されます。

7.1.2 Linux

多くのLinuxディストリビューションでは、デスクトップ環境やログインマネージャーによってセッション開始時にSSHエージェントが起動されるよう設定されています。その場合、ターミナルを開いて以下のコマンドで秘密鍵を追加します。

“`bash
ssh-add ~/.ssh/id_ed25519

パスフレーズの入力を求められたら入力

“`

もしエージェントが起動していない場合は、手動で起動する必要があります。

“`bash
eval $(ssh-agent -s)

Agent pid 12345

ssh-agentの環境変数（SSH_AUTH_SOCKなど）を設定

ssh-add ~/.ssh/id_ed25519

パスフレーズの入力を求められたら入力

“`

eval $(ssh-agent -s) コマンドは、ssh-agentを起動し、そのエージェントを利用するために必要な環境変数（SSH_AUTH_SOCKなど）を現在のシェルセッションに設定します。

追加されたキーを確認するには ssh-add -l コマンドを使います。

SSHエージェントをシステム起動時に自動的に起動し、特定のキーを自動的に追加する設定は、使用しているデスクトップ環境やログインマネージャーによって異なります。.bashrc や .profile、.xinitrc などのシェル設定ファイルやスタートアップスクリプトに設定を追加する方法が一般的です。

7.1.3 Windows (Git Bash)

Git for Windowsに含まれるGit Bashでは、起動時にSSHエージェント（ssh-agent）が自動起動し、デフォルトの場所に秘密鍵 (~/.ssh/id_rsa や ~/.ssh/id_ed25519 など) を自動的にエージェントに追加しようとします。パスフレーズ付きのキーの場合、初回利用時にパスフレーズの入力を求められ、そのセッション中はエージェントが記憶してくれます。

デフォルト以外のファイル名でキーを生成した場合や、Git Bash起動後に手動でキーを追加したい場合は、以下のコマンドを使います。

“`bash
ssh-add /c/Users/YourUsername/.ssh/id_ed25519_gitlab

パスフレーズの入力を求められたら入力

“`

Git BashではWindowsのパスを /c/Users/YourUsername/... のように指定します。

追加されたキーを確認するには ssh-add -l コマンドを使います。

7.1.4 Windows (PowerShell / コマンドプロンプト with OpenSSH)

Windows 10以降に標準搭載されているOpenSSHクライアントを使用する場合、ssh-agent サービスを起動して利用します。

まず、SSH Agentサービスが起動しているか確認します。

powershell
Get-Service ssh-agent

もしRunningになっていない場合は、手動で起動するか、自動起動に設定します。

“`powershell

手動で起動

Start-Service ssh-agent

自動起動に設定

Set-Service ssh-agent -StartupType Automatic
“`

サービスが起動したら、秘密鍵をエージェントに追加します。

“`powershell
ssh-add ~/.ssh/id_ed25519

パスフレーズの入力を求められたら入力

“`

追加されたキーを確認するには ssh-add -l コマンドを使います。

7.2 エージェント使用時の接続

SSHエージェントが起動しており、秘密鍵がエージェントに追加されていれば、GitLabへのSSH接続やGit操作 (git clone, git pull, git push) を行う際に、パスフレーズの入力を求められることなく認証が成功するようになります。

これで、セキュリティを保ちながら、より快適にGitLabを利用できるようになりました。

8. SSHキー管理とセキュリティのヒント

SSHキーはあなたのデジタルアイデンティティの一部であり、安全に管理することが極めて重要です。

8.1 秘密鍵のパーミッションの厳格化

前述しましたが、秘密鍵ファイル (~/.ssh/id_ed25519 など) のパーミッションは、所有者（あなた）以外が読み書きできないように設定されている必要があります。理想的なパーミッションは 600 です (-rw-------)。

パーミッションを確認するコマンド：

bash
ls -l ~/.ssh/id_ed25519

もしパーミッションが厳格でない場合、以下のコマンドで修正してください。

bash
chmod 600 ~/.ssh/id_ed25519

SSHクライアントは、パーミッションが厳格でない秘密鍵ファイルを自動的に拒否することがあり、これが Permission denied エラーの原因となることがあります。

また、~/.ssh ディレクトリ自体のパーミッションも、所有者以外が書き込みできないように (700 または 755) 設定されていることが推奨されます。

8.2 秘密鍵のバックアップ

秘密鍵ファイルを紛失すると、そのキーを使ってGitLabなどのサービスにアクセスできなくなります。パスフレーズを設定していても、ファイル自体がなければ認証できません。

秘密鍵ファイルは、安全な場所にバックアップを取ることを強くお勧めします。バックアップする際は、秘密鍵が暗号化されていること（パスフレーズ設定済みであること）を確認し、さらにバックアップファイル自体も暗号化するなど、二重の保護を検討してください。

8.3 不要になったキーの削除

• GitLab側: 使わなくなった、または漏洩の可能性があるSSH公開鍵は、GitLabのユーザー設定の「SSH Keys」画面から削除してください。これにより、その公開鍵を使った認証ができなくなります。
• ローカル側: GitLab側から削除した公開鍵に対応する秘密鍵ファイルも、ローカルの ~/.ssh ディレクトリから削除することを検討してください。不要な秘密鍵ファイルはセキュリティリスクとなり得ます。

8.4 パスフレーズの定期的な変更 (任意)

セキュリティポリシーによっては、SSHキーのパスフレーズを定期的に変更することが推奨される場合があります。パスフレーズを変更したい場合は、ssh-keygen -p -f ~/.ssh/id_ed25519 のようにコマンドを実行し、古いパスフレーズを入力してから新しいパスフレーズを設定できます。

8.5 公開鍵の共有範囲

公開鍵は名前の通り公開しても安全ですが、公開鍵に含まれるコメント（メールアドレスなど）やフィンガープリントから個人情報が推測される可能性があります。不特定多数に公開する必要はありませんが、GitLabのような信頼できるサービスに登録するのは問題ありません。

8.6 フィッシング詐欺等への注意

SSHキーを使った認証は強力ですが、SSHキーのファイル自体やパスフレーズを騙し取ろうとするフィッシング詐欺などには注意が必要です。見知らぬウェブサイトやメールでパスフレーズの入力を求められても絶対に入力しないようにしてください。GitLabのSSH認証でパスフレーズが求められるのは、通常、SSH接続を試みた際のあなたのターミナル/コマンドプロンプト上だけです。

9. トラブルシューティング

SSH接続の設定は、パーミッション、ファイルパス、config 設定、エージェントの状態など、様々な要因が絡み合うため、問題が発生することもあります。ここでは、よくあるトラブルとその解決策について解説します。

9.1 Permission denied (publickey). エラー

これは最も一般的なSSH認証失敗のエラーです。原因は多岐にわたりますが、以下の点を順に確認してください。

1. GitLabに公開鍵が登録されているか？: GitLabのWeb UIで、あなたのユーザー設定 -> SSH Keys に、使用しようとしている秘密鍵に対応する公開鍵が正しく（文字列全体が正確に）登録されているか確認してください。
2. 正しい秘密鍵が使われているか？:
   • SSH接続時に ssh -v [email protected] のように -v オプションを付けてデバッグ情報を出力し、「Trying private key: /path/to/your/key」のような行で、どの秘密鍵ファイルを試そうとしているかを確認します。
   • もし ~/.ssh/config を使っている場合は、Host エイリアスが正しく、IdentityFile のパスが正しい秘密鍵ファイルを指しているか確認します。
   • 複数のキーがある場合、デフォルトのキー (~/.ssh/id_rsa, ~/.ssh/id_ed25519 など) ではなく、特定のキーを使う設定になっているか確認します。
3. 秘密鍵ファイルのパーミッションは正しいか？: 秘密鍵ファイル (~/.ssh/id_ed25519 など) のパーミッションが 600 (-rw-------) になっているか確認します。異なっている場合は chmod 600 /path/to/your/private_key で修正します。~/.ssh ディレクトリのパーミッションも 700 または 755 であることが望ましいです。
4. パスフレーズが正しいか、またはSSHエージェントに追加されているか？:
   • パスフレーズ付きのキーを使用している場合、パスフレーズを正確に入力しているか確認します。
   • SSHエージェントを使用している場合、エージェントが起動しているか (ssh-agent 関連のプロセスを確認)、そして秘密鍵がエージェントに追加されているか (ssh-add -l で確認) を確認します。エージェントに追加されていない場合は ssh-add /path/to/your/private_key で追加します。
5. 公開鍵文字列のコピー＆ペーストミス: GitLabに登録する際に、公開鍵ファイルの中身を完全にコピー＆ペーストできているか、余計な空白や改行が入っていないか再確認します。

9.2 Agent admitted failure to sign using the key.

このエラーは、SSHエージェントが秘密鍵を使って署名を行おうとしたが失敗したことを示しています。主な原因は以下の通りです。

• エージェントに秘密鍵が追加されていない: ssh-add -l コマンドでエージェントに秘密鍵が登録されているか確認します。登録されていない場合は ssh-add /path/to/your/private_key で追加します。
• 秘密鍵のパスフレーズが正しくない: エージェントにキーを追加する際にパスフレーズを間違えたか、SSHエージェントがパスフレーズを正しく扱えていない可能性があります。エージェントから一度キーを削除し (ssh-add -d /path/to/your/private_key)、再度パスフレーズを正確に入力して追加し直してみてください。

9.3 Could not resolve hostname gitlab.com... または ssh: connect to host gitlab.com port 22: Network is unreachable

これはネットワーク接続の問題を示唆しています。

• インターネット接続: お使いのコンピュータがインターネットに接続されているか確認します。
• DNS: gitlab.com の名前解決ができているか確認します。ping gitlab.com や nslookup gitlab.com などのコマンドで確認できます。
• ファイアウォール/プロキシ: 会社のネットワークなど、ファイアウォールやプロキシがSSH接続（デフォルトではTCPポート22番）をブロックしている可能性があります。ネットワーク管理者に確認するか、HTTPS接続の使用を検討してください。GitLabが他のポートでSSH接続を受け付けている場合は、~/.ssh/config で Port オプションを指定して試すこともできます。

9.4 WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!

これは、接続しようとしているホストのフィンガープリントが、~/.ssh/known_hosts ファイルに保存されているフィンガープリントと異なっている場合に表示される警告です。

原因として最も考えられるのは、GitLabサーバーのIPアドレスが変更された、サーバー側のSSHホストキーが変更された、またはサーバー証明書が更新されたなど、正当な理由によるものです。

しかし、中間者攻撃の可能性もゼロではありません。 警告メッセージに表示されている新しいフィンガープリントが、GitLab公式ドキュメントなどで公開されている最新のフィンガープリントと一致するか、必ず確認してください。

正当な変更であることを確認したら、警告メッセージに表示されているコマンド例（通常は ssh-keygen -R hostname のようなコマンド）を実行して、~/.ssh/known_hosts ファイルから古いエントリを削除し、再度接続することで新しいフィンガープリントを登録し直します。

注意: フィンガープリントの確認を怠ると、悪意のあるサーバーに接続してしまうリスクがあります。必ず公式情報を確認してください。

9.5 その他の問題

• WindowsでGit BashとPowerShell/CMDのSSHが連携しない: それぞれが別のOpenSSHクライアント実装や設定ファイルを使用している場合があります。Git Bashの設定はGit Bash内で行い、PowerShell/CMDの設定はWindowsのOpenSSH設定（~/.ssh ディレクトリなど）で行う必要があります。
• WSL (Windows Subsystem for Linux) でSSHが使えない: WSL環境内にOpenSSHクライアントがインストールされているか確認します。インストールされていない場合は、Linuxのパッケージマネージャーでインストールします。キー生成や設定はWSL環境内で行います。
• 複雑な ~/.ssh/config 設定: config ファイルの設定が複雑になると、意図しないキーが使われたり、設定が競合したりすることがあります。シンプルに保つか、ssh -v デバッグ情報を見ながら設定が正しく適用されているか確認してください。

これらのトラブルシューティング手順を試しても解決しない場合は、GitLabの公式ドキュメントやコミュニティフォーラムで同様の問題が報告されていないか検索してみるのも有効です。

10. まとめ

この記事では、GitLabにSSHキーを登録し、安全かつ効率的な接続設定を行うための詳細な手順を解説しました。

• SSHキー認証がHTTPSパスワード認証よりも安全で便利な理由を理解しました。
• ssh-keygen コマンドを使って、ED25519やRSAなどのSSHキーペアを生成する方法と、その際のオプションやパスフレーズの重要性を学びました。
• 生成された公開鍵ファイル (.pub) の内容を確認し、OSごとのコマンドを使ってクリップボードにコピーする方法を習得しました。
• コピーした公開鍵をGitLabのWeb UIから自分のアカウントに登録する具体的なステップを確認しました。
• ssh [email protected] コマンドを使って、SSH接続が正しく認証されるかを確認し、初回接続時のフィンガープリントの重要性を理解しました。
• SSH接続が確立された状態で、GitLabからリポジトリをクローンしたり、プッシュ/プル操作を行ったりする方法を確認しました。
• 複数のSSHキーを使い分けるために、~/.ssh/config ファイルを設定する方法を学びました。
• パスフレーズ入力を省略するためにSSHエージェントを利用する方法をOS別に確認しました。
• SSHキーの管理におけるセキュリティのヒント（パーミッション、バックアップ、削除など）を押さえました。
• Permission denied などの一般的なSSH接続トラブルの原因と解決策を理解しました。

SSHキー認証は、GitLabだけでなく、GitHub, Bitbucketなどの他のGitホスティングサービスや、SSHサーバーへのログインなど、様々な場面で利用される標準的な認証方法です。ここで習得した知識は、GitLab以外での開発環境構築やサーバー管理にも役立つでしょう。

SSHキーを使った安全で快適な開発環境を構築し、GitLabでの作業効率をさらに向上させてください。もしこの記事の手順で不明な点があったり、解決できない問題に直面したりした場合は、お使いのOS、GitLabのバージョン、エラーメッセージなどの詳細を添えて、GitLabの公式ドキュメントやコミュニティフォーラム、あるいは関連する技術コミュニティで質問してみてください。

これで、GitLab SSHキーの登録と接続設定に関する詳細な解説を終わります。長文お読みいただき、ありがとうございました。あなたのGitLabライフが、より安全で快適になることを願っています！

---