맥 깃허브 SSH 키 생성 후 연결 안될 때 — 딱 정리

맥에서 깃허브 저장소에 push나 pull을 시도할 때마다 자꾸 비밀번호를 물어보거나, 아예 SSH 연결이 안 된다는 메시지가 뜨면서 작업이 막힌 경험이 있으실 겁니다.

이 문제는 로컬 환경과 깃허브 서버 간에 안전하고 영구적인 인증 방식, 즉 SSH 키가 제대로 설정되지 않았기 때문입니다.

이 글에서는 맥에서 SSH 키를 생성하고 깃허브에 등록하여 SSH 연결 문제를 단 5단계로 해결하고, 더 이상 비밀번호를 입력하지 않고 원활하게 작업하는 방법을 명확히 설명합니다.

SSH, 왜 필요한가? 반복되는 비밀번호 입력 문제 해결

깃허브와 같은 원격 저장소에 접근할 때, 대부분은 HTTPS 방식이나 SSH 방식을 사용합니다. HTTPS 방식은 사용자 이름과 비밀번호를 매번 입력해야 하는 번거로움이 있습니다. 특히 복잡한 비밀번호를 사용하거나 보안 정책에 따라 자주 변경해야 할 경우, 작업 흐름이 끊기기 쉽습니다. 이런 반복적인 인증 과정은 개발 생산성을 저해하는 주요 원인 중 하나입니다.

SSH(Secure Shell)는 이러한 불편함을 해소하고 더 강력한 보안을 제공하는 방법입니다. SSH는 로컬 컴퓨터에 생성된 ‘개인 키’와 깃허브에 등록된 ‘공개 키’를 사용하여 서로를 인증합니다. 마치 자물쇠와 열쇠처럼, 개인 키는 사용자만이 가지고 있고 공개 키는 누구에게나 보여줄 수 있습니다. 이 방식을 사용하면 한 번 설정으로 비밀번호 입력 없이 안전하게 깃허브에 접근할 수 있게 됩니다.

Photo by RealToughCandy.com on Pexels

맥에서 SSH 키 생성 및 설정하기 — 단 5단계로 끝내기

이제 맥에서 깃허브 연결을 위한 SSH 키를 직접 생성하고 설정하는 과정을 살펴보겠습니다. 이 과정은 총 5단계로 구성되며, 단계별로 정확히 따라 하시면 문제 없이 키 생성을 완료할 수 있습니다. 이미 SSH 키를 가지고 있다면 이 단계를 건너뛰고 바로 키 확인 단계로 넘어가도 좋습니다.

1. 기존 SSH 키 확인 — 터미널을 열고 ls -al ~/.ssh 명령어를 입력해 기존 키가 있는지 확인합니다. id_rsa, id_ed25519 등의 파일이 보인다면 기존 키가 있는 것입니다. 없다면 다음 단계로 진행합니다.
2. 새 SSH 키 생성 — ssh-keygen -t ed25519 -C "your_email@example.com" 명령어를 사용하여 키를 생성합니다. 여기서 "your_email@example.com"은 깃허브 계정에 등록된 이메일 주소를 사용합니다. 파일 저장 경로를 묻는 메시지가 나오면 기본 경로(~/.ssh/id_ed25519)를 사용하는 것이 일반적이며, passphrase는 선택 사항입니다. 보안 강화를 위해 설정하는 것을 권장하지만, 매번 입력해야 하는 번거로움이 생길 수 있습니다.
3. SSH 에이전트 시작 — SSH 에이전트는 개인 키를 메모리에 로드하여 비밀번호 없이 SSH 연결을 가능하게 합니다. eval "$(ssh-agent -s)" 명령어를 입력하여 에이전트를 시작합니다.
4. SSH 키 에이전트에 추가 — ssh-add -K ~/.ssh/id_ed25519 명령어를 사용하여 방금 생성한 개인 키를 SSH 에이전트에 추가합니다. 만약 passphrase를 설정했다면 이 단계에서 입력해야 합니다.
5. SSH 설정 파일(config) 생성 — ~/.ssh/config 파일을 생성하거나 편집하여 SSH 에이전트가 자동으로 실행되고 키를 불러오도록 설정합니다.

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

   Host github.com은 깃허브에 연결할 때 이 설정을 사용하겠다는 의미입니다. AddKeysToAgent yes와 UseKeychain yes는 맥의 키체인과 연동하여 한 번 입력한 passphrase를 기억하게 하는 설정입니다. IdentityFile은 사용할 개인 키의 경로를 지정합니다. 이 설정 파일을 저장한 후에는 터미널을 다시 시작하는 것이 좋습니다.

