Git Permission denied (publickey) SSH 키 오류 5단계 실전 해결 가이드

Git Permission denied (publickey) 오류 원인과 핵심 요약

이 오류는 GitHub에 등록된 공개키와 짝이 맞는 개인키를 내 컴퓨터의 SSH가 찾지 못했거나, 찾았더라도 제시하지 못했다는 뜻입니다. 키가 아예 없는 경우, 키는 있지만 ssh-agent에 올라가 있지 않은 경우, 다른 계정의 키가 먼저 제시되는 경우, 윈도우에서 Git이 다른 SSH 프로그램을 쓰는 경우 중 하나이며 아래 진단 한 번으로 어느 쪽인지 가려집니다.

개인키 파일(확장자 없는 id_ed25519)은 절대 어디에도 붙여 넣거나 업로드하지 마세요. GitHub에 등록하는 것은 항상 .pub으로 끝나는 공개키뿐입니다. 개인키가 노출됐다면 해당 키를 GitHub에서 즉시 삭제하고 새로 만들어야 합니다.

---

증상별 바로가기

지금 상황	바로 갈 곳
원인을 모르겠다, 처음 보는 오류다	해결 방법 1
SSH 키를 만든 적이 없거나 새 PC다	해결 방법 2
어제까지 됐는데 재부팅 후 갑자기 안 된다	해결 방법 3
회사 계정과 개인 계정을 한 PC에서 같이 쓴다	해결 방법 4
윈도우 터미널의 ssh -T는 성공하는데 git push나 VS Code·Cursor만 실패한다	해결 방법 5

---

해결 방법 1: 어디서 막혔는지 확인하기

1. 터미널을 엽니다. 윈도우는 PowerShell, 맥은 터미널 앱입니다.

2. GitHub과 SSH 연결이 되는지 시험합니다.

   ssh -T git@github.com

3. 처음 연결할 때 Are you sure you want to continue connecting 질문이 나오면 yes를 입력합니다. 화면의 지문이 GitHub 공식 문서에 공개된 지문과 같은지 확인한 뒤 진행하세요.

4. Hi 사용자이름! You've successfully authenticated가 나오면 SSH 연결은 정상입니다. 이 경우 저장소 주소가 틀렸거나, Git이 다른 SSH 프로그램을 쓰고 있는 것이므로 아래 5번 과정과 해결 방법 5로 갑니다.

5. 저장소 주소를 확인합니다.

   git remote -v

6. git@github.com:계정/저장소.git 형식이면 SSH 주소입니다. 계정 이름과 저장소 이름에 오타가 없는지 봅니다.

7. 2번에서 Permission denied (publickey)가 나왔다면 자세한 기록을 봅니다.

   ssh -vT git@github.com

8. 출력에서 Offering public key 로 시작하는 줄을 찾습니다.

   • 이 줄이 아예 없다면 SSH가 제시할 키를 찾지 못한 것입니다 → 해결 방법 2와 해결 방법 3
   • 이 줄은 있는데 실패한다면 GitHub에 등록되지 않은 키, 또는 다른 계정의 키를 제시한 것입니다 → 해결 방법 2의 등록 단계와 해결 방법 4

---

해결 방법 2: SSH 키 만들고 GitHub에 등록하기

1. 이미 만든 키가 있는지 확인합니다. 윈도우 PowerShell은 아래 명령을 씁니다.

   ls $env:USERPROFILE\.ssh

2. 맥은 아래 명령을 씁니다.

   ls -al ~/.ssh

3. id_ed25519와 id_ed25519.pub이 이미 있다면 새로 만들지 말고 6번 등록 단계로 바로 갑니다.

4. 없다면 키를 만듭니다. 따옴표 안에는 GitHub 계정 이메일을 넣습니다.

   ssh-keygen -t ed25519 -C "your_email@example.com"

5. 저장 위치를 묻으면 Enter로 기본값을 쓰고, 패스프레이즈를 두 번 입력합니다.

