GitHub SSH 키 등록 방법 및 Permission denied (publickey) 오류 5분 해결 팁

Posted on by steve

 

GitHub SSH 키 등록 및 인증 오류 완벽 해결 가이드! 매번 귀찮게 Personal Access Token(PAT)을 복사해 붙여넣고 계신가요? 5분 만에 초고속으로 SSH 키를 생성·등록하고, 지긋지긋한 ‘Permission denied (publickey)’ 오류까지 단칼에 해결하는 실전 노하우를 모두 정리해 드립니다.

 

깃허브(GitHub)에 기분 좋게 커밋을 마치고 git push origin main을 입력했는데, 갑자기 시뻘건 글씨로 Permission denied (publickey)라는 경고 메시지가 화면을 가득 채운 적 있으신가요? 솔직히 저도 처음에 개발 공부를 시작했을 때 이 오류를 보고 컴퓨터가 고장 난 건 아닌지 식은땀을 흘렸던 기억이 생생해요. 😊

GitHub가 비밀번호 기반 인증 방식을 완전히 중단한 이후로 토큰을 발급받아 사용하는 분들이 많은데요. 토큰은 만료 기간이 다가올 때마다 다시 갱신해야 해서 정말 번거롭고 일의 흐름을 뚝뚝 끊어놓곤 하죠. 하지만 SSH 키(Secure Shell Key)를 한 번만 등록해 두면 번거로운 비밀번호 입력 없이 안전하고 자유롭게 작업할 수 있답니다. 오늘 저와 함께 터미널에서 딱 5분 만에 세팅을 끝내볼까요?

 

1. 왜 개발자들은 HTTPS 대신 SSH 키를 선호할까요? 🤔

깃허브와 내 컴퓨터가 소통하는 통로는 크게 두 가지예요. 바로 HTTPS 방식과 SSH 방식입니다. 둘 다 원격 저장소와 데이터를 주고받을 수 있지만, 사용성과 보안 측면에서 꽤 큰 차이가 있어요.

HTTPS는 웹 주소처럼 익숙해서 초보자가 시작하기 쉽지만, 매번 긴 Personal Access Token 문자열을 요구하거나 자격 증명(Credential) 헬퍼가 꼬여서 로그인 오류를 일으키기 십상이에요. 반면에 SSH 키 인증 방식은 ‘비대칭 암호화 기술’을 사용하여 내 컴퓨터에는 ‘비밀키(Private Key)’를 숨겨두고, 깃허브에는 ‘공개키(Public Key)’를 올려두어 둘이 서로를 자동으로 알아보고 문을 열어주는 시스템이랍니다. 사람이 직접 긴 암호를 타이핑할 필요가 전혀 없는 셈이죠!

💡 알아두세요!
SSH 방식은 보안 토큰처럼 정기적으로 만료 기간을 연장해 줄 필요가 없어요. 한 번 등록해 두면 노트북이나 PC를 포맷하기 전까지 평생 ‘무인 하이패스’처럼 편리하게 깃허브를 이용할 수 있답니다!

HTTPS vs SSH 비교 분석표

비교 항목 HTTPS 인증 SSH 키 인증 추천 대상
인증 방식 Personal Access Token (PAT) 공개키 / 개인키 암호쌍 모든 개발 환경
입력 편의성 만료 시마다 토큰 재발급 및 입력 필요 자동 인증 (입력 불필요) SSH 적극 권장
보안 수준 토큰 문자열 유출 위험 존재 비밀키가 로컬 외부로 절대 전송 안 됨 보안 중시 프로젝트
저장소 주소 예시 https://github.com/user/repo.git git@github.com:user/repo.git 프로젝트 리모트 설정

 

2. 터미널에서 초고속으로 SSH 키 생성하기 🔑

본격적으로 키를 생성하기 전에, 혹시 내 컴퓨터에 이미 만들어진 SSH 키가 있는지 먼저 확인해 보는 것이 좋아요. 터미널(Windows의 경우 Git Bash)을 열고 아래 명령어를 쳐보세요.

📝 기존 SSH 키 확인 명령어

ls -al ~/.ssh

출력 결과에 id_ed25519.pub 또는 id_rsa.pub 파일이 보이지 않는다면 새로운 키를 생성해야 합니다. 요즘은 구형 RSA 알고리즘보다 보안성이 뛰어나고 속도가 훨씬 빠른 Ed25519 알고리즘을 사용하는 것이 글로벌 표준 권장 사항이에요.

