devAlice
← Windows

Windows Git 인증 — Credential Manager · SSH · commit 서명까지

Windows에서 Git 인증 매끄럽게 — Git Credential Manager·SSH 키·SSH 서명 + 멀티 계정.

Windows Git 인증은 macOS·Linux보다 살짝 복잡하다 — Git Credential Manager(GCM)·OpenSSH·1Password agent가 섞여 충돌 나기 쉽다. 이 가이드는 한 번 깔끔히 셋업해서 다음 1년 동안 안 건드리는 상태를 목표로 한다.

대상: Windows 11 + Git for Windows + GitHub (Windows 초기 셋업 완료).

TL;DR

  1. Git Credential Manager (GCM) — HTTPS clone 시 OAuth (브라우저 로그인)
  2. OpenSSH 키 — SSH clone 시. Ed25519 권장
  3. commit 서명 — SSH 키로 (GPG 대신, 더 단순)
  4. 회사/개인 계정 분리 — Include.path 또는 ~/.ssh/config Host 별칭
  5. 1Password SSH agent (선택) — 키를 vault에 두기

사전 조건

  • Git for Windows 2.40+ — winget install --id Git.Git (Windows 초기 셋업)
  • OpenSSH 클라이언트 활성화 (Win11 기본) — Get-WindowsCapability -Online -Name "OpenSSH.Client*" 로 확인

1. Git Credential Manager — HTTPS

Git for Windows 설치 시 GCM 자동 포함. HTTPS clone/push 시 자동으로 OAuth 브라우저 창이 열린다:

git clone https://github.com/user/repo.git
# 브라우저 열림 → GitHub 로그인 → 토큰 자동 저장

저장 위치: Windows Credential Manager (제어판 → 사용자 계정 → 자격 증명 관리자 → Windows 자격 증명).

동작 확인

git config --global credential.helper
# manager

manager 가 나오면 GCM 활성. 다른 값이면:

git config --global credential.helper manager

멀티 계정 (회사 + 개인 GitHub)

URL별 다른 헬퍼 사용:

git config --global --add credential.https://github.com.useHttpPath true

이제 같은 호스트의 다른 path마다 별도 자격 증명 가능.

2. SSH 키

SSH 방식은 HTTPS보다 매끄럽다 (브라우저 안 띄움). Ed25519 키 생성:

ssh-keygen -t ed25519 -C "you@example.com"
# 저장 경로: ~/.ssh/id_ed25519 (기본)
# passphrase: 권장 (1Password agent 쓰면 자동 unlock)

공개 키 확인:

Get-Content ~/.ssh/id_ed25519.pub
# ssh-ed25519 AAAA... you@example.com

GitHub → Settings → SSH and GPG keys → New SSH key → 위 공개 키 붙여넣기.

ssh-agent 활성화 (passphrase 자동 unlock)

# 관리자 PowerShell
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
 
# 일반 PowerShell
ssh-add ~/.ssh/id_ed25519
# passphrase 입력 한 번. 이후 자동

SSH 동작 확인

ssh -T git@github.com
# Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.

remote URL 전환 (HTTPS → SSH)

git remote set-url origin git@github.com:user/repo.git

3. SSH 서명으로 commit 서명

GPG보다 단순하고 같은 키 재사용. Git 2.34+ 필요.

git config --global gpg.format ssh
git config --global user.signingkey "ssh-ed25519 AAAA... you@example.com"
git config --global commit.gpgsign true
git config --global tag.gpgsign true

user.signingkey는 공개 키 한 줄 통째로. 또는 파일 참조:

git config --global user.signingkey "C:/Users/me/.ssh/id_ed25519.pub"

GitHub에 signing key 등록

같은 공개 키를 GitHub → SSH and GPG keys → Add new SSH key → Key type = Signing Key 로 등록.

테스트

git commit --allow-empty -m "test signed"
git log --show-signature -1
# Good "git" signature with ED25519 key SHA256:...

GitHub PR 화면에서 "Verified" 배지 확인.

