Git을 처음 사용할 때, SSH 키가 왜 필요한지 이해하기 어려울 수 있다. 나도 처음엔 HTTPS로 clone 받으면 그만이라고 생각했다. 그런데 push할 때마다 비밀번호를 입력하라는 창이 뜨고, 2021년 8월부터는 GitHub이 비밀번호 기반 HTTPS 인증을 완전히 차단하면서 상황이 달라졌다. Personal Access Token을 쓰는 방법도 있지만, 토큰을 관리하고 갱신하는 것 자체가 번거롭다. 결국 SSH 키를 한 번 제대로 설정해두면 인증 문제에서 해방된다. 이 글에서는 Mac 환경에서 SSH 키 생성부터 GitHub 연동, 그리고 실제로 부딪히는 에러까지 전부 다룬다.
📑 목차
SSH vs HTTPS — 왜 SSH를 써야 하는가
GitHub 저장소를 clone할 때 두 가지 프로토콜을 선택할 수 있다. HTTPS와 SSH이다. 표면적으로는 같은 결과를 내지만, 인증 방식과 사용 경험이 크게 다릅니다. 관련 내용은 Mac Node.js 버전 충돌 해결법에서도 다루고 있다.
| 항목 | HTTPS | SSH |
|---|---|---|
| 인증 방식 | Personal Access Token (PAT) | 공개키/개인키 쌍 |
| push 시 비밀번호 | 매번 입력 (또는 credential helper) | 불필요 (ssh-agent가 처리) |
| 토큰 만료 | PAT에 유효기간 있음 | 키에 만료 없음 (직접 폐기) |
| 방화벽 제한 | 443 포트 (대부분 통과) | 22 포트 (간혹 차단됨) |
| Clone URL 형태 | https://github.com/user/repo.git | [email protected]:user/repo.git |
내가 SSH를 선호하는 가장 큰 이유는 단순하다. 한 번 설정하면 더 이상 인증에 대해 신경 쓸 일이 없기 때문이다. PAT를 사용하면 토큰이 만료될 때마다 새로 발급받아야 하고, 여러 머신에서 동기화하는 것도 귀찮다. SSH 키는 머신별로 한 번만 등록하면 된다.
기존에 HTTPS로 clone한 저장소를 SSH로 전환하는 것도 간단하다.
# 현재 remote URL 확인
git remote -v
# origin https://github.com/username/my-repo.git (fetch)
# origin https://github.com/username/my-repo.git (push)
# SSH URL로 변경
git remote set-url origin [email protected]:username/my-repo.git
# 변경 확인
git remote -v
# origin [email protected]:username/my-repo.git (fetch)
# origin [email protected]:username/my-repo.git (push)Ed25519 SSH 키 생성하기
SSH 키를 생성할 때 알고리즘을 선택해야 한다. 과거에는 RSA 4096이 표준이었지만, 현재 GitHub은 Ed25519를 권장한다. Ed25519는 키 길이가 짧으면서도 RSA 4096과 동등하거나 더 나은 보안 수준을 제공한다. 서명 속도도 빠릅니다.
터미널을 열고 다음 명령어를 실행한다.
# Ed25519 키 생성
ssh-keygen -t ed25519 -C "[email protected]"
# 실행하면 아래와 같은 대화가 진행됩니다
# Generating public/private ed25519 key pair.
# Enter file in which to save the key (/Users/username/.ssh/id_ed25519):
# 기본 경로 그대로 Enter를 누릅니다
# Enter passphrase (empty for no passphrase):
# passphrase를 입력합니다 (권장)
# Enter same passphrase again:
# 동일하게 다시 입력합니다
# 결과 출력 예시:
# Your identification has been saved in /Users/username/.ssh/id_ed25519
# Your public key has been saved in /Users/username/.ssh/id_ed25519.pub
# The key fingerprint is:
# SHA256:AbCdEfGhIjKlMnOpQrStUvWxYz1234567890abcd [email protected]
# The key's randomart image is:
# +--[ED25519 256]--+
# | .o+=+.o |
# | . o.=oo . |
# | + B.+. |
# | o X O .. |
# | . S B = o |
# | . + = + . |
# | o . o . |
# | . . . |
# | E |
# +----[SHA256]-----+passphrase 설정을 강력히 권장한다. passphrase 없이 생성한 키는, 누군가 여러분의 Mac에 접근하면 곧바로 GitHub 계정까지 접근할 수 있다는 뜻이다. passphrase를 설정하면 키 파일이 유출되더라도 추가 보호 계층이 존재한다. 뒤에서 설명할 macOS Keychain 연동을 하면 매번 입력하지 않아도 되므로 불편함도 없다.
생성이 끝나면 ~/.ssh 디렉터리에 두 개의 파일이 만들어진다.
# 생성된 파일 확인
ls -la ~/.ssh/
# 출력 예시:
# drwx------ 6 username staff 192 Apr 2 10:30 .
# drwxr-x---+ 32 username staff 1024 Apr 2 10:30 ..
# -rw------- 1 username staff 464 Apr 2 10:30 id_ed25519 # 개인키 (절대 공유하면 안 됨)
# -rw-r--r-- 1 username staff 104 Apr 2 10:30 id_ed25519.pub # 공개키 (GitHub에 등록할 키)
# 공개키 내용 확인
cat ~/.ssh/id_ed25519.pub
# ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG... [email protected]만약 ~/.ssh 디렉터리가 없는 상태에서 시작한다면, ssh-keygen 실행 시 자동으로 생성된다. 별도로 mkdir를 할 필요는 없다.
ssh-agent에 키 등록 및 macOS Keychain 연동
SSH 키를 생성했다고 바로 사용할 수 있는 건 아닙니다. ssh-agent라는 백그라운드 프로세스에 키를 등록해야 한다. ssh-agent는 메모리에 개인키를 보관하고, SSH 연결 시 자동으로 인증을 처리한다.
# ssh-agent를 백그라운드에서 시작
eval "$(ssh-agent -s)"
# 출력: Agent pid 12345
# 키를 agent에 추가 (macOS Keychain에도 저장)
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
# Enter passphrase for /Users/username/.ssh/id_ed25519:
# Identity added: /Users/username/.ssh/id_ed25519 ([email protected])
# 등록된 키 목록 확인
ssh-add -l
# 256 SHA256:AbCdEfGhIjKlMnOpQrStUvWxYz... [email protected] (ED25519)--apple-use-keychain 플래그가 핵심이다. 이 옵션을 사용하면 passphrase가 macOS Keychain에 저장되어, Mac을 재시작해도 passphrase를 다시 입력할 필요가 없다. macOS Monterey(12.0) 이전 버전에서는 -K 플래그를 사용해야 한다. 본인의 macOS 버전을 확인하자.
# macOS 버전 확인
sw_vers
# ProductName: macOS
# ProductVersion: 15.3
# BuildVersion: 24D2026
# Monterey 이전 버전인 경우
ssh-add -K ~/.ssh/id_ed25519여기서 주의할 점이 있다. 터미널을 새로 열 때마다 ssh-agent가 실행 중인지 보장되지 않다. 이 문제는 다음 섹션의 ~/.ssh/config 설정으로 해결한다.
~/.ssh/config 파일 설정
사실 이 파일이 SSH 연동의 핵심이다. config 파일을 작성해두면 ssh-agent가 자동으로 키를 로드하고, passphrase도 Keychain에서 자동으로 가져온다. 매번 eval "$(ssh-agent -s)"를 실행할 필요가 없어진다.
# config 파일이 없다면 생성
touch ~/.ssh/config
# 편집기로 열기 (nano, vim, 또는 VS Code)
nano ~/.ssh/config아래 내용을 입력한다.
# ~/.ssh/config
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519
AddKeysToAgent yes
UseKeychain yes각 설정의 의미를 정리하면 다음과 같다.
| 옵션 | 설명 |
|---|---|
Host github.com |
이 설정이 적용될 호스트명. SSH 연결 시 매칭됨 |
HostName github.com |
실내 접속할 서버 주소 |
User git |
GitHub SSH 접속 시 사용하는 사용자명 (항상 git) |
IdentityFile |
사용할 개인키 경로 |
AddKeysToAgent yes |
키를 자동으로 ssh-agent에 추가 |
UseKeychain yes |
macOS Keychain에서 passphrase를 자동으로 읽어옴 |
UseKeychain yes는 macOS 전용 옵션이다. Linux에서는 이 줄을 제거해야 한다. 그렇지 않으면 Bad configuration option: usekeychain 에러가 발생한다. 나는 처음에 이걸 몰라서 회사 Ubuntu 서버에서 30분 정도 헤맸던 기억이 있다.
파일 권한도 확인한다. SSH는 권한이 너무 열려 있으면 키 사용을 거부한다.
# config 파일 권한 설정 (소유자만 읽기/쓰기)
chmod 600 ~/.ssh/config
# 개인키 권한 확인 (반드시 600이어야 함)
chmod 600 ~/.ssh/id_ed25519
# 공개키는 644여도 무방
chmod 644 ~/.ssh/id_ed25519.pub
# .ssh 디렉터리 자체는 700
chmod 700 ~/.sshGitHub에 공개키 등록하기
이내 생성한 공개키를 GitHub 계정에 등록할 차례이다. 먼저 공개키 내용을 클립보드에 복사한다.
# 공개키를 클립보드에 복사 (macOS)
pbcopy < ~/.ssh/id_ed25519.pub
# 복사되었는지 확인하고 싶다면
pbpaste
# ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG... [email protected]이후 GitHub 웹사이트에서 다음 단계를 진행한다.
- GitHub에 로그인한다.
- 우측 상단 프로필 아이콘 > Settings를 클릭한다.
- 왼쪽 사이드바에서 SSH and GPG keys를 클릭한다.
- New SSH key 버튼을 클릭한다.
- Title에 키를 식별할 수 있는 이름을 입력한다. (예:
MacBook Pro 2024 - 개인) - Key type은 Authentication Key를 선택한다.
- Key 필드에 복사한 공개키를 붙여넣다.
- Add SSH key를 클릭한다.
Title은 나중에 어떤 머신의 키인지 구분하기 위한 것이므로 명확하게 작성하는 게 좋다. 나는 기기명 + 연도 + 용도 형식으로 짓다. 키를 여러 대 등록하다 보면 어떤 게 어떤 머신인지 헷갈리는 경우가 생기기 때문이다.
GitHub CLI를 사용한다면 터미널에서 바로 등록할 수도 있다.
# GitHub CLI로 SSH 키 등록 (gh가 설치되어 있어야 함)
gh ssh-key add ~/.ssh/id_ed25519.pub --title "MacBook Pro 2024 - 개인"
# 등록된 키 목록 확인
gh ssh-key list
# TITLE ID KEY ADDED
# MacBook Pro 2024 - 개인 12345678 ssh-ed25519 AAAAC3NzaC1... 2026-04-02SSH 연결 테스트
모든 설정이 끝났으면 실제로 GitHub에 SSH 연결이 되는지 확인한다.
# GitHub SSH 연결 테스트
ssh -T [email protected]
# 처음 접속 시 fingerprint 확인 메시지가 나옵니다
# The authenticity of host 'github.com (20.200.245.247)' can't be established.
# ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
# This key is not known by any other names.
# Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
# 성공 시 출력:
# Hi username! You've been authenticated, but GitHub does not provide shell access.
# 만약 디버그 정보가 필요하다면 -v 옵션 사용
ssh -vT [email protected]Hi username! 메시지가 나오면 성공이다. 이내 SSH URL로 clone, push, pull 모두 비밀번호 없이 수행할 수 있다.
실제로 저장소를 clone해서 push까지 테스트해보겠다.
# SSH URL로 clone
git clone [email protected]:username/test-repo.git
# Cloning into 'test-repo'...
# remote: Enumerating objects: 42, done.
# remote: Counting objects: 100% (42/42), done.
# Receiving objects: 100% (42/42), 8.12 KiB | 4.06 MiB/s, done.
cd test-repo
# 파일 수정 후 push
echo "SSH test" >> README.md
git add README.md
git commit -m "test: SSH 연결 확인"
git push origin main
# Enumerating objects: 5, done.
# Counting objects: 100% (5/5), done.
# Writing objects: 100% (3/3), 287 bytes | 287.00 KiB/s, done.
# To github.com:username/test-repo.git
# a1b2c3d..e4f5g6h main -> main비밀번호 프롬프트 없이 push가 완료된다. 이게 SSH의 편리함이다.
트러블슈팅 — 자주 발생하는 에러와 해결법
Permission denied (publickey)
SSH 설정에서 가장 흔하게 마주치는 에러이다. 원인은 여러 가지이므로 순서대로 확인한다.
# 에러 메시지 예시
ssh -T [email protected]
# [email protected]: Permission denied (publickey).
# 1단계: ssh-agent에 키가 등록되어 있는지 확인
ssh-add -l
# The agent has no identities. <-- 이 메시지가 나오면 키가 없는 것
# 키가 없다면 다시 추가
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
# 2단계: GitHub에 올바른 공개키가 등록되어 있는지 확인
ssh -vT [email protected] 2>&1 | grep "Offering"
# debug1: Offering public key: /Users/username/.ssh/id_ed25519 ED25519 SHA256:...
# 이 fingerprint가 GitHub에 등록된 키와 일치하는지 대조
# 3단계: 파일 권한 확인
ls -la ~/.ssh/
# id_ed25519 은 -rw------- (600) 이어야 함
# id_ed25519.pub 은 -rw-r--r-- (644) 이어야 함
# 권한이 잘못되어 있다면 수정
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pubGitHub 계정이 여러 개인 경우
회사 계정과 개인 계정을 동시에 사용하는 경우, 하나의 SSH 키로는 두 계정을 모두 처리할 수 없다. 각 계정별로 별도의 키를 생성하고, ~/.ssh/config에서 Host alias로 구분한다.
# 개인용 키 생성
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519_personal
# 회사용 키 생성
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519_work
# 두 키 모두 agent에 등록
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_personal
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_work~/.ssh/config를 다음과 같이 설정한다.
# ~/.ssh/config — 다중 GitHub 계정 설정
# 개인 계정
Host github.com-personal
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_personal
AddKeysToAgent yes
UseKeychain yes
# 회사 계정
Host github.com-work
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_work
AddKeysToAgent yes
UseKeychain yesclone할 때 Host alias를 사용한다.
# 개인 계정 저장소 clone
git clone [email protected]:my-personal/my-project.git
# 회사 계정 저장소 clone
git clone [email protected]:company-org/company-project.git
# 각 저장소의 git config에서 사용자 정보도 분리
cd company-project
git config user.name "회사이름"
git config user.email "[email protected]"
# 연결 테스트
ssh -T [email protected]
# Hi personal-username! You've been authenticated...
ssh -T [email protected]
# Hi work-username! You've been authenticated...이 방식의 핵심은 Host 값을 실내 도메인이 아닌 alias로 설정하되, HostName은 실내 도메인인 github.com을 유지하는 것이다. SSH 클라이언트는 Host 값으로 config 블록을 매칭하고, 실내 연결은 HostName 주소로 한다.
Could not open a connection to your authentication agent
ssh-agent가 실행되지 않았을 때 발생한다.
# 에러 메시지
ssh-add ~/.ssh/id_ed25519
# Could not open a connection to your authentication agent.
# 해결: ssh-agent 시작
eval "$(ssh-agent -s)"
# Agent pid 54321
# 다시 키 추가
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
# ~/.ssh/config에 AddKeysToAgent yes를 설정해두면
# 이후에는 이 과정이 자동으로 처리됩니다WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED
GitHub의 SSH 호스트 키가 변경되었을 때 나타난다. 2023년 3월에 GitHub이 실제로 RSA 호스트 키를 교체한 적이 있어서, 이 경고가 정당한 경우도 있다. 하지만 무작정 무시하면 안 된다.
# 경고 메시지 예시
# @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
# @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
# @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
# GitHub의 현재 공식 fingerprint 확인
# https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints
# 기존 known_hosts에서 github.com 항목 제거
ssh-keygen -R github.com
# # Host github.com found: line 3
# /Users/username/.ssh/known_hosts updated.
# 다시 연결하면 새 fingerprint 확인 후 등록
ssh -T [email protected]
# The authenticity of host 'github.com (20.200.245.247)' can't be established.
# ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
# Are you sure you want to continue connecting (yes/no)? yes이 fingerprint가 GitHub 공식 문서에 게시된 값과 일치하는지 반드시 확인한 후 yes를 입력해야 한다. 확인 없이 수락하면 중간자 공격(MITM)에 노출될 수 있다.
22번 포트가 차단된 환경
회사나 학교 네트워크에서 SSH 기본 포트(22)가 차단된 경우, GitHub은 443 포트를 통한 SSH 접속을 지원한다.
# ~/.ssh/config — 443 포트로 SSH 접속
Host github.com
HostName ssh.github.com
Port 443
User git
IdentityFile ~/.ssh/id_ed25519
AddKeysToAgent yes
UseKeychain yes# 443 포트 접속 테스트
ssh -T -p 443 [email protected]
# Hi username! You've been authenticated, but GitHub does not provide shell access.HostName이 github.com이 아니라 ssh.github.com인 점에 주의한다. 이 설정을 해두면 clone이나 push 시에는 기존과 동일하게 [email protected]:... URL을 사용할 수 있다. SSH 클라이언트가 config를 보고 자동으로 443 포트와 ssh.github.com 호스트를 사용한다.
SSH 키 설정은 처음에 다소 번거로워 보이지만, 한 번 제대로 해두면 Git 작업이 확실히 쾌적해진다. 특히 여러 저장소를 오가며 작업하는 경우, 인증 없이 자유롭게 push/pull할 수 있다는 것은 생산성에 적지 않은 차이를 만듭니다. 이 글의 설정을 그대로 따라하면 대부분의 환경에서 문제없이 동작할 것이다. 자세한 내용은 GitHub SSH 공식 문서를 참고하자.