[Git & SSH] SSH 키 생성 및 원격 저장소 연동하기

이번 글에서는 SSH 키를 활용하여 GitHub 원격 저장소에 안전하게 접속하는 방법을 정리하였습니다. 기본적으로 GitHub에 코드를 push하거나 pull할 때 HTTPS 방식을 사용할 수도 있지만, SSH 키를 설정하면 매번 ID/PW 를 입력할 필요 없이 빠르고 안전하게 GitHub과 연동할 수 있습니다. 

SSH 키를 생성하는 방법부터 GitHub 에 등록하고 사용하는 과정까지 단계별로 정리하였습니다. 🚀

📂 목차

 

---

1. SSH 키가 뭐지?

SSH(Secure Shell) 키는 서버(또는 Git 원격 저장소)와 클라이언트(사용자 PC)가 암호학적으로 안전하게 통신하기 위한 인증 방식 중 하나입니다.

• Public Key(공개키): 누구나 가질수 있는 키 (원격 서버나 GitHub에 등록됨) - ⭐공개키를 ~/.ssh/id_rsa.pub -> 이후 원격서버 authorized_keys에 추가
• Private Key(개인키): 소유자만 가지고 있어야 하는 키 (로컬 컴퓨터에 저장됨)
• 암호화 복호화 방식
  • 공개키로 암호화한 데이터는 개인키로만 복호화 가능
  • 개인키로 암호호한 데이터는 공개키로만 복호화 가능
  • SSH 인증에서는 주로 개인키로 서명한 데이터를 공개키를 이용해 검증하는 방식이 사용됨

공개키와 개인키 이 둘을 짝으로 사용하면, 비밀번호 없이도 안전하게 접속할 수 있습니다.

 

GitHub  SSH 인증 과정의 흐름

 

[1] SSH 키 쌍 생성

사용자가 ssh-keygen을 실행하면 개인키(Private Key)와 공개키(Public Key) 한 쌍이 생성됨

 

[2] 공개키를 Github에 등록

사용자는 공개키(Public Key)를 GitHub에 등록

 

[3] SSH를 이용한 GitHub 인증과정

사용자가 git push 명령을 실행하면:

1. 로컬 PC는 개인키(Private Key)로 서명한 데이터를  GitHub  서버로 보냄
2. GitHub 서버는 등록된 공개키(Public Key)로 서명 검증
3. 검증이 성공하면 push 요청을 승인

[4] 인증 후 git push 성공! 🚀

서명이 검증되면 GitHub가 요청을 받아들여, push 작업이 성공적으로 완료됩니다.

 

2. SSH 키 생성하기

Windows 기준으로 Git Bash에서 기존에 SSH 키 쌍이 있는지 확인합니다.

cd ~/.ssh
ls

 

id_rsa 및 id_rsa.pub 와 같은 파일이 보인다면 이미 SSH 키 쌍이 있습니다. 그런 경우 5단계로 바로 이동합니다.

🔑 SSH 키 쌍이 없다면 다음 명령을 실행하여 새키를 생성합니다.

ssh-keygen

 

 

옵션으로

• -t rsa: 생성할 키 타입
• -C "your_email@gmail.com": 키 식별용 코멘트(예: GitHub 계정 이메일)

위 명령을 입력하면 경로와 비밀번호(패스프레이즈) 등을 묻는데, 엔터만 누르면 기본경로(~/.ssh/id_rsa)와 빈 패스프레이즈 진행해도 무방합니다.

 

생성이 완료되면, ~/.ssh 폴더에 다음 두 파일이 생깁니다:

• id_rsa: (개인키, 외부에 유출되면 안됨)
• id_rsa.pub: (공개키, 이 파일 내용을 복사해 GitHub 등 서버에 등록)

 

3. SSH 에이전트(ssh-agent)에 SSH 키 등록하기

SSH 에이전트란?

