GitHub SSH 키 등록 가이드

GitHub 계정에 SSH 키를 등록하여 저장소를 복제하거나 인증할 때 매번 비밀번호를 입력하지 않는 방법을 안내합니다.

🚀 GitHub SSH 설정으로 이동 →

📋 개요

**SSH (Secure Shell)**는 네트워크를 통해 비밀번호를 보내지 않고도 안전한 인증을 제공하는 프로토콜입니다. SSH 키 쌍을 GitHub에 등록하면 자격 증명을 매번 입력하지 않고도 저장소를 복제, 풀, 푸시할 수 있습니다.

GitHub는 두 가지 유형의 SSH 키를 지원합니다:

• Ed25519 (권장) — 현대적이며 안전하고 키 크기가 작습니다
• RSA (4096비트) — 레거시 호환용, Ed25519가 지원되지 않는 환경에서만 사용하세요

🛠️ 설정 단계

1. 기존 SSH 키 확인

새 키를 생성하기 전에 이미 키가 있는지 확인합니다.

Linux / macOS / WSL:

ls -la ~/.ssh/

Windows (PowerShell):

Get-ChildItem $env:USERPROFILE\.ssh

id_ed25519, id_ed25519.pub, id_rsa, id_rsa.pub 파일이 있는지 확인합니다. 사용할 키 쌍이 이미 있으면 3단계로 건너뛰세요.

2. 새 SSH 키 생성

Ed25519 알고리즘을 사용해 새 SSH 키를 생성합니다 (권장).

Linux / macOS / WSL:

ssh-keygen -t ed25519 -C "<your-email@example.com>"

Windows (PowerShell):

ssh-keygen -t ed25519 -C "<your-email@example.com>"

키 파일 위치를 묻는 프롬프트에서 Enter를 눌러 기본값(~/.ssh/id_ed25519)을 적용합니다.

암호(passphrase)를 묻는 프롬프트에서는 안전한 암호를 입력하거나 Enter를 눌러 비워둘 수 있습니다. 암호를 사용하면 개인 키가 유출되더라도 추가 보안 계층이 적용됩니다.

3. 공개 키 확인 및 복사

공개 키를 표시하고 클립보드에 복사합니다.

Linux / macOS / WSL:

cat ~/.ssh/id_ed25519.pub

Windows (PowerShell):

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

공개 키는 ssh-ed25519 또는 ssh-rsa로 시작하고 이메일 주소로 끝납니다. 전체 출력을 선택하여 복사하세요.

⚠️ 보안 주의: 개인 키(id_ed25519 또는 id_rsa, .pub 없이)를 절대 공유하거나 게시하지 마세요. 공개 키(id_ed25519.pub)만 공유해도 안전합니다.

4. GitHub에 키 등록

1. GitHub에 로그인합니다
2. 프로필 사진 클릭 → Settings 클릭
3. 왼쪽 사이드바에서 SSH and GPG keys 클릭
4. New SSH key 클릭
5. Title 필드에 설명이 포함된 레이블을 입력합니다 (예: 내 노트북, 사무실 PC)
6. Key 필드에 공개 키를 붙여넣습니다
7. Add SSH key 클릭

5. 연결 테스트

SSH 키가 올바르게 등록되었는지 확인합니다.

ssh -T git@github.com

첫 연결 시 다음과 같은 경고가 표시될 수 있습니다:

The authenticity of host 'github.com (IP 주소)' can't be established.
RSA key fingerprint is SHA256:xxxxx.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

yes를 입력하고 Enter를 누르세요. 성공하면 다음 메시지가 표시됩니다:

Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.

6. SSH로 저장소 복제

연결을 확인한 후 SSH 주소를 사용하여 저장소를 복제합니다.

git clone git@github.com:<owner>/<repository>.git

<owner>를 저장소 소유자로, <repository>를 저장소 이름으로 대체하세요.

🔍 SSH 키 등록 확인

GitHub 계정에 등록된 모든 SSH 키를 목록으로 보려면:

1. Settings → SSH and GPG keys로 이동합니다
2. 제목과 생성 날짜와 함께 등록된 키 목록을 확인합니다

🩺 문제 해결

증상	원인	해결
Permission denied (publickey)	SSH 키가 등록되지 않았거나 잘못된 키 사용	공개 키가 GitHub에 등록되어 있는지 확인합니다. 올바른 개인 키를 사용하고 있는지 확인합니다.
ssh -T는 "successfully authenticated"라고 하지만 git 작업은 실패	키가 특정 저장소에 추가되지 않음	SSH 키가 해당 저장소에 대한 읽기/쓰기 권한이 있는지 확인합니다.
연결 시간 초과	포트 22를 차단하는 방화벽 또는 네트워크 문제	네트워크 설정을 확인하거나 HTTPS를 대신 사용합니다.
git@github.com: Permission denied	잘못된 원격지 URL 형식	원격지 URL에서 git@github.com:(콜론)을 사용하고 https://github.com/이 아닌지 확인합니다.
"Too many authentication failures"	키 시도 횟수가 많아 서버가 거부	ssh -vT git@github.com으로 디버깅하거나 -i ~/.ssh/id_ed25519로 키를 지정합니다.

🔒 보안 모범 사례

• 개인 키(id_ed25519 또는 id_rsa)를 절대 공유하지 마세요. 이슈, 이메일 첨부, 저장소 커밋에 포함하지 마세요.
• SSH 키 생성 시 암호(passphrase)를 사용하여 개인 키가 유출되더라도 보호하세요.
• 기기별로 고유한 SSH 키 사용 — 노트북, 데스크톱, 서버에 서로 다른 키를 등록하세요.
• 등록된 키 정기 감사 — 오래되거나 사용하지 않는 SSH 키는 GitHub 계정에서 제거하세요.
• 조직에서 중앙 집중식 키 관리가 필요한 경우 SSH 인증서 사용을 고려하세요.

📚 참조

• GitHub Docs: SSH 정보
• GitHub Docs: 새 SSH 키 생성
• GitHub Docs: 새 SSH 키 추가
• OpenSSH 문서

---

버전: 1.0 최종 업데이트: 2026-09-24 소스 파일: giipv3/public/help/github-ssh-key.ko.md