🙆

Gitの認証情報エラー「Authentication failed」を解決する

に公開
Git
SSH
Authentication
keychain
tech

はじめに

git push や git pull を実行した際、fatal: Authentication failed for '...' というエラーメッセージに遭遇することがある。これは、Gitがリモートリポジトリ（GitHub, GitLab, Bitbucketなど）との認証に失敗したことを示している。

原因は使用している認証方式（HTTPSまたはSSH）やOSによって様々である。この記事では、この認証エラーの原因を切り分け、OSごとの具体的な解決策を備忘録として記録する。

対象環境

原因

Authentication failed エラーの主な原因は、利用している認証方式に応じて以下の2つに大別される。

  1. HTTPS認証: OSに保存されている認証情報（ユーザー名/パスワード、またはパーソナルアクセストークン）が古い、無効になっている、あるいは間違っている。特にGitHubでは、2021年8月13日以降、パスワード認証が廃止され、Personal Access Token (PAT) の使用が必須となっている。
  2. SSH認証: 使用しようとしているSSHキーがリモートリポジトリのホスティングサービスに登録されていない、またはローカルのSSHエージェントが秘密鍵を正しく読み込めていない。

解決策

1. 認証方式の確認

最初に、対象リポジトリがどちらの認証方式を使用しているかを確認する。以下のコマンドを実行し、リモートURLの形式を調べる。

ターミナル
git remote -v
  • URLが https://... で始まっていればHTTPS認証。
    実行結果例
    origin  https://github.com/username/repository.git (fetch)
origin  https://github.com/username/repository.git (push)
  • URLが git@... で始まっていればSSH認証。
    実行結果例
    origin  git@github.com:username/repository.git (fetch)
origin  git@github.com:username/repository.git (push)

2. HTTPS認証の場合の対処法

基本的な解決策は、各OSの認証情報管理システムから古い情報を削除し、新しい認証情報（通常はPAT）で再認証することである。

macOS: キーチェーンアクセスを利用する

macOSでは、GitのHTTPS認証情報が「キーチェーンアクセス」アプリケーションに保存される。

  1. LaunchpadまたはSpotlight検索から「キーチェーンアクセス.app」を起動する。
  2. 右上の検索窓にリポジトリホスト名（例: github.com）を入力して検索する。
  3. 種類が「インターネットパスワード」となっている該当項目を見つけ、右クリックして「“github.com”を削除」を選択する。
  4. ターミナルに戻り、再度 git pull や git push を実行する。
  5. ユーザー名とパスワード（PATを入力）を求めるプロンプトが表示されるので、正しい情報を入力する。

Windows: 資格情報マネージャーを利用する

Windowsでは「資格情報マネージャー」で認証情報が管理される。

  1. スタートメニューで「資格情報マネージャー」を検索して開く。
  2. 「Windows 資格情報」を選択する。
  3. 「汎用資格情報」のセクションから git:https://github.com のような項目を探す。
  4. 該当項目をクリックして詳細を展開し、「削除」を選択する。
  5. ターミナルに戻り、再度 git コマンドを実行する。
  6. 認証ダイアログが表示されたら、正しいユーザー名とPATを入力する。

Linux: Credential Helperをリセットする

Linux環境では、Git Credential Helperの設定によって認証情報の保存方法が異なる。store モードが設定されている場合、認証情報は ~/.git-credentials に平文で保存される。

  1. まず、設定されているCredential Helperを確認する。
    ターミナル
    git config --global credential.helper
  2. store が設定されている場合、~/.git-credentials ファイルをエディタで開き、該当する行を削除する。
    ~/.git-credentials
    # このような形式で保存されている
https://user:your_pat@github.com
  3. または、以下のコマンドでCredential Helperの設定を一時的に解除し、再認証を促すこともできる。
    ターミナル
    git config --global --unset credential.helper
  4. 再度 git コマンドを実行し、ユーザー名とPATを入力する。

3. SSH認証の場合の対処法

SSH認証エラーは、SSHキーの生成、リモートリポジトリへの登録、SSHエージェントへの登録のいずれかの段階に問題があることが多い。

ステップ1: SSHキーの確認と生成

~/.ssh ディレクトリに秘密鍵と公開鍵のペア（例: id_ed25519 と id_ed25519.pub）が存在するか確認する。存在しない場合は、以下のコマンドで生成する。ED25519形式が推奨される。

ターミナル
ssh-keygen -t ed25519 -C "your_email@example.com"

詳細は公式ドキュメントを参照。

ステップ2: SSH公開鍵をリモートリポジトリに登録

生成した公開鍵（.pub ファイル）の内容をコピーし、GitHubなどのSSHキー設定画面に登録する。

ターミナル
# macOSの場合
pbcopy < ~/.ssh/id_ed25519.pub

# Linuxの場合 (xclipが必要)
xclip -selection clipboard < ~/.ssh/id_ed25519.pub

# Windows (Git Bash)の場合
cat ~/.ssh/id_ed25519.pub | clip

詳細は公式ドキュメントを参照。

ステップ3: SSHエージェントに秘密鍵を登録

SSHエージェントは、SSHキーのパスフレーズを記憶し、認証を代行するプログラムである。

macOS

macOSではSSHエージェントが自動で起動する。~/.ssh/config ファイルに設定を追加すると、パスフレーズをキーチェーンに安全に保存できる。

~/.ssh/config
Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

設定後、ssh-add コマンドでキーをエージェントに追加する。

ターミナル
# macOS 12.0以降
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Windows

PowerShellで ssh-agent サービスを起動し、自動起動するよう設定する。

PowerShell
# ssh-agentサービスの状態を確認
Get-Service ssh-agent

# サービスが停止している場合は開始
Start-Service ssh-agent

# PC起動時に自動で開始するように設定
Set-Service -Name ssh-agent -StartupType 'Automatic'

サービス起動後、ssh-add で秘密鍵を登録する。

PowerShell
ssh-add ~/.ssh/id_ed25519
Linux

セッション開始時にSSHエージェントを起動し、キーを登録する。

ターミナル
# エージェントを起動
eval "$(ssh-agent -s)"

# 秘密鍵を登録
ssh-add ~/.ssh/id_ed25519

毎回このコマンドを実行しなくて済むよう、.bashrc や .zshrc などのシェル設定ファイルに起動スクリプトを追記することもできる。

ステップ4: 接続テスト

最後に、以下のコマンドでSSH接続が成功するかテストする。

ターミナル
ssh -T git@github.com

Hi username! You've successfully authenticated... というメッセージが表示されれば、設定は完了である。

おわりに

Gitの Authentication failed エラーは、認証方式（HTTPS/SSH）とOSの組み合わせによって対処法が異なる。問題解決の第一歩は、git remote -v コマンドで利用中の認証方式を正確に把握することである。

本記事では、OSごとの認証情報の管理方法と、一般的なトラブルシューティング手順をまとめた。同様の問題に直面した開発者にとって、この備忘録が解決の一助となれば幸いである。

参考リンク

Discussion