Git Permission denied (publickey) 에러 5분 해결 — SSH 키부터 다중계정까지
처음 GitHub 저장소를 SSH로 clone하거나 push하려는 순간, 비밀번호도 안 물어보고 단칼에 거부당한 경험이 있으신가요? 화면에는 이런 메시지가 떠 있을 겁니다.
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.당황하지 마세요. 이건 저장소가 사라졌거나 권한 신청을 잘못한 게 아닙니다. "내가 누구인지 SSH로 증명하지 못했다" 는 단 하나의 의미입니다. 참고로 docker: permission denied나 EACCES 같은 OS 파일 권한 에러와는 전혀 다른 문제예요. 이건 순수하게 Git/SSH 인증 문제입니다. 위에서부터 차례대로 따라 치면 5분 안에 풀립니다.
왜 거부될까? 근본 원인 4가지
같은 에러 화면이 떠도 원인은 보통 아래 네 가지 중 하나입니다.
| # | 원인 | 한 줄 설명 |
|---|---|---|
| 1 | SSH 키 자체가 없음 | ~/.ssh에 id_ed25519가 아예 안 만들어진 상태 |
| 2 | GitHub에 공개키 미등록 | 키는 있는데 GitHub Settings에 공개키를 안 올림 |
| 3 | ssh-agent에 키 미등록 | 키 파일은 있지만 agent가 들고 있지 않아 인증에 못 씀 |
| 4 | ~/.ssh 권한 오류 | 권한이 느슨하면 SSH가 보안상 그 키를 무시함 |
네 가지 모두 결과는 똑같이 Permission denied (publickey)로 나타나기 때문에, 먼저 내 상태를 진단하는 게 중요합니다.
1분 진단: ssh -T로 내 상태 확인하기
아무것도 고치기 전에, 지금 GitHub가 나를 알아보는지부터 확인합니다.
ssh -T [email protected]성공이면 이렇게 나옵니다(에러가 아니니 안심하세요):
Hi yourname! You've successfully authenticated,
but GitHub does not provide shell access.실패면 그 Permission denied (publickey)가 또 뜹니다. 이때 어떤 키를 시도하는지 추적하려면 -v(verbose)를 붙입니다.
ssh -vT [email protected]출력 중 Offering public key: ... 줄을 보면 SSH가 어떤 키 파일을 내밀고 있는지 알 수 있고, Permissions ... are too open 같은 경고가 보이면 4번(권한) 문제입니다.
단계별 해결 복붙 가이드
진단이 끝났으면, 아래 순서를 그대로 따라 치세요. 각 명령이 무엇을 하는지 한 줄씩 설명을 달았습니다.
# 1) ed25519 키 생성 (이메일은 GitHub 계정 이메일)
ssh-keygen -t ed25519 -C "[email protected]"
# → 저장 경로/passphrase는 Enter로 기본값 사용해도 OK
# 2) 공개키 내용 출력 → 통째로 복사
cat ~/.ssh/id_ed25519.pub
# 3) ssh-agent 시작
eval "$(ssh-agent -s)"
# 4) 비밀키를 agent에 등록
ssh-add ~/.ssh/id_ed25519
# 5) 인증 검증
ssh -T [email protected]2번에서 복사한 ssh-ed25519 AAAA... 문자열을 GitHub → Settings → SSH and GPG keys → New SSH key에 붙여넣고 저장하면 됩니다. 그다음 5번을 다시 실행해서 Hi yourname!이 나오면 끝입니다.
실무 팁: 저는 신입 온보딩 때 이 5줄을 메모장에 박아두고 그대로 따라 치게 합니다. 열에 아홉은 "2번 공개키를 GitHub에 안 올린 것" 아니면 "ssh-agent에 키를 안 올린 것"이더군요. 키 생성부터 다시 하기보다
ssh-add -l로 agent에 키가 있는지부터 확인하면 시간을 아낍니다.
권한 체크리스트: 느슨하면 키를 무시한다
SSH는 비밀키를 남이 읽을 수 있는 상태면 보안상 위험으로 간주하고 그 키를 아예 사용하지 않습니다. 그래서 권한이 틀리면 키가 멀쩡해도 거부당해요. 아래로 정리합니다.
chmod 700 ~/.ssh # 디렉터리: 나만 접근
chmod 600 ~/.ssh/id_ed25519 # 비밀키: 나만 읽기/쓰기
chmod 644 ~/.ssh/id_ed25519.pub # 공개키: 남이 읽어도 OK
chmod 600 ~/.ssh/config # config 파일-vT에서 Permissions are too open 경고를 봤다면 이 네 줄이 정답입니다.
OS별 차이 비교표
ssh-agent를 시작하고 키를 유지하는 방법이 OS마다 미묘하게 다릅니다.
| 항목 | Windows (Git Bash) | macOS | Linux |
|---|---|---|---|
| agent 시작 | eval "$(ssh-agent -s)" 또는 start-ssh-agent | eval "$(ssh-agent -s)" (보통 자동) | eval "$(ssh-agent -s)" 수동 |
| 키체인 저장 | 없음 (재부팅 시 재등록) | ssh-add --apple-use-keychain ~/.ssh/id_ed25519 | 없음 |
| config 설정 | 일반 | UseKeychain yes 추가 | 일반 |
| 키 경로 | C:\Users\이름\.ssh | ~/.ssh | ~/.ssh |
macOS에서 재부팅마다 passphrase를 다시 묻는 게 귀찮다면, ~/.ssh/config에 아래를 넣으세요.
Host github.com
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519회사/개인 계정 분리: ~/.ssh/config 다중계정 설정
GitHub 계정 하나엔 같은 공개키를 두 번 등록할 수 없습니다. 회사 계정과 개인 계정을 한 PC에서 쓰려면 키를 두 개 만들고 config로 구분합니다.
# ~/.ssh/config
# 개인 계정
Host github-personal
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_personal
# 회사 계정
Host github-work
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_work이제 clone할 때 github.com 대신 위에서 정의한 별칭(Host)을 씁니다.
# 개인 저장소
git clone git@github-personal:myname/my-repo.git
# 회사 저장소
git clone git@github-work:company/service.git핵심은 @ 뒤의 호스트가 실제 도메인이 아니라 config의 Host 별칭이라는 점입니다. 이 별칭에 따라 어떤 키를 쓸지 결정됩니다.
SSH가 막힐 때: HTTPS + PAT 대안
사내 방화벽이 22번 포트를 막아두면 SSH 자체가 연결되지 않습니다. 이때는 HTTPS와 Personal Access Token(PAT) 으로 우회합니다. (2021년 비밀번호 인증 폐지 이후, HTTPS도 비밀번호 대신 PAT를 사용합니다.)
# 기존 SSH 원격을 HTTPS로 전환
git remote set-url origin https://github.com/user/repo.git
# push 시 비밀번호 자리에 PAT 붙여넣기그래도 SSH를 쓰고 싶다면, GitHub가 제공하는 443 포트 over-HTTPS SSH를 config에 설정할 수 있습니다.
Host github.com
HostName ssh.github.com
Port 443
User gitHTTPS는 어디서든 잘 뚫리지만 매번 토큰 관리를 해야 하고, SSH는 한 번 세팅하면 편하지만 포트가 열려 있어야 합니다. 환경에 맞게 고르세요. 참고로 GitHub가 RSA SHA-1 키 지원을 종료하면서 지금은 ed25519가 사실상 표준입니다.
결론: 막히면 이 순서대로
다음에 또 Permission denied (publickey)를 만나면 아래 체크리스트를 위에서부터 확인하세요.
ssh -T [email protected]→ 상태 진단- 키 없으면
ssh-keygen -t ed25519 - 공개키(
cat *.pub)를 GitHub Settings에 등록 eval "$(ssh-agent -s)"→ssh-add로 agent 등록chmod 700 ~/.ssh,600 id_ed25519로 권한 정리- 다중계정이면
~/.ssh/config의 Host 별칭 확인 - 22번 포트가 막혔으면 HTTPS+PAT 또는 443 over-SSH
자주 묻는 질문 (FAQ)
Q. 키를 분명히 GitHub에 등록했는데도 계속 거부돼요.
A. 대부분 agent에 키가 안 올라가 있거나, config의 Host 별칭이 잘못된 경우입니다. ssh-add -l로 키가 목록에 있는지 확인하고, 없으면 ssh-add ~/.ssh/id_ed25519로 다시 등록하세요. 다중계정이라면 clone URL의 호스트 별칭이 config와 일치하는지도 확인합니다.
Q. rsa 키는 이제 못 쓰나요?
A. GitHub는 보안이 강한 ed25519를 권장합니다. RSA SHA-1 서명은 지원이 종료되어, 새로 만든다면 ed25519가 정답입니다. 다만 구형 사내 Git 서버 등 ed25519를 못 받는 환경이라면 ssh-keygen -t rsa -b 4096으로 RSA 키를 만들어 쓰면 됩니다.
Q. 회사·개인 두 계정을 동시에 쓰면 push는 어떻게 하나요?
A. 키를 두 개 만들고 ~/.ssh/config에 Host github-work / Host github-personal처럼 별칭을 정의한 뒤, git@github-personal:user/repo.git 형태로 별칭을 넣어 clone/remote를 설정하면 SSH가 자동으로 해당 키를 골라 인증합니다.
이 글은 AI 에이전트가 1차 초안을 작성한 뒤, 사람 편집자가 사실관계·출처·톤과 맥락을 검토하여 발행했습니다. 오류나 부정확한 내용이 확인되면 24시간 이내에 정정합니다.
댓글
불러오는 중...