Git & GitHub 연동 및 SSH 설정 종합 가이드

맨날 까먹어서 올려둠

Git & GitHub 연동 및 SSH 설정 종합 가이드

이 문서는 로컬 개발 환경에서 Git 저장소를 초기화하고, SSH 키를 생성하여 GitHub 원격 저장소와 안전하고 편리하게 연동하는 전체 과정과 각 명령어의 옵션/플래그 상세 설명을 정리한 가이드입니다.

---

📌 전체 흐름 요약 (Cheatsheet)

단계	주요 작업	핵심 명령어
1단계	로컬 Git 초기화 & 브랜치 이름 변경	git init git branch -M main
2단계	사용자 이름 및 이메일 설정	git config user.name "YourName" git config user.email "your-email@example.com"
3단계	SSH 키 생성 & Agent 등록	ssh-keygen -t ed25519 -C "your-comment" ssh-add ~/.ssh/id_ed25519
4단계	GitHub에 공개키 등록	GitHub 웹사이트 설정 내 SSH Keys 추가
5단계	원격 저장소 연결 및 첫 푸시	git remote add origin git@github.com:username/repo.git git push -u origin main

---

1단계: 로컬 Git 저장소 초기화

작업 중인 프로젝트 폴더 루트에서 Git을 시작하고 기본 브랜치 이름을 설정합니다.

# 1. 현재 디렉토리를 로컬 Git 저장소로 초기화 (.git 폴더 생성)
git init

# 2. 기본 브랜치 이름을 master에서 main으로 강제 변경
git branch -M main

💡 옵션 설명

• -M (또는 --move --force): 브랜치 이름을 강제(Force)로 이동/변경(Move)하는 옵션입니다. 기존에 master로 생성된 기본 브랜치를 현대 표준 권장 사항인 main으로 깔끔하게 덮어씁니다.

---

2단계: 사용자 정보 설정 (git config)

커밋 내역에 기록될 작성자 정보를 설정합니다. 설정 정보가 없거나 틀리면 협업 시 추적이 어려워집니다.

① 전역 설정 (PC의 모든 Git 저장소에 공통 적용)

git config --global user.name "YourName"
git config --global user.email "your-email@example.com"

② 지역 설정 (현재 프로젝트 폴더에만 단독 적용)

git config user.name "YourName"
git config user.email "your-email@example.com"

③ 설정 확인 명령어

# 등록된 이름 조회
git config user.name

# 등록된 이메일 조회
git config user.email

[!WARNING]
자주 하는 실수 주의
Git 설정값 변경 시 Key(user.email)와 Value("your-email...") 사이에 등호(=)를 넣지 않고 공백(Space)으로 구분해야 정상 작동합니다.

• ❌ 잘못된 예: git config user.email=email@example.com
• ⭕ 올바른 예: git config user.email "email@example.com"

---

3단계: SSH Key 생성 및 에이전트 등록

매번 비밀번호나 Personal Access Token을 입력하지 않고 암호화 통신을 통해 안전하게 로그인 상태를 유지하도록 해줍니다.

① SSH 키 쌍 생성 (비밀키 + 공개키)

ssh-keygen -t ed25519 -C "your-comment-label"

• 명령어 입력 후 나타나는 경로 지정 및 패스프레이즈(비밀번호) 입력 프롬프트 3개는 모두 아무것도 입력하지 않고 Enter를 눌러 통과하면 기본 경로(~/.ssh/)에 비밀키(id_ed25519)와 공개키(id_ed25519.pub)가 생성됩니다.

② SSH 에이전트 구동 및 키 등록

# SSH Agent 서비스 가동
Start-Service ssh-agent

# 백그라운드 에이전트에 생성한 개인키 등록
ssh-add ~/.ssh/id_ed25519

💡 옵션 설명

• -t ed25519: Type(암호화 알고리즘 종류)을 지정하는 옵션입니다. ed25519는 현대적 타원곡선 알고리즘으로, 기존 rsa 방식에 비해 속도가 훨씬 빠르며 더 작은 크기로도 강력한 보안을 자랑합니다.
• -C "your-comment": Comment(주석) 옵션입니다. 공개키 파일 맨 끝에 붙는 식별용 메모입니다. 보통 이메일을 많이 쓰지만 "my-desktop", "personal-key" 등 식별하기 편한 고유 명칭을 자유롭게 기재해도 무관하며 생략할 수도 있습니다.

❓ SSH 에이전트 구동 및 키 등록은 왜 필요한가요?

