맥 SSH 키 생성 후 깃허브 연결 오류? 한 번에 해결!

맥에서 SSH 키를 생성해 GitHub에 연결하려는데, 매번 비밀번호를 입력해야 하거나 연결 오류가 계속 발생해 답답하셨을 겁니다.

이 문제는 SSH 키가 올바르게 설정되지 않았거나 GitHub에 등록하는 과정에서 흔히 발생하는 설정 오류 때문입니다.

이 글에서는 맥 환경에서 SSH 키를 생성하고 GitHub에 완벽하게 연결하는 5단계 과정을 상세히 안내하며, 발생할 수 있는 문제점까지 한 번에 해결해 드립니다.

SSH 키는 왜 필요하고, 어떻게 작동할까요?

GitHub와 같은 원격 저장소에 접근할 때, 대부분은 사용자 이름과 비밀번호를 사용하는 HTTPS 방식을 떠올립니다. 하지만 이 방식은 매번 인증 정보를 입력해야 하거나 개인 접근 토큰(PAT)을 발급받아 관리해야 하는 번거로움이 있습니다. 또한, 보안 측면에서도 민감한 정보를 자주 노출하는 위험이 존재합니다.

SSH(Secure Shell) 키는 이러한 불편함과 보안 문제를 해결해 줍니다. SSH 키는 강력한 암호화를 기반으로 사용자를 인증하며, 한 번 설정해두면 비밀번호 없이 안전하게 GitHub와 통신할 수 있게 합니다. 이는 공개키와 비공개키 한 쌍으로 이루어져 있는데, 공개키는 GitHub에 등록하고 비공개키는 로컬 시스템에 보관하여 서로를 인증하는 방식입니다.

Photo by Pixabay on Pexels

맥에서 새로운 SSH 키 생성하기 (5단계)

GitHub 연결 오류의 대부분은 SSH 키 생성 과정에서 발생하는 작은 실수나 누락 때문입니다. 아래 5단계 과정을 차분히 따라 하면 안전하고 정확하게 SSH 키를 생성할 수 있습니다.

먼저, 터미널을 열고 기존에 사용하던 SSH 키가 있는지 확인하는 것이 좋습니다. 만약 이미 키가 있다면 백업 후 새로운 키를 생성하거나, 기존 키를 활용하는 방법도 고려할 수 있습니다. 이 글에서는 가장 최신 보안 표준을 따르는 `ed25519` 알고리즘을 사용한 키 생성 방법을 안내합니다.

1. 터미널 열기 — 맥 화면 우측 상단 돋보기 아이콘(Spotlight 검색)을 클릭하거나 Command + Spacebar를 눌러 ‘터미널’을 입력하고 실행합니다.
2. 기존 SSH 키 확인 — 터미널에 ls -al ~/.ssh 명령어를 입력하여 기존에 생성된 SSH 키 파일이 있는지 확인합니다. 만약 id_rsa나 id_ed25519와 같은 파일이 보인다면, 백업 후 삭제하거나, 충돌을 피하기 위해 새로운 키를 다른 이름으로 생성할 수 있습니다.
3. 새로운 SSH 키 생성 — 다음 명령어를 입력하여 새로운 SSH 키를 생성합니다. "your_email@example.com" 부분은 본인의 GitHub 계정 이메일 주소로 변경하세요.
   ssh-keygen -t ed25519 -C "your_email@example.com"
   엔터를 누르면 파일 저장 경로를 묻는데, 기본 경로(~/.ssh/id_ed25519)를 그대로 사용하는 것이 좋습니다. 패스프레이즈(비밀번호)를 입력하라는 메시지가 나오면 공백으로 두거나 강력한 비밀번호를 설정할 수 있습니다. 보안 강화를 위해 패스프레이즈를 설정하는 것을 권장하며, 이는 256비트 암호화로 키를 보호합니다.
4. SSH 에이전트에 키 추가 — SSH 키를 생성했어도 매번 비밀번호를 입력해야 하는 경우가 있습니다. 이는 SSH 에이전트에 키가 추가되지 않았기 때문입니다. 다음 두 명령어를 순서대로 실행하여 SSH 에이전트를 실행하고 새로운 키를 추가합니다.
   eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
   만약 패스프레이즈를 설정했다면, 이때 한 번 입력해야 합니다. 이 과정을 통해 SSH 에이전트가 키를 기억하여 이후에는 비밀번호 입력 없이 인증됩니다.