⚠️ 주의하세요!
키를 생성할 때 터미널에서 Enter passphrase라는 질문이 나옵니다. 개인 컴퓨터에서 비밀번호 없이 바로 push하고 싶다면 아무것도 입력하지 마시고 Enter 키를 두 번 쳐서 넘어가시면 됩니다!

🔢 SSH 키 생성 명령어 맞춤 도구

암호화 알고리즘:

GitHub 이메일:

 

3. GitHub 웹사이트에 공개키 등록하기 💻

키 생성이 완료되었다면 이제 자물쇠 역할을 해줄 공개키(Public Key)를 GitHub 웹사이트에 등록할 차례예요. 정말 간단한 3단계로 이루어집니다.

  1. 1단계 (공개키 복사): 터미널에서 클립보드로 공개키를 즉시 복사합니다. Mac 사용자는 pbcopy < ~/.ssh/id_ed25519.pub를 실행하고, Windows 사용자는 clip < ~/.ssh/id_ed25519.pub를 입력하세요. 또는 cat ~/.ssh/id_ed25519.pub 명령어로 화면에 띄운 뒤 전체 텍스트를 드래그 복사해도 됩니다.
  2. 2단계 (설정 메뉴 이동): GitHub에 로그인한 뒤 오른쪽 상단 프로필 아이콘을 누르고 Settings > SSH and GPG keys 메뉴로 들어갑니다.
  3. 3단계 (키 추가): 초록색 New SSH key 버튼을 누르고, Title에는 알아보기 쉬운 이름(예: ‘My-MacBook-Pro’)을 적은 뒤 Key 영역에 복사한 키를 붙여넣고 Add SSH key를 클릭하면 완료됩니다!
📌 알아두세요!
절대로 id_ed25519(확장자가 없는 개인키 파일)를 외부에 노출하거나 GitHub에 올리면 안 됩니다! 반드시 파일명 끝에 .pub가 붙어있는 공개키 파일만 복사해서 등록하셔야 해요.

 

4. 단골 인증 오류 3가지 5분 만에 해결하기 🛠️

등록을 마친 후 정상적으로 연결되는지 확인하려면 터미널에 ssh -T git@github.com을 입력해 보세요. 만약 아래와 같은 에러가 뜬다면 당황하지 마시고 바로 해결해 봅시다.

🚨 문제 1: Permission denied (publickey)

원인: 백그라운드에서 동작하는 SSH 에이전트(ssh-agent)가 새로 만든 개인키를 인식하지 못하고 있을 확률이 90%입니다.

해결법: 에이전트를 깨우고 키를 등록해 주세요.

eval “$(ssh-agent -s)”
ssh-add ~/.ssh/id_ed25519

🚨 문제 2: 계속 토큰 비밀번호를 물어볼 때

원인: 로컬 Git 저장소의 리모트 URL 주소가 여전히 HTTPS 주소로 묶여있기 때문입니다.

해결법: 현재 원격 주소를 SSH 포맷으로 변경합니다.

git remote -v (현재 주소 확인)
git remote set-url origin git@github.com:사용자아이디/저장소이름.git

⚠️ 문제 3: 회사나 학교 방화벽으로 22번 포트가 막혔을 때!
Connection timed out이 뜬다면 보안 방화벽이 SSH 기본 포트(22)를 차단한 것입니다. 이럴 땐 ~/.ssh/config 파일을 열고 깃허브 접속 포트를 웹 표준 포트인 443번 포트로 변경해 주면 말끔히 뚫립니다.

 

실전 예시: 맥북 교체 후 3분 만에 SSH 복구한 이야기 📚

실제로 제가 얼마 전 새로운 맥북으로 기기를 교체하고 신나게 새 프로젝트를 push하려다가 인증 거부를 겪었던 실제 사례를 공유해 드릴게요. 여러분도 기기를 바꿨을 때 이 순서대로만 따라 하시면 3분 만에 복구가 끝납니다.

사례 주인공의 상황

  • 기존 환경: 인텔 맥북에서 SSH 키로 편하게 사용 중이었음
  • 발생 상황: M-시리즈 신형 맥북으로 마이그레이션 후 push 시 publickey 거부 발생

해결 과정

1) 신규 단말기에 맞춰 ssh-keygen -t ed25519 -C "sangkwon@dev.com"로 새 키 생성

