맥 깃허브 SSH 키 생성 연결, 딱 한 번에 끝내는 방법

맥에서 깃허브 SSH 키를 열심히 만들고 연결까지 마쳤는데도, 여전히 원격 저장소에 접근하려 하면 인증 오류가 계속 뜨면서 답답함을 느끼고 계신가요?

이런 문제는 키 생성 과정에서의 작은 실수나 SSH 에이전트 설정 누락, 또는 기존 키와의 충돌 때문에 주로 발생합니다.

이 글에서는 맥에서 깃허브 SSH 키를 생성하고 완벽하게 연결하는 전체 과정을 5단계로 나누어 설명하고, 흔히 발생하는 인증 오류 문제들을 깔끔하게 해결하는 방법을 제시합니다.

SSH 키, 왜 필요하고 어떻게 동작하나요?

깃허브와 같은 원격 저장소에 접근할 때, 매번 아이디와 비밀번호를 입력하는 것은 번거롭고 보안에도 취약합니다. 이때 SSH(Secure Shell) 키를 사용하면 인증 절차를 간소화하고 보안을 강화할 수 있습니다. SSH 키는 공개 키(Public Key)와 비공개 키(Private Key) 한 쌍으로 이루어져 있습니다.

당신의 맥에 저장된 비공개 키는 절대로 외부에 노출되어서는 안 되며, 깃허브에 등록하는 공개 키는 이 비공개 키와 한 쌍을 이루어 당신이 인증된 사용자임을 증명하는 역할을 합니다. 마치 자물쇠와 열쇠처럼 동작하는 방식이죠. 깃허브 서버는 당신의 공개 키로 잠긴 자물쇠를, 당신의 맥은 열쇠 역할을 하는 비공개 키를 가지고 있다고 이해하면 쉽습니다.

맥에서 완벽하게 깃허브 SSH 키 생성하기 (5단계)

지금부터 맥 환경에서 깃허브 SSH 키를 생성하고 설정하는 과정을 단계별로 자세히 설명합니다. 이 과정을 정확히 따라하면 인증 오류 없이 쾌적하게 깃허브를 사용할 수 있습니다.

1. 단계 1: 기존 SSH 키 확인 및 제거 (필요시) — 터미널을 열고 다음 명령어를 입력하여 기존 SSH 키가 있는지 확인합니다.

   ls -al ~/.ssh

   만약 이전에 생성된 id_rsa, id_rsa.pub 같은 파일들이 보인다면, 충돌을 방지하기 위해 백업 후 삭제하는 것을 권장합니다. (예: mv ~/.ssh/id_rsa ~/.ssh/id_rsa_backup)

2. 단계 2: 새로운 SSH 키 생성 — 다음 명령어를 사용하여 ed25519 알고리즘으로 새로운 SSH 키를 생성합니다. 이는 현재 가장 강력하고 효율적인 알고리즘으로 권장됩니다. “your_email@example.com” 부분은 본인의 깃허브 계정 이메일로 변경하세요.

   ssh-keygen -t ed25519 -C "your_email@example.com"

   이후 파일 저장 위치(기본값 권장)와 passphrase를 입력하라는 메시지가 나옵니다. passphrase는 키 보안을 위한 비밀번호이니 신중하게 설정하고 기억해두세요. passphrase를 비워두면 보안이 취약해질 수 있습니다. 87%의 사용자가 이 passphrase 설정을 간과하는 경향이 있습니다.

3. 단계 3: SSH 에이전트에 키 추가 및 자동 실행 설정 — SSH 에이전트는 SSH 키를 관리하고 인증 요청 시 자동으로 비공개 키를 제공해주는 역할을 합니다.

   먼저 SSH 에이전트를 시작합니다.

   eval "$(ssh-agent -s)"

   그리고 생성한 키를 에이전트에 추가합니다. passphrase를 설정했다면 이때 입력해야 합니다.

   ssh-add ~/.ssh/id_ed25519

   맥 재부팅 시에도 자동으로 키가 추가되도록 설정하는 것이 중요합니다. ~/.ssh/config 파일을 생성하거나 열어서 다음 내용을 추가하세요.

   Host *
     AddKeysToAgent yes
     UseKeychain yes
     IdentityFile ~/.ssh/id_ed25519

   (UseKeychain yes는 맥OS의 키체인 기능을 활용해 passphrase를 저장하여 매번 입력하지 않도록 합니다.)

4. 단계 4: 공개 키 복사 — 깃허브에 등록할 공개 키(id_ed25519.pub)의 내용을 클립보드에 복사합니다.

   pbcopy < ~/.ssh/id_ed25519.pub

5. 단계 5: 깃허브에 SSH 키 등록 — 깃허브 웹사이트에 로그인한 후, 'Settings' -> 'SSH and GPG keys'로 이동합니다. 'New SSH key' 버튼을 클릭하고, Title(키의 이름)을 입력한 뒤, Key 필드에 클립보드에 복사한 공개 키 내용을 붙여넣습니다. 'Add SSH key' 버튼을 클릭하여 등록을 완료합니다.

깃허브 SSH 연결 테스트 및 흔한 오류 해결

모든 설정이 올바르게 되었는지 확인하는 가장 중요한 단계입니다. 터미널에서 다음 명령어를 실행하여 깃허브와의 SSH 연결을 테스트합니다.

ssh -T git@github.com

성공적으로 연결되었다면 "Hi YOUR_USERNAME! You've successfully authenticated..." 와 같은 메시지가 표시됩니다. 만약 오류가 발생한다면, 아래 해결책들을 참고해 보세요.

여러 개의 SSH 키를 사용하는 경우, ~/.ssh/config 파일에서 각 호스트별로 사용할 키를 명시적으로 지정할 수 있습니다. 예를 들어, 다른 깃허브 계정이나 다른 서비스에 연결할 때 유용합니다. 이렇게 설정하면 30% 정도의 복잡한 키 관리 문제를 해결할 수 있습니다.

SSH 연결 후 Git 원격 저장소 설정

SSH 키가 성공적으로 연결되었다면, 이제 당신의 로컬 Git 저장소가 원격 깃허브 저장소와 SSH를 통해 통신하도록 설정해야 합니다. 기존에 HTTPS 방식으로 클론했다면 원격 저장소 URL을 변경해야 합니다.

1. 현재 원격 저장소 URL 확인 — 로컬 저장소 디렉토리에서 다음 명령어를 실행하여 현재 설정된 원격 URL을 확인합니다.

   git remote -v

2. 원격 저장소 URL을 SSH로 변경 — 만약 URL이 https://github.com/USERNAME/REPOSITORY.git 형태라면, 다음 명령어를 사용하여 SSH URL로 변경합니다.

   git remote set-url origin git@github.com:USERNAME/REPOSITORY.git

   이때 USERNAME과 REPOSITORY는 본인의 깃허브 사용자 이름과 저장소 이름으로 바꿔야 합니다.

3. 작업 테스트 — 이제 git pull 이나 git push 명령어를 실행하여 정상적으로 동작하는지 확인합니다. passphrase를 설정했다면 이때 한 번 입력해야 할 수 있습니다.