5. config 파일 설정 — SSH 에이전트가 시스템 재시작 후에도 키를 자동으로 로드하도록 ~/.ssh/config 파일을 설정합니다. 터미널에서 다음 명령어를 실행하여 파일을 열고 내용을 추가합니다.
   nano ~/.ssh/config
   파일 내용에 다음을 추가한 후 Ctrl+X, Y, Enter를 눌러 저장합니다.

   Host github.com
     HostName github.com
     User git
     IdentityFile ~/.ssh/id_ed25519

생성된 SSH 키를 GitHub에 등록하기

이제 맥에서 SSH 키 생성을 마쳤으니, 이 키의 공개 부분을 GitHub 계정에 등록해야 합니다. GitHub에 공개키를 등록해야만 GitHub 서버가 여러분의 로컬 시스템에서 보내는 인증 요청을 인식하고 통신을 허용합니다.

1. 공개키 복사 — 생성된 SSH 공개키는 .pub 확장자를 가집니다. 다음 명령어를 입력하여 공개키의 내용을 클립보드에 복사합니다.
   pbcopy < ~/.ssh/id_ed25519.pub
2. GitHub 접속 및 키 등록 — 웹 브라우저를 열어 GitHub에 로그인합니다.
   • GitHub 화면 우측 상단의 프로필 이미지를 클릭한 후 'Settings'로 이동합니다.
   • 왼쪽 사이드바에서 'SSH and GPG keys'를 클릭합니다.
   • 'New SSH key' 또는 'Add SSH key' 버튼을 클릭합니다.
   • 'Title' 필드에는 이 키를 식별할 수 있는 이름을 입력합니다 (예: 'My Mac Pro SSH Key').
   • 'Key' 필드에 클립보드에 복사해 두었던 공개키 내용을 붙여넣습니다.
   • 'Add SSH key' 버튼을 클릭하여 등록을 완료합니다.

연결 오류 진단 및 비밀번호 반복 입력 문제 해결

위의 단계를 모두 정확히 따랐음에도 불구하고 연결 오류가 발생하거나 여전히 비밀번호를 매번 입력해야 하는 경우가 있습니다. 대부분은 아래의 진단 과정을 통해 해결할 수 있습니다. 침착하게 각 단계를 점검해 보세요.

1. SSH 연결 테스트 — 가장 먼저 GitHub와의 SSH 연결이 정상적으로 이루어지는지 테스트해야 합니다. 터미널에 다음 명령어를 입력합니다.
   ssh -T git@github.com
   성공적으로 연결되었다면 Hi username! You've successfully authenticated와 같은 메시지가 출력됩니다. 만약 오류 메시지가 나온다면 다음 단계들을 확인해야 합니다.
2. config 파일 확인 — ~/.ssh/config 파일에 오타가 있거나 IdentityFile 경로가 잘못 지정된 경우가 많습니다. nano ~/.ssh/config 명령어로 파일을 다시 열어 위 5단계에서 추가했던 내용과 정확히 일치하는지 확인하세요.
3. SSH 에이전트 실행 확인 및 키 추가 — SSH 에이전트가 실행 중인지, 그리고 키가 제대로 추가되었는지 확인합니다.
   eval "$(ssh-agent -s)" (에이전트 실행)
   ssh-add -l (추가된 키 목록 확인)
   만약 키가 보이지 않는다면, ssh-add ~/.ssh/id_ed25519 명령어로 다시 추가해야 합니다.
4. SSH 키 파일 권한 확인 — SSH 키 파일의 권한이 너무 개방적이거나, 너무 제한적인 경우 문제가 발생할 수 있습니다. 비공개 키(id_ed25519)는 소유자만 읽고 쓸 수 있도록 600 권한으로, 공개 키(id_ed25519.pub)는 소유자만 쓰고 다른 사용자는 읽기만 가능하도록 644 권한으로 설정해야 합니다.
   chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

위의 4가지 점검 사항은 GitHub SSH 연결 문제의 99%를 해결할 수 있습니다. 각 단계를 확인하고 문제를 해결했다면, 다시 ssh -T git@github.com 명령어로 연결을 테스트해 보세요. 이제 원활한 GitHub 사용 환경을 경험할 수 있을 것입니다.