GitHubでcloneやpushをするたびに、認証まわりで手が止まってしまう。SSH接続がよいと聞いたものの、何を設定すればいいのかが見えてこない。この段階でつまずく人は少なくありません。
先に結論をお伝えすると、SSH接続は鍵を使ってGitHubに本人確認をする仕組みで、一度整えておくとclone、pull、pushがぐっと扱いやすくなります。
コマンドを丸暗記する前に「何をどこに置くのか」という全体像をつかんでおくと、エラーが出たときにも落ち着いて確認できます。
SSH接続は鍵を使ってGitHubに本人確認する仕組み
SSH接続を一言でいうと、鍵を使ってGitHubに本人確認をする仕組みです。ログイン画面で毎回ユーザー名やトークンを打ち込むのとは、考え方が少し違います。
自分のパソコンに秘密鍵を置き、GitHub側には公開鍵を登録しておく。この2つがそろって初めて、GitHubは「登録済みの本人のパソコンからの操作だ」と判断できます。
ここで取り違えたくないのが、秘密鍵と公開鍵の役割です。
- 秘密鍵
-
自分のパソコンの中だけに置いておく鍵。外には出しません。
- 公開鍵
-
GitHubアカウントに登録する鍵。こちらは共有してかまいません。
GitHub公式ドキュメントでも、認証に使うのはローカルにある秘密鍵で、GitHubへ登録するのは公開鍵だと説明されています。
だからこそ、秘密鍵をGitHubの画面やチャット、メモ帳に貼り付けないことが大前提になります。
SSH接続を一度整えておくと、Gitのclone、pull、pushで使い回せます。VS CodeやターミナルからGitHubを頻繁に触る人ほど、早めに理解しておく価値があると考えています。
SSH接続で必要になるもの
GitHubのSSH接続には、主に4つの要素が関わってきます。それぞれが何を担っているのかを先に押さえておくと、あとの設定がぐっと読みやすくなります。
SSHキー
SSHキーは、秘密鍵と公開鍵のペアです。GitHub公式ドキュメントでは、まず既存のSSHキーがあるかを確認し、そのうえで新しいキーを作る流れが案内されています。
すでに使っている鍵があるなら、うっかり上書きしないよう気をつけたいところ。代表的な公開鍵ファイル名としては、id_ed25519.pub などが公式で例示されています。
ssh-agent
ssh-agentは、SSHキーを扱いやすくするための仕組みです。新しいキーを作ったあと、この ssh-agent に鍵を追加する手順が公式ドキュメントで案内されています。
Macならキーチェーンと連携させるコマンドが用意されていて、環境によって書き方が変わります。実際に設定するときは、公式ドキュメントのMac、Windows、Linuxの該当箇所を見ながら進めるのが安全です。
GitHubアカウントへの公開鍵登録
SSHキーを作っただけでは、GitHub側はまだその鍵を知りません。公開鍵をアカウントの設定画面に登録して初めて、GitHubがその鍵を認証に使えるようになります。
登録方法はWebブラウザからとGitHub CLIからの2通りが公式に案内されていますが、最初はWebブラウザから登録するほうが流れをつかみやすいはずです。
SSH形式のリモートURL
SSH接続を使うには、GitのリモートURLもSSH形式になっている必要があります。GitHubのリポジトリには、HTTPS形式とSSH形式の2つのURLがあります。
HTTPS形式の例
https://github.com/ユーザー名/リポジトリ名.git
SSH形式の例
git@github.com:ユーザー名/リポジトリ名.gitすでにHTTPS形式でcloneしていると、リモートURLがHTTPSのまま残っていることがあります。この状態では、SSHキーを設定しても、そのリポジトリだけはHTTPS認証で動き続けてしまう場合があります。
GitHubをSSHで接続する基本手順
設定の順番を、初心者が追いやすい形で並べます。実際のコマンドはOSや環境によって変わるので、最終的な確認はGitHub公式ドキュメントで行ってください。
1. 既存のSSHキーがあるか確認する
最初に、自分のパソコンにSSHキーがすでにあるかを確認します。MacやLinuxなら、ターミナルで次のコマンドを打ちます。
ls -al ~/.sshid_ed25519.pub のような公開鍵ファイルがあれば、すでに鍵を持っている状態です。その場合は、既存の鍵を使うのか、別名で新しく作るのかを先に決めておきます。
よくわからないまま既存ファイルを上書きすると、別のサービスや別のGitHub設定に影響することがあるためです。
2. 新しいSSHキーを作成する
新しく作る場合、公式ドキュメントではEd25519形式のキーを作るコマンドが案内されています。
ssh-keygen -t ed25519 -C "your_email@example.com"古い環境でEd25519に対応していないときは、RSA 4096bitの例も用意されています。
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"指定するメールアドレスは、自分が見分けやすいものにしておきます。GitHubに登録しているアドレスとそろえておくと、あとで見返したときに迷いません。
保存場所を聞かれてEnterを押すと既定の場所に保存されますが、同じ名前の鍵があると上書き確認が出ることがあります。既存キーを残したいなら、別名で作る判断が必要です。
3. SSHキーをssh-agentに追加する
作成した秘密鍵は、ssh-agentに追加します。Macの場合、公式ドキュメントでは次のようなコマンドが案内されています。
ssh-add --apple-use-keychain ~/.ssh/id_ed25519ファイル名を変えて作ったなら、id_ed25519 の部分を自分の秘密鍵ファイル名に置き換えます。WindowsやLinuxでは手順が変わるので、公式ドキュメントの該当OSの項目を必ず確認してください。
ここをOSごとに読み替えないと、コマンドが通らないことがあります。
4. 公開鍵をGitHubアカウントに登録する
続いて、公開鍵をGitHubアカウントに登録します。登録するのは .pub が付いた公開鍵ファイルです。既定名で作ったなら、次のファイルになります。
~/.ssh/id_ed25519.pubMacなら、公開鍵の中身をクリップボードにコピーするのに次のコマンドが使われることがあります。
pbcopy < ~/.ssh/id_ed25519.pubあとはGitHubの設定画面でSSH keysのページを開き、新しいSSHキーとして貼り付けて追加します。公式ではWebブラウザからの方法とGitHub CLIを使う方法の両方が案内されています。
登録するのは公開鍵だけです。.pub が付いていないファイルは秘密鍵なので、コピーしたり貼り付けたりしないよう気をつけてください。
5. SSH接続をテストする
公式ドキュメントでは、接続確認に次のコマンドが案内されています。
ssh -T git@github.com初回はGitHubのホストを信頼するかどうか確認されることがあります。
表示された内容に不安があるときは、公式の「Testing your SSH connection」やSSH key fingerprintsのページでフィンガープリントを照らし合わせてから進めると安心です。
接続に成功すると、GitHubのユーザー名を含むメッセージが返ってきます。「シェルアクセスは提供されない」という趣旨の一文が出ることもありますが、Git操作の認証確認としては問題ないケースがほとんどです。
6. リポジトリのURLがSSH形式か確認する
SSHキーを設定しても、リポジトリのリモートURLがHTTPS形式のままだと、SSH接続が使われていないことがあります。対象リポジトリのフォルダーで次を確認します。
git remote -vSSH形式なら、次のようなURLが表示されます。
git@github.com:ユーザー名/リポジトリ名.gitHTTPS形式になっていた場合は、必要に応じてSSH形式へ変更します。
git remote set-url origin git@github.com:ユーザー名/リポジトリ名.gitこの設定はリポジトリごとに独立しています。別のリポジトリでは、また改めて確認が必要になります。
VS CodeでSSH接続を使うときの考え方
VS CodeでGitHubを使うときも、仕組みは変わりません。画面上でpushやpullのボタンを押していても、裏側で動いているのはGitです。
SSH接続になるかどうかは、VS Code本体ではなく、ローカルにSSHキーがあるか、ssh-agentに秘密鍵が追加されているか、GitHubに公開鍵が登録されているか、そしてリポジトリのリモートURLがSSH形式か。この4点で決まります。
VS CodeのGit連携がうまくいかないときは、VS Codeだけを疑う前に、まずターミナルで ssh -T git@github.com と git remote -v を確認すると、原因を切り分けやすくなります。
たとえば、接続テストは成功しているのに特定のリポジトリだけpushで認証を求められるなら、そのリポジトリのリモートURLがHTTPS形式のまま残っている可能性が高いです。
逆に、リモートURLはSSH形式なのに接続テストが失敗するなら、SSHキーの作成、ssh-agentへの追加、GitHubへの公開鍵登録のどこかを見直します。
SSH接続でつまずきやすいポイント
SSH接続でつまずきやすいポイントをいくつか挙げます。
秘密鍵と公開鍵を取り違える
一番避けたいのは、秘密鍵を外に出してしまうことです。GitHubに登録するのは、あくまで .pub が付いた公開鍵。.pub が付かない秘密鍵は、自分のパソコンの中だけで管理します。
既存のSSHキーを上書きしてしまう
すでにSSHキーを使っている環境で、同じファイル名のまま新しいキーを作ろうとすると、上書き確認が出ることがあります。
意味がわからないまま進めると、別のGitHubアカウントや別サービスの接続に影響しかねません。既存キーを使うのか、別名で作るのかを決めてから手を動かします。
OSごとの手順を混ぜてしまう
ssh-agentへの追加やクリップボードへのコピーは、Mac、Windows、Linuxで書き方が変わります。
検索で見つけたコマンドをそのまま貼るより、公式ドキュメントでOSを切り替えて、自分の環境に合った手順を確認するほうが確実です。
リモートURLがHTTPSのまま残っている
SSHキーを設定したのにGit操作で認証を求められるときは、リモートURLがHTTPS形式のまま残っている場合が多いです。git remote -v で確認し、必要ならSSH形式に変更すると解決することがあります。
複数アカウントで混乱する
仕事用と個人用など、複数のGitHubアカウントを使い分けていると、どの鍵がどのアカウント用なのかが見えにくくなります。SSH設定ファイルでホストを分ける方法もありますが、最初から手を広げると混乱のもと。
私は、まず1つのアカウントと1つの鍵で接続できる状態を作るところから始めるのが現実的だと考えています。
HTTPS接続のままでもよいケース
SSH接続は便利ですが、誰もが最初からSSHにしなければいけないわけではありません。
GitHubを少し試すだけ、ブラウザ中心で使うだけ、Git操作の頻度がそれほど高くない。そんな段階なら、HTTPS接続のままでも十分に作業できます。
一方で、VS Codeやターミナルからclone、pull、pushを頻繁に行う人は、SSH接続を整えておくと運用がぐっと楽になります。
複数のリポジトリを扱う人や、開発環境を長く使い続ける人ほど、早めにSSHの考え方を押さえておくと安心できるはずです。
判断の目安は、GitHubをブラウザで眺めるだけなのか、ローカルの作業環境からGit操作をよく行うのか。ローカルでGitを使う場面が増えてきたら、SSH接続を学ぶタイミングだと考えるとちょうどいいです。
まずは流れを理解して1つずつ確認する
GitHubのSSH接続が最初だけ難しく感じるのは、SSHキー、ssh-agent、GitHubの設定画面、リモートURLといった複数の要素が絡むからです。
どれか1つでも抜けると、エラーの原因が見えにくくなります。迷ったら、次の順番で1つずつ確認していくと整理しやすいはずです。
ls -al ~/.ssh で、すでに鍵があるかを確かめます。
基本はEd25519形式。既存キーの上書きに注意します。
OSごとに手順が変わるので、公式ドキュメントで自分の環境を確認します。
登録するのは .pub が付いた公開鍵ファイルだけです。
ssh -T git@github.com で認証が通るかを確かめます。
git remote -v で、SSH形式になっているかを見ます。
GitHubやVS CodeでGit操作をする機会が多い人にとって、SSH接続は一度覚えておくと長く役立つ基礎設定です。
全体像さえつかめれば、エラーが出たときも「どの要素を見直せばいいのか」で落ち着いて切り分けられるようになります。