Photo by Christina Morillo on Pexels

깃허브에 SSH 공개 키 등록 및 연결 확인

로컬 맥 환경에 SSH 키 생성을 완료했다면, 이제 이 키의 공개 부분(Public Key)을 깃허브 계정에 등록하여 인증을 가능하게 해야 합니다. 이 과정은 깃허브 웹사이트에서 단 몇 분 안에 쉽게 진행할 수 있습니다.

1. SSH 공개 키 복사 — 터미널에서 cat ~/.ssh/id_ed25519.pub 명령어를 입력하여 공개 키의 내용을 확인하고, 전체 내용을 복사합니다. id_ed25519.pub 파일은 일반 텍스트 파일이므로, 복사 시 주의하여 모든 문자를 빠짐없이 복사해야 합니다.
2. 깃허브에 SSH 키 등록 — 웹 브라우저를 열고 깃허브에 로그인합니다.
   • 우측 상단 프로필 아이콘 클릭 > Settings (설정)
   • 왼쪽 사이드바에서 “SSH and GPG keys” 선택
   • “New SSH key” 또는 “Add SSH key” 버튼 클릭
   • “Title” 필드에 맥북, 개인용 등 키를 구분할 수 있는 이름을 입력합니다.
   • “Key” 필드에 복사한 공개 키 내용을 붙여넣습니다.
   • “Add SSH key” 버튼을 클릭하여 등록을 완료합니다.
3. SSH 연결 테스트 — 모든 설정이 올바르게 되었는지 확인하기 위해 터미널에서 ssh -T git@github.com 명령어를 실행합니다. 처음 연결 시에는 호스트의 신뢰 여부를 묻는 메시지가 나타날 수 있습니다. yes를 입력하고 엔터를 누르면 됩니다. “Hi [username]! You’ve successfully authenticated, but GitHub does not provide shell access.”와 같은 메시지가 보인다면, SSH 연결이 성공적으로 이루어진 것입니다.

SSH 연결이 여전히 안될 때 — 3가지 핵심 점검 사항

모든 단계를 정확히 따랐다고 생각했는데도 SSH 연결이 제대로 되지 않아 답답할 수 있습니다. 이런 경우 대부분은 몇 가지 설정을 놓쳤거나 오타가 발생했을 가능성이 높습니다. 다음 3가지 핵심 점검 사항을 통해 문제를 신속하게 파악하고 해결할 수 있습니다.

1. ~/.ssh/config 파일 설정 확인 — 가장 흔한 오류 중 하나는 설정 파일의 오타나 누락입니다. IdentityFile 경로가 올바른지, Host github.com이 정확히 지정되었는지 다시 확인합니다. 특히 Host는 깃 클론 시 사용하는 URL에서 도메인 부분(예: git@github.com:user/repo.git의 github.com)과 일치해야 합니다.
2. SSH 에이전트 및 키 추가 상태 확인 — ssh-agent가 제대로 실행 중인지, 그리고 개인 키가 에이전트에 추가되었는지 확인해야 합니다. 터미널에서 ssh-add -l 명령어를 입력했을 때, 추가된 키 목록이 나타나야 합니다. 만약 아무것도 나타나지 않는다면 eval "$(ssh-agent -s)"와 ssh-add -K ~/.ssh/id_ed25519 명령어를 다시 실행해 보세요.
3. 깃허브에 등록된 공개 키 일치 여부 확인 — 로컬에서 복사한 공개 키와 깃허브에 등록된 키가 완벽하게 일치하는지 다시 한 번 검증해야 합니다. 간혹 복사 과정에서 누락되거나 다른 키를 복사하는 실수가 발생하기도 합니다. 깃허브 계정 설정에서 등록된 키의 내용을 다시 확인하고, 로컬의 cat ~/.ssh/id_ed25519.pub 결과와 비교해 보세요. 한 글자라도 다르면 연결이 실패합니다.

위 3가지 점검 사항을 꼼꼼히 확인하면 대부분의 SSH 연결 문제를 해결할 수 있습니다. 만약 여전히 문제가 해결되지 않는다면, 터미널에서 ssh -vT git@github.com 명령어를 실행하여 자세한 연결 로그를 확인하고 어떤 단계에서 오류가 발생하는지 파악하는 것이 좋습니다.