6. 공개키를 클립보드에 복사합니다. 윈도우 PowerShell은 아래 명령입니다.

   Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

7. 맥은 아래 명령입니다.

   pbcopy < ~/.ssh/id_ed25519.pub

8. GitHub 웹사이트에서 오른쪽 위 프로필 사진을 눌러 [Settings > SSH and GPG keys]로 이동합니다.

9. New SSH key를 누르고, Title에 이 PC를 구분할 이름을 적은 뒤 Key 칸에 붙여 넣고 Add SSH key를 누릅니다.

10. 해결 방법 1의 ssh -T git@github.com으로 다시 확인합니다.

4번에서 Overwrite (y/n)?가 나오면 n을 누르세요. 같은 이름의 키가 이미 있다는 뜻이고, 덮어쓰면 그 키를 쓰던 다른 서버와 서비스의 접속이 모두 끊깁니다. 새 키가 꼭 필요하다면 저장 위치를 묻는 단계에서 다른 파일 이름을 지정하세요.

---

해결 방법 3: ssh-agent에 키 올리기

키를 만들었는데도 안 되거나, 재부팅 후 갑자기 안 된다면 키가 ssh-agent에 올라가 있지 않은 경우가 대부분입니다.

윈도우

1. 시작 메뉴에서 PowerShell을 검색해 관리자 권한으로 실행합니다.

2. ssh-agent 서비스를 자동 시작으로 바꾸고 실행합니다. 윈도우에서는 이 서비스가 기본적으로 꺼져 있습니다.

   Get-Service ssh-agent | Set-Service -StartupType Automatic

3. 이어서 서비스를 시작합니다.

   Start-Service ssh-agent

4. 일반 PowerShell 창에서 키를 등록합니다. 패스프레이즈를 묻으면 입력합니다.

   ssh-add $env:USERPROFILE\.ssh\id_ed25519

5. 등록된 키 목록을 확인합니다. 키 지문이 한 줄 이상 보이면 성공입니다.

   ssh-add -l

맥

1. ssh-agent를 실행합니다.

   eval "$(ssh-agent -s)"

2. 키를 등록하면서 패스프레이즈를 키체인에 저장합니다.

   ssh-add --apple-use-keychain ~/.ssh/id_ed25519

3. 재부팅 후에도 유지되도록 ~/.ssh/config 파일에 아래 내용을 넣습니다. 파일이 없으면 새로 만듭니다.

   Host github.com
     AddKeysToAgent yes
     UseKeychain yes
     IdentityFile ~/.ssh/id_ed25519

2번의 서비스 설정 변경은 관리자 권한이 필요합니다. 회사에서 지급한 PC라 관리자 권한이 없다면 IT 담당자에게 ssh-agent 서비스 활성화를 요청하세요. UseKeychain은 맥 전용 설정이라 윈도우의 config 파일에는 넣지 않습니다.

---

해결 방법 4: 계정이 여러 개일 때 config로 키 지정하기

회사 계정과 개인 계정을 같이 쓰면, SSH가 엉뚱한 계정의 키를 먼저 제시해 실패하는 경우가 많습니다. GitHub은 같은 공개키를 두 계정에 동시에 등록하지 못하게 막기 때문에, 계정마다 키를 따로 만들어야 합니다.

1. 해결 방법 2와 같은 방법으로 두 번째 키를 만듭니다. 저장 위치를 묻는 단계에서 id_ed25519_work처럼 다른 이름을 지정합니다.

2. 새 키의 공개키를 회사 계정의 [Settings > SSH and GPG keys]에 등록합니다.

3. .ssh 폴더의 config 파일을 엽니다. 윈도우 경로는 C:\Users\사용자이름\.ssh\config이며 확장자가 없습니다.

