GitLabのリポジトリをSSHでクローンしたいとき、鍵の登録方法や接続先の指定で迷うことがある。社内GitLabでは、ブラウザで開くURLとSSHの接続先が異なる環境もある。
この記事では、WindowsとVS Codeを使い、SSH鍵の準備からクローン、接続確認までを順番に説明する。認証エラーへの対処も含め、自分の環境に合わせて作業できる内容である。
URL、IPアドレス、ユーザー名、メールアドレス、氏名は架空の例である。コマンドを実行する前に、実際の値へ読み替える必要がある。
GitLabをSSHでクローンするメリット・デメリット
SSHは、公開鍵と秘密鍵の組み合わせで本人を確認し、暗号化した通信でリポジトリを取得する方法である。クローンとは、ファイルや変更履歴を含むリポジトリのコピーをパソコンに作ることだ。
SSHを使うメリットは、一度鍵を設定すれば、GitLabのログインパスワードをGit操作のたびに入力せずに認証できる点にある。ただし、秘密鍵に設定したパスフレーズの入力が必要な場合はある。
デメリットは、最初の鍵登録に加え、端末の交換や鍵の期限切れに応じた管理が必要なことだ。会社の運用ルールでSSH接続が制限されている場合もあるため、利用条件を事前に確認する。
クローン前に確認する環境とSSH接続先
この記事では、管理者からSSH接続先としてIPアドレスが案内されている社内環境を例にする。
- 作業環境：Windows、VS Code、PowerShell
- GitLabのWeb URL：
https://gitlab.example.com/ - SSH接続先：
192.0.2.10 - GitLabユーザー：
sample.user、メールアドレス：sample.user@example.com - 作業フォルダ：
C:\Workspace、SSH鍵の種類：Ed25519
対象プロジェクトを閲覧・クローンできる権限と、必要に応じて社内ネットワークやVPNへの接続も必要である。
SSH接続でIPアドレスが必須というわけではない。 実際には、GitLabが表示するSSHクローンURLと管理者の案内に従う。ホスト名を使う環境では、そのホスト名を使用する。
この記事の例では、Web画面を https://gitlab.example.com/ で開き、SSH接続には次の形式を使う。
git@192.0.2.10:<グループ名またはユーザー名>/<リポジトリ名>.git先頭の git は通常のGitLab環境で使用するSSHユーザー名であり、自分のGitLabユーザー名に置き換える部分ではない。
GitLabのリポジトリをSSHでクローンする手順
1. GitとSSHを確認する
GitとSSHのバージョンが表示されれば、コマンドを利用できる。
VS Codeの「ターミナル」→「新しいターミナル」をクリックし、PowerShellのターミナルで次を実行する。以降のコマンドもPowerShellを前提とする。
git --version
ssh -Vコマンドが見つからない場合は、Git for WindowsやWindowsのOpenSSHクライアントが利用できる状態か確認する。インストール直後なら、VS Codeを起動し直して再確認する。
2. SSH鍵を準備する
既存の鍵を確認してから、必要な場合だけ新しい鍵を作成する。
Get-ChildItem $env:USERPROFILE\.sshフォルダがない場合は、その場所に鍵がまだ作成されていない可能性がある。次のファイルがある場合は、本人が管理する鍵か、社内ルール上その用途に利用できるかを確認する。
id_ed25519
id_ed25519.pub新しく作成する場合は、次を実行する。
ssh-keygen -t ed25519 -C "sample.user@example.com"保存先の確認では、同名の鍵がないことを確認し、Enterキーで既定値を確定する。
C:\Users\<Windowsユーザー名>\.ssh\id_ed25519続いてパスフレーズを入力し、確認のため同じ内容をもう一度入力する。入力中に文字が表示されなくても異常ではない。パスフレーズは秘密鍵を保護するための文字列であり、会社の方針に従って設定する。
既存の鍵を上書きしてはいけない。 上書き確認が表示されたら n を入力して中止する。別の鍵が必要な場合は、保存名や使い分けを管理者に確認する。
3. 公開鍵をGitLabへ登録する
GitLabに登録するのは、拡張子が .pub の公開鍵である。
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub表示された ssh-ed25519 から始まる1行全体をコピーする。拡張子のない id_ed25519 は秘密鍵なので、GitLabへ貼り付けたり、他人へ送ったりしない。
ブラウザで社内GitLabへログインし、ユーザー設定のSSH鍵の画面を開く。以下はGitLab公式資料で案内されている英語表示の例であり、言語やバージョンによって表示は異なる。
アバターをクリックし、「Edit profile」→「Access」→「SSH keys」→「Add new key」の順にクリックする。「Key」に公開鍵を貼り付け、「Title」に端末を識別できる名前を入力する。
「Usage type」は認証を含む「Authentication」または「Authentication & Signing」をクリックし、「Expiration date」で有効期限を確認してから「Add key」をクリックする。詳細はGitLab公式のSSH鍵設定手順で確認できる。
4. SSH接続とホスト鍵を確認する
クローン前に、SSH接続先への認証を確認する。
ssh -T git@192.0.2.10初回接続では、接続先のホスト鍵を信頼するか確認されることがある。ホスト鍵は、接続先サーバーを識別するための鍵である。
The authenticity of host '192.0.2.10' can't be established.
ED25519 key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxx.
Are you sure you want to continue connecting (yes/no/[fingerprint])?フィンガープリントは鍵の識別用情報である。表示された値を管理者から別途案内された値と照合し、一致した場合だけ yes と入力する。不一致や確認不能の場合は接続を中止する。
承認したホスト鍵は、通常、次のファイルに保存される。
C:\Users\<Windowsユーザー名>\.ssh\known_hosts秘密鍵のパスフレーズを求められた場合は、鍵作成時に設定した値を入力する。次のように表示されればSSH認証は成功である。
Welcome to GitLab, @sample.user!この表示は、対象リポジトリを取得できる権限まで保証するものではない。表示されたユーザー名が自分のアカウントであることも確認する。
5. SSHクローンURLをコピーする
対象プロジェクトが表示するSSHクローンURLを使うと、接続先やプロジェクトパスの入力間違いを防ぎやすい。
ブラウザで社内GitLabの対象プロジェクトを開く。英語表示の例では「Code」をクリックし、「Clone with SSH」のコピーアイコンをクリックする。GitLab公式のクローン手順でも、このURLを使う方法が案内されている。
この記事の環境では、次の形式となる。
git@192.0.2.10:sample.user/sampleproject.gitホスト名が表示される環境なら、そのURLを使う。IPアドレスへの変更が管理者から案内されている場合だけ、その案内に従う。
SSH URLは git clone に渡す文字列である。Web URLを付け足したり、ブラウザのアドレス欄へ入力したりする必要はない。
6. 作業フォルダへクローンする
書き込み権限のある作業フォルダで git clone を実行する。
C:\Workspace がまだない場合だけ、次のコマンドで作成する。作成できない場合は、書き込み可能な場所に変更する。
New-Item -ItemType Directory -Path C:\Workspace作業フォルダへ移動し、コピーしたSSH URLでクローンする。
cd C:\Workspace
git clone git@192.0.2.10:sample.user/sampleproject.git次の表示はクローンの開始を示すものであり、完了を示すものではない。
Cloning into 'sampleproject'...処理が終了して入力待ちに戻り、エラーが出ていないことを確認する。成功すると、この例では C:\Workspace\sampleproject が作成される。
別のプロジェクトでは、URL全体をそのプロジェクトからコピーした値に置き換える。
7. VS Codeで開き、接続先を確認する
クローンしたフォルダに移動し、Gitの状態と接続先を確認する。
cd C:\Workspace\sampleproject
git status
git remote -v
code .git status でリポジトリの状態が表示され、git remote -v のURLが取得したいプロジェクトと一致していれば、保存先と接続先を確認できる。
origin git@192.0.2.10:sample.user/sampleproject.git (fetch)
origin git@192.0.2.10:sample.user/sampleproject.git (push)origin は接続先に付いた名前で、fetch は取得、push は送信を表す。この例ではIPアドレスだが、ホスト名のURLでも環境の設定と一致していれば問題ない。
code . は現在のフォルダをVS Codeで開くコマンドである。認識されない場合は、VS Codeの「ファイル」→「フォルダーを開く」をクリックし、対象フォルダを開く。
既存のブランチがある通常のリポジトリでは、続けて次を実行すると最新の変更を取得できる。
git pull変更がなければ Already up to date. と表示される。空のリポジトリにはまだ取得するブランチがないため、同じ表示にはならない。
クローン後の更新方法と注意点
コミット前に名前とメールアドレスを設定する
Gitの名前とメールアドレスは、変更履歴を記録するコミットに使う情報である。SSH認証やクローン自体の必須設定ではない。
現在の設定は次で確認できる。
git config --global user.name
git config --global user.email未設定の場合は、会社で指定された情報など、実際に使用する値を設定する。
git config --global user.name "Sample User"
git config --global user.email "sample.user@example.com"--global は、そのWindowsユーザーが扱う複数のリポジトリに共通する設定である。対象リポジトリだけに設定する場合は、そのフォルダ内で --global を外して実行する。Git公式の初期設定ガイドで設定範囲を確認できる。
変更内容を確認してからGitLabへ送信する
ファイルを変更したら、反映対象を確認してからコミットと送信を行う。
git status
git add .
git status
git commit -m "変更内容"
git pushgit add . は、現在のフォルダ以下の新規ファイル・変更・削除をコミット対象に追加する。パスワードを含む設定ファイルや不要な生成物が含まれていないか、前後の git status で確認する。
上流ブランチが未設定というエラーが出た場合だけ、現在のブランチ名を確認する。
git branch --show-current現在のブランチが main なら、次のように関連付けて送信する。別の名前なら main を読み替える。
git push -u origin main送信には書き込み権限が必要である。保護されたブランチに直接送信できない場合は、プロジェクトで決められたブランチやマージリクエストの運用に従う。
GitLabをSSHでクローンできないときの対処法
Host key verification failed. と表示される
接続先のホスト鍵を確認・承認できていない可能性がある。次を実行し、直前に表示される説明を確認する。
ssh -T git@192.0.2.10初回接続の確認であれば、手順4のようにフィンガープリントを照合する。
REMOTE HOST IDENTIFICATION HAS CHANGED! も表示される場合は、保存済みのホスト鍵と接続先が提示した鍵が異なる。管理者に変更の正当性を確認してから、対象の登録だけを更新する。known_hosts 全体を削除して回避しない。GitLab公式のホスト鍵変更エラーの説明も参照できる。
Permission denied (publickey). と表示される
公開鍵による認証が成立していない状態である。次の点を確認する。
- 使用中の秘密鍵と、GitLabへ登録した公開鍵が対応しているか
- 接続したい自分のGitLabアカウントに公開鍵を登録したか
- 登録した鍵の用途に認証が含まれているか
- 公開鍵の有効期限が切れていないか
詳細を確認する場合は、次を実行する。
ssh -vT git@192.0.2.10ログでどの鍵を使おうとしているか確認できる。ログを共有するときは、ユーザー名や内部のホスト名などが含まれていないか確認する。原因の確認にはGitLab公式の公開鍵認証エラー対処も役立つ。
fatal: not a git repository と表示される
Gitリポジトリとして認識できない場所でコマンドを実行している可能性が高い。クローンしたフォルダに移動して再確認する。
cd C:\Workspace\sampleproject
git status
git remote -vその場所でも同じエラーが出る場合は、クローンが成功しているか、対象フォルダを取り違えていないかを確認する。
接続先URLが管理者の案内と異なる
接続先がホスト名であること自体はエラーではない。管理者からIPアドレスのURLを使うよう案内されており、既存の接続先がその案内と異なる場合に変更する。
例えば、次のURLが登録されているとする。
git@gitlab.example.com:sample.user/sampleproject.gitリポジトリ内で、案内された接続先と実際のプロジェクトパスを指定する。
git remote set-url origin git@192.0.2.10:sample.user/sampleproject.git
git remote -v変更後は、取得先と送信先の両方が意図したURLになっていることを確認する。
まとめ
GitLabをSSHでクローンするには、公開鍵をGitLabに登録し、接続先のホスト鍵を確認したうえで、SSHクローンURLを使って git clone を実行する。
- SSH接続先は、GitLabの表示と管理者の案内に従う
- 公開鍵だけを登録し、秘密鍵や既存の鍵を適切に管理する
ssh -Tで認証を確認し、クローン終了時のエラーも確認する- クローン後は
git statusとgit remote -vで状態と接続先を確認する
Web画面のURLとSSH接続先が異なっていても、環境の設定どおりであれば問題ない。認証エラーが出た場合は、鍵の対応関係や登録内容から順に確認すると原因を絞り込みやすい。
コメント