SSH 에이전트는 SSH 개인키(private Key)를 관리하여, 매번 비밀번호(passphrase)를 입력하지 않고도 안전하게 인증할 수 있도록 돕는 프로그램입니다.

 

3.1 SSH 키를 등록하는 이유

• SSH 키를 사용해 원격 서버(GitHub, GitLab, AWS 등)에 연결할 때, 매번 키 파일을 입력할 필요없이 자동 인증할 수 있습니다.
• SSH 키에 패스프레이즈를 설정한 경우, SSH 에이전트가 한 번만 비밀번호를 입력한 뒤 세션을 유지할 수 있습니다.
• SSH 키를 여러 개 사용할 경우, 특정 서버/저장소에 맞게 자동으로 선택할 수 있습니다.

 

3.2 SSH 키를 SSH 에이전트에 등록하는 방법

 

1️⃣ SSH 에이전트 실행

 

💠 Windows (Git Bash, PowerShell)

eval $(ssh-agent -s)

 

💠  macOS / Linux

eval "$(ssh-agent -s)"

 

→ pid(프로세스 ID)가 표시되면 SSH 에이전트가 정상적으로 실행된 것입니다.

---

2️⃣ SSH 키를 에이전트에 등록

이제 로컬 SSH키를 SSH 에이전트에 추가합니다.

ssh-add ~/.ssh/id_rsa

 

✔️ 이제 SSH 키가 SSH 에이전트에 등록되었으며, 원격 서버(GitHub, GitLab 등)와 연결할 때 자동으로 사용됩니다.

---

 

3️⃣ SSH 에이전트에 등록된 키 확인

ssh-add -l

 

✔️ 여기에 원하는 키가 나오면 SSH 에이전트에 정상적으로 등록된 것입니다.

 

4. 공개키(GitHub)에 등록하기

SSH 키를 생성하면 개인키(id_rsa)와 공개키(id_rsa.pub)가 짝을 이루게 됩니다. 이제 id_rsa.pub(공개키) 파일의 내용을 GitHub 계정에 등록해야 합니다.

 

1. id_rsa.pub 내용 복사

• 해당 파일을 메모장이나 VS Code에서 텍스트 전체를 복사 또는 cat id_rsa.pub 전체 복사합니다.
• 예) ssh-rsa AAAAB3NzaC1yc2EAAAA... your_email@gmail.com

2. GitHub 웹 사이트 접속 > 우측 상단 프로필 아이콘 클릭 > Settings

 

3. 왼쪽 메뉴에서 SSH and GPG keys 클릭 > New SSH key 버튼

 

4. 공개키 붙여 넣기

• Title: "개인 PC" 등 식별하기 편한 이름
• key: 방금 복사한 공개키 붙여넣기
• Add SSH key 버튼으로 저장

 

5. SSH  공개키 (id_rsa.pub)를 GitHub에 업로드하였습니다. 이제 GitHub의 SSH 주소만 알고 있으면 로그인 정보를 입력하지 않아도 즉시 해당 저장소에 접속이 가능합니다. 위 과정을 마치면 GitHub에서 SSH 연결이 활성화되어, 앞으로 원격 저장소에 git push/pull을 할 때 암호 입력 없이 빠르게 진행할 수 있습니다.

 

 

 

5. SSH 연결 테스트

공개키 등록이 제대로 되었는지 테스트해 봅니다:

ssh -T git@github.com

 

정상적으로 Hi <username>! You've successfully authenticated, but GitHub does not provide shell access. 메시지가 나오면 설정 완료

만약 Permission denied (publickey). 등의 에러가 뜬다면,

• 공개키가 올바르게 등록되었는지
• SSH 에이전트(ssh-agent)가 동작중인지
• 개인키의 경로가 맞는지 확인합니다.

 

5.1 공개키가 올바르게 등록되었는지 확인

SSH 키가 올바르게 GitHub(또는 원격 서버)에 등록되었는지 확인하려면, 다음 단계를 수행합니다.

 