SSH 에이전트(ssh-agent)는 "비밀키를 안전하게 보관하고 대신 서명해 주는 보안 비서" 역할을 합니다.

1. 비밀번호 캐싱 (편의성): SSH 키 생성 시 패스프레이즈(비밀번호)를 설정한 경우, 매번 git push/pull 때마다 비밀번호를 치지 않도록 메모리에 안전하게 기억해 줍니다.
2. 다중 키 자동 매칭: 업무용, 개인용 등 여러 개의 SSH 키를 교체하며 사용할 때 올바른 키를 자동으로 골라 연결해 줍니다.
3. 보안성 향상: 디스크의 실제 키 파일에 직접 접근하는 대신 에이전트가 중계 서명을 수행하므로 개인키 유출 방지에 좋습니다.

🚫 SSH 에이전트 과정이 필요 없는 경우

아래 조건에 모두 해당한다면 에이전트 실행(Start-Service)과 키 등록(ssh-add) 단계를 완전히 생략하고 바로 GitHub 공개키 등록 후 푸시하셔도 정상 동작합니다.

1. 비밀번호를 설정하지 않음: 키 생성 시 패스프레이즈를 빈 값(Enter)으로 통과했을 때
2. 단 한 개의 키만 사용: 기본 경로 (~/.ssh/id_ed25519)에 키를 단 하나만 두고 사용할 때 (Git이 이 경로를 기본으로 우선 탐색하여 사용함)
3. HTTPS 주소 연동 시: SSH 대신 https://... 주소로 연동하여 Git Credential Manager를 사용할 때

---

4단계: GitHub에 공개키 등록

로컬 PC의 공개키(Public Key)를 GitHub 웹서버에 등록하여 로컬 비밀키와 대조해 인증할 수 있도록 만듭니다.

① 공개키 내용 조회 및 복사

# 공개키 파일(.pub)의 텍스트 내용 출력
cat ~/.ssh/id_ed25519.pub

• 출력된 ssh-ed25519 AAAAC3... your-comment 형식의 텍스트 전체를 빠짐없이 드래그하여 복사합니다.

② GitHub 등록 단계

1. GitHub에 로그인합니다.
2. 우측 상단의 프로필 아이콘 -> Settings 메뉴로 이동합니다.
3. 좌측 네비게이션 바에서 SSH and GPG keys를 선택합니다.
4. New SSH key 버튼을 클릭합니다.
5. Title에 PC 이름(예: Office-Desktop, My-Macbook)을 지정하고, Key 본문 입력란에 복사한 공개키 값을 붙여넣습니다.
6. Add SSH key 버튼을 눌러 등록을 완료합니다.

③ 연결 검증

ssh -T git@github.com

• 최초 연결 시 보안을 위한 신뢰 여부 확인 창(Are you sure you want to continue connecting (yes/no/[fingerprint])?)이 나오면 yes를 직접 입력한 뒤 엔터를 누릅니다.
• Hi username! You've successfully authenticated... 문구가 출력되면 최종 연결에 성공한 것입니다.

---

5단계: 원격 저장소 추가 및 첫 푸시

GitHub에 생성된 빈 Repository와 로컬 저장소를 연결하고 소스코드를 처음으로 업로드합니다.

# 1. 로컬 저장소에 'origin'이라는 이름으로 원격 저장소 주소 등록
git remote add origin git@github.com:username/repository-name.git

# 2. 등록된 원격 저장소 리스트 확인 (-v)
git remote -v

# 3. 로컬의 변경 사항 스테이징 및 커밋 생성
git add .
git commit -m "Initial commit"

# 4. 원격 저장소로 첫 푸시 및 기본 업스트림 설정
git push -u origin main

💡 옵션 설명

• remote add origin [URL]: 원격(Remote) 저장소의 식별 이름(Alias)을 관례적으로 origin이라 이름 붙여 추가(add)합니다. origin 대신 다른 임의의 명칭으로 지정해도 연동에는 지장이 없습니다.
• -v (또는 --verbose): 등록된 원격 저장소 주소를 상세(Verbose)하게 출력하여 보여주는 플래그입니다. (Read/Write 권한 경로 출력)
• -u (또는 --set-upstream): 현재의 로컬 브랜치를 원격 브랜치와 추적(Tracking) 관계로 영구 연결해 줍니다. 최초 push 때 한 번만 이 옵션을 적용해 두면, 이후부터는 단순히 git push 또는 git pull만 쳐도 자동으로 origin의 main 브랜치를 기준으로 동기화가 이루어집니다.

 

 

git_github_setup_guide.md

0.01MB