4. 아래처럼 호스트 별명을 두 개 만듭니다.

   Host github.com
     HostName github.com
     User git
     IdentityFile ~/.ssh/id_ed25519
     IdentitiesOnly yes
   
   Host github-work
     HostName github.com
     User git
     IdentityFile ~/.ssh/id_ed25519_work
     IdentitiesOnly yes

5. 회사 저장소의 원격 주소를 별명으로 바꿉니다. 회사계정/저장소는 실제 이름으로 바꿉니다.

   git remote set-url origin git@github-work:회사계정/저장소.git

6. 별명으로 연결을 시험합니다. 회사 계정 이름으로 인사가 나오면 성공입니다.

   ssh -T git@github-work

IdentitiesOnly yes는 지정한 키만 제시하라는 뜻이라, 다른 키가 먼저 제시되는 문제를 막아줍니다. 윈도우 메모장으로 config를 만들 때는 저장 창에서 파일 형식을 모든 파일로 바꿔야 config.txt로 저장되지 않습니다.

---

해결 방법 5: Git이 쓰는 SSH 프로그램 맞추기

윈도우에서 ssh -T는 성공하는데 git push, VS Code, Cursor에서만 실패한다면 대부분 이 경우입니다. Git for Windows는 자체 SSH 프로그램을 함께 설치하는데, 이 프로그램은 해결 방법 3에서 설정한 윈도우의 ssh-agent 서비스를 쓰지 않습니다.

1. 지금 Git이 어떤 SSH를 쓰도록 지정되어 있는지 확인합니다. 아무것도 나오지 않으면 Git 내장 SSH를 쓰는 중입니다.

   git config --global --get core.sshCommand

2. Git이 윈도우 기본 SSH를 쓰도록 지정합니다.

   git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

3. VS Code나 Cursor를 완전히 종료했다가 다시 실행합니다.

4. 다시 git push를 시도합니다.

5. 반대로 Git 내장 SSH를 계속 쓰고 싶다면 이 설정 대신 Git Bash에서 eval "$(ssh-agent -s)"와 ssh-add로 키를 따로 올려야 합니다. 두 방식을 섞지 말고 하나로 정하는 편이 관리가 쉽습니다.

6. Git for Windows를 다시 설치할 때는 설치 화면의 SSH 선택 단계에서 외부 OpenSSH를 쓰는 옵션을 고르면 같은 효과를 얻을 수 있습니다. 옵션 문구는 버전에 따라 다를 수 있습니다.

---

문제 해결이 안 될 경우 추가 점검 사항

• 회사망에서 22번 포트 차단: Connection timed out이나 port 22: Connection refused라면 키 문제가 아니라 방화벽 문제입니다. GitHub은 443번 포트로도 SSH를 받으므로, config의 Host github.com 항목에 HostName ssh.github.com과 Port 443 두 줄을 넣고 다시 시험해보세요.
• 맥·리눅스 키 파일 권한: UNPROTECTED PRIVATE KEY FILE 경고가 나오면 chmod 600 ~/.ssh/id_ed25519로 개인키 권한을 본인만 읽을 수 있게 바꿉니다.
• 인증은 되는데 저장소 접근이 거부됨: Repository not found나 Permission to 저장소 denied to 다른계정이 나오면 키는 정상이고, 그 계정에 저장소 권한이 없거나 다른 계정 키로 인증된 것입니다. 해결 방법 4를 확인하세요.
• 조직의 SSO 정책: 회사 GitHub 조직이 SSO를 쓰면 [Settings > SSH and GPG keys]의 해당 키 옆에서 SSO 승인(Configure SSO)을 따로 해줘야 조직 저장소에 접근됩니다.
• GUI 클라이언트: SourceTree, GitHub Desktop 같은 프로그램은 자체 SSH·인증 설정을 따로 가지고 있습니다. 터미널에서는 되는데 이런 프로그램에서만 안 된다면 그 프로그램의 설정 화면에서 SSH 키 경로를 확인하세요.