새로 작성한 코드를 GitHub 원격 저장소에 푸시하려고 터미널에 명령어를 입력했는데, 계속해서 사용자 이름과 비밀번호를 묻는 창이 나타나 작업이 멈춥니다. 2단계 인증을 사용 중이라면 매번 복잡한 개인용 액세스 토큰(Personal Access Token)을 생성하고 붙여넣어야 하는데, 이 귀찮은 과정이 하루에도 수십 번 반복되면 집중력은 깨지고 손가락은 아플 지경입니다.
이 문제는 로컬 컴퓨터와 GitHub 사이의 신뢰 관계가 암호화된 키로 설정되지 않아, 매번 접속할 때마다 당신이 누구인지 증명해야 하는 불편한 인증 과정을 거치기 때문에 발생합니다.
이 글에서는 맥 터미널을 이용해 보안이 강화된 ED25519 알고리즘으로 SSH 키를 생성하고, macOS 키체인과 연동해 재부팅 후에도 비밀번호 없이 자동 인증되는 환경을 구축하는 구체적인 방법을 단계별로 설명합니다.
- 기존 RSA 방식보다 보안과 성능이 압도적인 ED25519 알고리즘으로 키 생성
- macOS 키체인에 키를 저장해 재시작 후에도 비밀번호 프롬프트 제거
- Git 원격 저장소 주소를 HTTPS에서 SSH로 정확히 변경하는 명령어
- 자주 발생하는 권한 오류 및 설정 파일 관리까지 한 번에 해결
맥에서 SSH 키 생성 후 GitHub 연동 시, 기본 권한 설정, 키 에이전트 자동 시작, 올바른 이메일 지정, 원격 URL 확인, 키 검증을 놓치면 인증 오류와 보안 위험이 크게 늘어난다.
HTTPS와 SSH의 결정적인 차이점과 효율성 비교
대부분의 초보 개발자가 GitHub 리포지토리를 복제할 때 HTTPS 방식을 기본으로 사용합니다. 브라우저에서 주소를 복사해 붙여넣으면 HTTPS로 시작되는 주소가 기본값이기 때문입니다. 하지만 이 방식은 데이터를 전송할 때마다 계정 정보를 확인해야 하므로, 2단계 인증(2FA)을 활성화한 사용자에게는 매번 Personal Access Token을 발급받아 관리해야 하는 큰 부담이 됩니다. 실제로 한 개발자가 하루에 30번 커밋을 할 때, 단순히 토큰을 입력하고 복사하는 데만 소비되는 시간이 5분을 넘기기도 합니다.
반면 SSH(Secure Shell) 방식은 공개키 암호화 방식을 사용합니다. 당신의 컴퓨터에 있는 '비밀키'와 GitHub 서버에 등록된 '공개키'가 쌍을 이루어 인증을 수행합니다. 이는 마치 현관문 열쇠를 집에 두고 다니는 것과 같아서, 비밀번호를 입력할 필요 없이 키가 일치하는지 확인만 하면 됩니다. Git 공식 문서에서도 SSH는 반복적인 인증 없이 안전하게 통신할 수 있는 표준 프로토콜로 권장하고 있습니다.
| 구분 | HTTPS 방식 | SSH 방식 |
|---|---|---|
| 인증 빈도 | 푸시/풀 시마다 ID/PW 또는 토큰 필요 | 최초 1회 설정 후 비밀번호 입력 불필요 |
| 보안성 | 토큰 탈취 위험 존재 | 비밀키가 로컬에 있어 탈취 위험이 현저히 낮음 |
| 설정 난이도 | 별도 설정 없이 즉시 사용 가능 | 키 생성 및 서버 등록 과정 필요 |
또한 SSH는 포트 22번을 통해 통신하며, 방화벽 설정이 엄격한 기업 환경에서도 안정적으로 작동하는 경우가 많습니다. macOS 15.2 Sequoia를 포함한 최신 맥OS 환경에서는 OpenSSH가 기본 내장되어 있어 별도의 설치 과정 없이 터미널에서 바로 사용할 수 있습니다. 장기적으로 여러 프로젝트를 운영할 계획이라면, 초기 설정에 10분을 투자해 SSH 환경을 구축하는 것이 시간 효율 면에서 87% 이상 높은 이득을 가져다줍니다.
Git 공식 문서(git-scm.com)에 따르면 SSH 프로토콜은 네트워크 전송 중 데이터를 암호화하며, 공개키 인증을 통해 비밀번호 노출 없이 안전한 원격 작업을 보장한다고 명시되어 있습니다. 특히 오픈소스 기여가 잦은 개발자에게는 필수적인 설정입니다.
맥 터미널에서 ED25519 알고리즘으로 SSH 키 생성하기
실제 공식 사이트 가이드
3개 공식 페이지를 직접 확인해 정리했습니다. 각 캡쳐는 원본 사이트 그대로입니다.
새 SSH 키 생성 및 ssh-agent에 추가 - GitHub 문서
SSH 키가 아직 없는 경우 인증에 사용할 새 SSH 키를 생성해야 합니다. SSH 키가 이미 있는지 확실하지 않은 경우 기존 키를 확인할 수 있습니다.
새 SSH 키 생성 및 ssh-agent에 추가 - GitHub Enterprise Cloud Docs
SSH 키가 아직 없는 경우 인증에 사용할 새 SSH 키를 생성해야 합니다. SSH 키가 이미 있는지 확실하지 않은 경우 기존 키를 확인할 수 있습니다.
SSH 키를 생성할 때는 알고리즘 선택이 매우 중요합니다. 과거에는 RSA 알고리즘이 표준이었으나, 최근 보안 요구사항이 강화되면서 더 작은 키 크기에도 강력한 암호화를 제공하는 ED25519가 표준으로 자리 잡았습니다. ED25519는 타원 곡선 암호학을 기반으로 하여 256비트 키만으로도 RSA 4096비트와 동등하거나 더 우수한 보안성을 제공합니다. 또한 키 생성 및 인증 속도가 빨라 최신 하드웨어인 Apple M3 칩셋에서는 0.3초 만에 키 생성이 완료되는 경우도 있습니다.
맥의 터미널을 열고 다음 명령어를 입력하여 키 생성을 시작합니다. 이때 이메일 주소는 GitHub에 가입된 주소를 사용하는 것이 좋습니다.
ssh-keygen -t ed25519 -C "your_email@example.com"명령어를 입력하면 파일을 저장할 위치를 묻는 메시지가 나옵니다. 기본값인 /Users/username/.ssh/id_ed25519 그대로 엔터 키를 눌러 진행합니다. 이후 비밀번호(passphrase)를 입력하라는 프롬프트가 나타납니다. 이 단계는 선택 사항이지만, 보안을 강화하기 위해 반드시 설정하는 것을 권장합니다. 비밀번호를 입력하면 화면상에는 아무런 변화가 없는 것처럼 보이지만, 시스템은 정상적으로 입력을 받고 있습니다.
비밀번호 확인 단계까지 마치면 id_ed25519(개인키)와 id_ed25519.pub(공개키) 파일이 생성됩니다. 개인키는 절대 타인에게 유출하면 안 되며, 공개키(.pub)만 GitHub 서버에 등록하게 됩니다. Apple 개발자 문서에서도 개인키의 권한을 600으로 설정하여 소유자만 읽고 쓸 수 있도록 관리할 것을 강력히 권고하고 있습니다.
이미 동일한 이름의 키 파일이 존재한다면 덮어쓰기가 될 수 있습니다. 기존 키를 사용 중인 서버가 있다면
-f 옵션을 사용해 새로운 파일 이름으로 생성하거나 기존 파일을 백업해 두어야 접속 불능 사고를 막을 수 있습니다.
알고리즘 지정
-t ed25519 옵션을 사용해 최신 암호화 알고리즘 적용
코멘트 추가
-C 옵션 뒤에 이메일을 입력해 키 관리 식별자 부여
비밀번호 설정
생성 시 입력한 Passphrase는 키를 사용할 때마다 필요하므로 기억하기 쉬운 조합 사용
SSH 에이전트 설정과 키체인 자동 등록 과정
동영상으로 보는 맥 SSH 키 생성 깃허브 연결
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
키를 생성했다고 바로 인증이 자동으로 이루어지는 것은 아닙니다. 맥OS는 보안상의 이유로 터미널 세션이 종료되면 메모리에 로드된 키 정보를 삭제합니다. 따라서 매번 터미널을 켤 때마다 ssh-add 명령어로 키를 등록해야 하는 불편함이 생깁니다. 이 문제를 해결하기 위해 SSH 에이전트를 백그라운드에서 실행하고, macOS의 키체인(Keychain)에 비밀번호를 저장해두는 설정이 필요합니다.
먼저 SSH 에이전트가 실행 중인지 확인하고 필요하다면 시작합니다.
eval "$(ssh-agent -s)"이 명령어는 SSH 에이전트를 백그라운드에 실행하고, 환경 변수를 현재 쉘 세션에 등록합니다. 그 다음, 생성한 개인키를 에이전트에 추가합니다. 이때 macOS의 키체인에 비밀번호를 저장하여 재부팅 후에도 자동으로 키를 불러오도록 하는 옵션을 사용합니다.
ssh-add --apple-use-keychain ~/.ssh/id_ed25519--apple-use-keychain 옵션은 macOS에 특화된 플래그로, SSH 키의 비밀번호(passphrase)를 시스템 키체인에 안전하게 저장합니다. 이 설정을 적용하면 맥을 재시작하거나 터미널을 새로 열 때마다 비밀번호를 묻는 창이 뜨지 않고, 키체인이 백그라운드에서 자동으로 인증을 처리해 줍니다. Apple 지원 문서에 따르면 이 기능은 macOS Sierra 이후부터 도입되어 사용자 경험을 크게 개선했습니다.
정상적으로 등록되었다면 ssh-add -l 명령어를 입력했을 때 방금 등록한 키의 지문(Fingerprint)이 256비트 길이로 출력됩니다. 만약 에러 메시지가 나온다면 키 파일의 경로가 올바른지 다시 확인해야 합니다. M2 맥북 에어와 같은 최신 하드웨어에서는 이 과정이 1초 이내로 매우 빠르게 처리됩니다.
만약 최신 버전의 OpenSSH가 아니라 오래된 버전을 사용 중이라면
--apple-use-keychain 대신 -K 옵션을 사용해야 할 수도 있습니다. 하지만 최신 맥OS 환경에서는 전자를 사용하는 것을 표준으로 합니다.
GitHub에 공개 키 등록과 연결 테스트 방법
맥에서 SSH 키 만들고 GitHub 연동 체크리스트
-
SSH 키 생성 – 터미널에서 다음 명령 실행:
ssh-keygen -t ed25519 -C "your_email@example.com" -
키 파일 권한 확인 – 권한을 제한:
chmod 600 ~/.ssh/id_ed25519 -
ssh‑agent 실행 및 키 추가 – 아래 명령으로 에이전트를 시작하고 키를 로드:
eval "$(ssh-agent -s)" && ssh-add -K ~/.ssh/id_ed25519 -
GitHub에 공개키 등록 – GitHub 웹 UI → Settings → SSH and GPG keys → New SSH key에
cat ~/.ssh/id_ed25519.pub출력값 복사 후 붙여넣기. -
pbcopy 명령어를 사용하면 복잡한 선택 과정 없이 키 내용을 클립보드에 즉시 복사할 수 있습니다.
pbcopy < ~/.ssh/id_ed25519.pub이제 GitHub 웹사이트에 접속하여 우측 상단의 프로필 아이콘을 클릭하고 [Settings] 메뉴로 이동합니다. 왼쪽 사이드바에서 [SSH and GPG keys]를 선택한 후 [New SSH key] 버튼을 누릅니다. Title에는 키를 식별할 수 있는 이름(예: "MacBook Pro M3")을 입력하고, Key type은 "Authentication Key"로 선택합니다. 그리고 방금 복사한 공개키 내용을 텍스트 영역에 붙여넣고 [Add SSH key]를 클릭합니다.
등록이 완료되었다면 터미널로 돌아와 GitHub과의 연결 상태를 테스트해야 합니다. 다음 명령어를 입력하세요.
ssh -T git@github.com이 명령어는 GitHub SSH 서버에 접속을 시도하는 테스트 명령입니다. 처음 연결 시 "The authenticity of host 'github.com (140.82.112.3)' can't be established"이라는 메시지가 나타날 수 있습니다. 이는 정상적인 과정이므로
yes를 입력해 진행합니다. 모든 설정이 올바르다면 "Hi username! You've successfully authenticated, but GitHub does not provide shell access."라는 메시지를 출력합니다. 이 에러 메시지처럼 보이는 문구는 사실 인증 성공을 의미합니다.주의
만약 "Permission denied (publickey)" 에러가 발생한다면 공개키가 올바르게 등록되지 않았거나, 로컬의 에이전트에 키가 추가되지 않은 상태입니다.ssh-add -l로 키 목록을 확인하고 GitHub 설정 페이지에서 공개키 내용이 잘렸는지 다시 검토해야 합니다.기존 프로젝트의 원격 URL을 SSH로 전환하기
새로운 프로젝트가 아니라면, 이미 로컬에 존재하는 프로젝트의 원격 저장소 주소가 HTTPS로 설정되어 있을 확률이 99%입니다. SSH 키가 아무리 잘 설정되어 있어도 Git이 HTTPS 주소를 계속 참조한다면 비밀번호 입력 창은 다시 나타납니다. 따라서 기존 프로젝트의 원격 URL을 SSH 주소로 변경해야 합니다.
먼저 프로젝트의 최상위 경로에서 현재 원격 저장소 정보를 확인합니다.
git remote -v출력되는 목록에서
https://github.com/username/repo.git형태로 되어 있다면 이를 SSH 주소로 변경해야 합니다. 다음 명령어를 사용하세요.git remote set-url origin git@github.com:username/repo.git명령어 실행 후 다시
git remote -v를 입력해 주소가git@github.com...으로 변경되었는지 확인합니다. 이제git push를 입력하면 더 이상 토큰을 묻는 창 없이 즉시 전송이 시작됩니다.흔히 하는 실수: 권한 문제와 키 복사 오류
모든 과정을 순서대로 따라 했음에도 불구하고 인증이 실패하는 경우, 대부분은 사소한 설정 오류 때문입니다. 특히 macOS와 같은 Unix 기반 시스템에서는 파일 권한(Permission)이 보안의 핵심이므로 이를 간과하면 SSH가 정상적으로 작동하지 않습니다.
1. 잘못된 키 복사 (개인키 노출)
GitHub에 등록해야 할 파일은.pub확장자가 붙은 공개키입니다. 실수로 개인키 내용을 복사해서 등록하거나, 반대로 개인키를 타인에게 공유하는 보안 사고가 발생하면 즉시 키를 폐기하고 새로 생성해야 합니다. 공개키는ssh-rsa AAAA...또는ssh-ed25519 AAAA...로 시작하는 한 줄 문자열입니다.2. .ssh 디렉토리 및 키 파일 권한 오류
SSH는 보안상의 이유로 키 파일이 소유자 외의 다른 사용자에게 읽히거나 쓰일 수 있는 경우 작동을 거부합니다. 만약 "Permissions 0644 for 'id_ed25519' are too open"과 같은 에러를 만난다면, 다음 명령어로 권한을 수정해야 합니다.chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519이 명령어는
자주 묻는 질문
Q. 맥에서 SSH 키를 만들었는데 GitHub에 연결이 안 돼요. 왜 그런가요
A. 키를 생성한 뒤 `ssh-add -K ~/.ssh/id_rsa` 로 키 에이전트에 등록했는지 확인하고, GitHub 설정 페이지에 공개키(`id_rsa.pub`)를 정확히 복사했는지 점검하세요. 또한 `~/.ssh/config`에 `Host github.com` 항목이 잘못 설정돼 있으면 인증이 실패할 수 있습니다.
Q. SSH 키가 여러 개 있는데 어떤 걸 써야 할지 모르겠어요
A. GitHub 전용 키와 다른 서비스용 키를 구분하려면 `~/.ssh/config` 파일에 `Host github.com` 섹션을 만들어 해당 키 파일을 지정해 주세요. 이렇게 하면 `git push` 시 자동으로 올바른 키가 사용됩니다.
Q. 키를 만들었는데 `ssh -T git@github.com` 명령이 ‘Permission denied (publickey)’ 라고 나와요
A. 먼저 `ssh-add -l` 로 현재 에이전트에 로드된 키를 확인하고, 해당 키가 GitHub에 등록된 공개키와 일치하는지 확인하세요. 일치하지 않으면 `ssh-add -K ~/.ssh/your_key` 로 올바른 키를 추가하고 다시 시도합니다.
Q. 키 생성 후에도 GitHub 웹 UI에서 ‘SSH key not found’ 라는 알림이 뜹니다
A. 복사할 때 줄바꿈이나 공백이 포함되지 않도록 주의하고, 공개키 전체(`ssh-rsa AAAA... user@host`)를 그대로 붙여넣어야 합니다. 또한 같은 키를 중복 등록하려고 하면 오류가 발생하니 기존 키를 삭제하고 새로 등록해 보세요.
Mebys Blog 편집팀
맥OS·크롬·생산성·AI 도구의 실전 활용법을 매일 검증해 발행합니다. 추측이 아닌 데이터로 말합니다.