allowed signers 파일 (verify 시 필요)

~/.config/git/allowed_signers:

you@example.com ssh-ed25519 AAAA...
coworker@example.com ssh-ed25519 BBBB...

git config --global gpg.ssh.allowedSignersFile "$HOME/.config/git/allowed_signers"

이제 git log --show-signature 가 다른 사람 커밋도 검증.

4. 멀티 GitHub 계정 (회사 + 개인)

4.1 SSH config — Host 별칭

~/.ssh/config:

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  IdentitiesOnly yes

Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

clone:

git clone git@github.com-personal:personal-user/repo.git
git clone git@github.com-work:company/repo.git

4.2 작업 폴더별 user.email — includeIf

~/.gitconfig:

[user]
    name = Your Name
    email = personal@example.com
 
[includeIf "gitdir:C:/Users/me/work/"]
    path = C:/Users/me/.gitconfig-work

~/.gitconfig-work:

[user]
    email = me@company.com
    signingkey = ssh-ed25519 AAAA... me@company.com

C:/Users/me/work/ 하위 repo는 자동으로 회사 이메일·키 사용.

확인:

cd C:\Users\me\work\some-repo
git config user.email
# me@company.com
 
cd C:\Users\me\personal\some-repo
git config user.email
# personal@example.com

5. 1Password SSH agent (선택)

비밀번호 매니저 참고. Windows는 환경변수로 agent 지정:

  1. 1Password 데스크톱 → Settings → Developer → "Use the SSH agent" ✅
  2. SSH 키를 1Password vault에 저장 + GitHub 등록
  3. PowerShell $PROFILE: 
    $env:SSH_AUTH_SOCK = '\\.\pipe\openssh-ssh-agent'
  4. 새 터미널 → ssh -T git@github.com → Windows Hello 한 번

이제 ~/.ssh/id_* 평문 파일 없어도 SSH·commit 서명 동작.

6. 검증

  1. ssh -T git@github.com — 인증 OK
  2. git clone git@github.com:you/repo.git — passphrase 없이 (또는 1Password biometric 한 번)
  3. git commit --allow-empty -m test && git log --show-signature -1 — "Good signature"
  4. GitHub UI에서 PR 화면 → "Verified" 배지
  5. 회사 폴더와 개인 폴더에서 git config user.email 다르게 나옴

트러블슈팅

ssh: connect to host github.com port 22: Connection timed out

회사 방화벽이 22 차단. 443 SSH:

# ~/.ssh/config
Host github.com
  HostName ssh.github.com
  Port 443

Permission denied (publickey)

  • 키 파일 권한 — PowerShell icacls ~/.ssh/id_ed25519 /inheritance:r /grant:r "$($env:USERNAME):(R)"
  • GitHub에 공개 키 등록 누락 확인

Git Credential Manager 비활성

git config --global credential.helper manager
git config --global credential.helperSelector prompt

1Password SSH agent 못 찾음

  • 데스크톱 앱이 실행 중 + 로그인 + Developer 옵션 ON
  • 환경변수 SSH_AUTH_SOCK 정확한지 (\\.\pipe\openssh-ssh-agent)
  • 충돌 가능: OpenSSH agent 서비스가 동작 중이면 그쪽 SSH_AUTH_SOCK 우선. Stop-Service ssh-agent 또는 disable

commit 서명이 "Unverified"

  • GitHub에 SSH 키를 signing key로 별도 등록 (authentication 키와 별개 항목)
  • git config --global gpg.format ssh 누락
  • 키 자체 손상 — 새 키 생성 후 재등록

includeIf가 적용 안 됨

  • Git 2.36+ 필요 (오래된 Git for Windows는 미지원)
  • gitdir 경로는 trailing / 포함 (C:/Users/me/work/)
  • Windows 경로는 \ 아닌 / 사용

참고

변경 이력

  • 2026-05-12: 첫 작성. GCM·SSH 키·SSH 서명·멀티 계정·1Password agent + 트러블슈팅 6종.

댓글