✅ (1) SSH 키 목록 확인

현재 사용중인  SSH 키가 있는지 확인하려면:

ls -al ~/.ssh

 

출력 내용

✔️ id_rsa.pub 파일이 존재 해야합니다.

❌ 없다면 SSH 키를 다시 생성해야합니다. (ssh-keygen  사용)

 

✅ (2) 공개키의 내용을 확인하고 GitHub에 등록했는지 체크

다음 명령어를 사용해 공개키 파일을 확인하고 복사합니다:

cat ~/.ssh/id_rsa.pub

 

🚀 이 내용을 복사하여 GitHub에 등록했는지 확인:

1. GitHub에 로그인
2. 우측 상단 프로필 > Settings > SSH and GPG keys
3. 등록된 SSH키가 있는지 확인(없다면 새로 추가)
4. 키를 잘못 등록한 경우, 삭제 후 새 키 등록

📌 GitHub에서 "Keep my email address private" 옵션이 활성화되어 있으면 noreply.github.com주소로 설정된 SSH키가 필요할 수도 있습니다.

 

5.2 SSH 에이전트(ssh-agent)가 동작중인지 확인

SSH  에이전트가 실행중인지 확인하려면 다음 명령어 입력:

eval $(ssh-agent -s)

 

✔️ pid 값이 표시되면 SSH 에이전트가 실행 중입니다.

❌ 실행되지 않는다면 다시 실행해야 합니다.

 

5.3 개인키의 경로가 맞는 확인

 

만약 SSH 에이전트에 등록했는데도 Permission denied (publickey) 오류가 발생한다면, Git이 SSH 키를 올바른 경로에서 찾고 있는지 확인해야합니다.

✅ (1) SSH 설정 확인

cat ~/.ssh/config

✔️ IdentityFile에 설정된 SSH 키가 올바른지 확인합니다.

❌ 경로가 다르다면, 올바른 SSH 키를 사용하도록 설정해야 합니다.

 

수정하려면:

nano ~/.ssh/config

필요한 경우 아래 내용을 추가 또는 수정합니다:

Host github.com
	HostName github.com
	IdentityFile ~/.ssh/id_rsa_hyonie
	User hyonie

파일을 저장한 후 다음 명령어를 실행하여 변경 사항을 적용합니다:

ssh-add ~/.ssh/id_rsa

 

모든 설정이 올바르게 되어 있는지 다시 SSH 연결 테스트를 합니다. 

 

5. Git 리포지토리 설정

이제 로컬 프로젝트를 GitHub에 연동해봅니다. 예시로 새 git 리포지토리를 만든 뒤 SSH 주소를 복사합니다.

 

 

1. 로컬 프로젝트 폴더로 이동

cd ~/Desktop/my-blog

 

2. Git 초기화(이미 git init 되어 있다면 생략)

git init
git add .
git commit -m "Initial commit"

 

3. 원격 추가

git remote add origin git@github.com:your-username/my-blog.git
git remote -v  // 연결 확인

 

4. 첫 푸시

git push -u origin main

이제 매번 ID/PW 입력 없이 SSH 키 인증으로 푸시가 가능합니다.

 

6. 마무리

정리하자면,

1. SSH 키 생성(ssh-keygen)
2. SSH 에이전트에 사용
3. 공개키를 GitHub에 등록
4. SSH 연결 확인 (ssh -T git@github.com)
5. 원격 제포지토리 주소를 SSH 형태로 추가 (git remote add origin git@..)

이 과정을 통해 매번 비밀번호를 입력할 필요 없이 편리하고 안전하게 버전 관리를 진행할 수 있습니다. 

💠 여러 대의 컴퓨터에서 작업한다면, 각각 SSH 키를 만들어 GitHub에 추가해도 됩니다.
💠 회사 내부에서 별도 서버를 사용할 때도 동일한 방식으로 SSH 키를 등록 후 접근하면 편리합니다.