2) pbcopy < ~/.ssh/id_ed25519.pub로 복사 후 GitHub 웹 Settings에 ‘MacBook-Air-M3’ 이름으로 추가

3) 터미널에 ssh -T git@github.com 명령어를 입력하여 정상 핸드셰이크 확인

최종 결과

– 출력 메시지: Hi username! You’ve successfully authenticated… 성공 확인

– 이후 토큰 입력 한 번 없이 즉시 git push 완벽 성공!

이처럼 기기마다 고유한 SSH 키를 생성하여 등록해 두면, 나중에 특정 노트북을 분실하거나 교체했을 때 해당 키만 GitHub 웹에서 삭제해 주면 되므로 보안 관리 측면에서도 아주 우수하답니다.

 

마무리: 핵심 내용 요약 📝

오늘 배운 핵심을 가볍게 되짚어볼까요? SSH 키는 토큰 만료 스트레스 없이 영구적이고 안전하게 Git 작업을 할 수 있도록 도와주는 개발자의 필수 무기입니다. 처음 터미널을 다룰 땐 조금 낯설 수 있지만, 생성부터 등록까지 차근차근 따라 해보면 5분도 채 걸리지 않는답니다.

혹시 따라 하시다가 터미널에 예상치 못한 에러 문구가 뜨거나 막히는 단계가 있다면 주저하지 마시고 댓글로 질문 남겨주세요~ 같이 머리 맞대고 시원하게 해결해 드릴게요! 여러분의 쾌적한 코딩 라이프를 응원합니다. 😊

💡

GitHub SSH 키 3줄 요약 카드

✨ 표준 키 생성: ssh-keygen -t ed25519 (RSA보다 빠르고 안전한 차세대 표준)
📊 키 등록 주의점: 반드시 .pub 확장자의 공개키만 GitHub 웹 Settings에 붙여넣기
🧮 핵심 연결 점검 공식:

ssh -T git@github.com ➔ ‘successfully authenticated’ 확인

👩💻 오류 즉시 탈출: eval “$(ssh-agent -s)” && ssh-add로 키를 에이전트에 재등록

토큰 갱신 없이 영구적인 자동 인증을 누려보세요!

자주 묻는 질문 ❓

Q: SSH 키를 생성할 때 Passphrase(암호)는 무조건 설정해야 하나요?
A: 필수는 아닙니다. 개인 노트북이고 편리하게 자동 로그인을 원하신다면 엔터를 두 번 눌러 비밀번호 없이 비워둘 수 있습니다. 다만 공용 PC나 분실 위험이 있는 환경에서는 암호를 설정하시는 것을 권장합니다.

Q: 구형 RSA 알고리즘 대신 Ed25519를 써야 하는 이유는 무엇인가요?
A: Ed25519는 타원곡선 암호화 기법(EdDSA)을 사용하여 RSA 4096-bit 이상의 보안성을 제공하면서도 키 길이가 짧고 처리 속도가 훨씬 빠르기 때문입니다. 현재 GitHub 공식 문서에서도 최우선으로 권장하고 있습니다.

Q: 컴퓨터를 포맷하거나 다른 노트북을 쓰면 새로 키를 만들어야 하나요?
A: 네, 기기마다 새로운 SSH 키 쌍을 생성하여 GitHub에 추가로 등록하시는 것이 가장 안전하고 편리합니다. 기존 컴퓨터의 개인키를 USB로 옮기는 것보다 새 기기에서 발급받는 것이 보안상 훨씬 안전합니다.

Q: SSH 키를 등록했는데도 계속 비밀번호를 입력하라는 창이 뜹니다. 왜 그럴까요?
A: 로컬 Git 저장소의 리모트 URL이 여전히 HTTPS로 설정되어 있을 가능성이 높습니다. 터미널에 git remote -v를 입력해 확인해 보시고, HTTPS로 되어 있다면 git remote set-url origin git@github.com:... 명령어로 SSH 주소로 변경해 주세요.

Q: 실수로 .pub가 없는 비밀키(Private Key)를 외부에 노출했다면 어떻게 해야 하나요?
A: 비밀키가 외부에 노출되었다면 즉시 GitHub 웹 설정의 ‘SSH and GPG keys’ 메뉴에서 해당 키를 삭제(Delete)하시고, 로컬 컴퓨터에서도 키 파일을 지운 뒤 새롭게 생성하여 등록하셔야 합니다.