GitHub 멀티 계정 전환 — gh auth switch 활용 가이드

한 머신에서 직장 계정, 개인 계정, organization별 봇 계정을 함께 쓰는 경우가 있다. git push 시 어떤 계정의 자격증명이 전송되는지는 credential helper가 결정한다. 이 글은 gh CLI를 credential helper로 쓸 때의 동작 원리와 자주 겪는 문제를 정리한다.

본 포스트는 macOS/Linux 기준이다. Windows는 Git Credential Manager(GCM)가 기본이라 helper 이름은 다르지만 개념은 동일하다.

[01] 멀티 계정이 필요한 상황

git 자체는 자격증명을 저장하지 않는다. credential helper 라는 외부 프로그램에 위임한다. helper는 OS keyring, 평문 파일, 또는 GitHub CLI(gh) 같은 외부 도구일 수 있다.

[02] credential helper의 동작 원리

git push 가 일어날 때의 흐름:

flowchart LR
    A["git push"] --> B{"remote URL이
HTTPS인가?"}
    B -->|Yes| C["helper에게
자격증명 요청"]
    C --> D["helper 응답
username + PAT"]
    D --> E["Basic Auth 헤더로
HTTPS 전송"]
    E --> F{"GitHub
권한 검증"}
    F -->|OK| G["push 성공"]
    F -->|NG| H["403 denied"]

    style G fill:#e8f5e9,stroke:#2e7d32
    style H fill:#ffcccc,stroke:#c62828

대표 helper:

Helper	저장 위치	특징
`store`	`~/.git-credentials` 평문	가장 단순, 보안 약함
`cache`	메모리 (TTL 15분 기본)	휘발성, 프로세스 종료 시 소멸
`manager` (GCM)	OS keyring	Windows 표준
`osxkeychain`	macOS Keychain	macOS 기본
`libsecret`	GNOME keyring	Linux 데스크톱
`!gh auth git-credential`	`gh` 가 동적으로 제공	멀티 계정 native

gh helper의 특별한 점은, 자격증명을 자체 보관하지 않고 활성 계정(active account) 의 OAuth 토큰을 그때그때 넘겨준다는 것이다. 즉 gh auth switch 한 줄이면 git push의 인증 주체가 바뀐다.

[03] 내 시스템 helper 확인

git config --get credential.https://github.com.helper

출력 예:

!/usr/bin/gh auth git-credential

이 출력이 보이면 gh 가 git 자격증명을 관장하고 있다. 이제부터 gh 의 활성 계정 = git push 계정이다.

출력이 비어 있거나 store, osxkeychain 등이 보이면 아직 gh 가 helper로 등록되지 않은 상태다. 아래 절차에서 gh auth setup-git 으로 등록할 수 있다.

[04] 두 번째 계정 추가하기

4-1. PAT 발급 (Fine-grained 권장)

새로 추가할 계정으로 GitHub 로그인 → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate.

권장 권한:

Repository access: 사용할 저장소만 선택 (전체 X)
Permissions: Contents = R/W, Workflows = R/W

토큰은 발급 직후 단 한 번만 노출된다. 즉시 안전한 곳(비밀번호 관리자)에 복사.

4-2. `gh auth login`

gh auth login

대화형 흐름:

질문	선택
Where do you use GitHub?	GitHub.com
Preferred protocol for Git operations?	HTTPS
Authenticate Git with your GitHub credentials?	Yes
How would you like to authenticate?	Paste an authentication token
Paste your authentication token	발급한 PAT 붙여넣기

성공하면 Logged in as <username> 이 출력된다.

4-3. 등록 결과 확인

gh auth status

github.com
  ✓ Logged in to github.com account work-bot
    Active account: true
  ✓ Logged in to github.com account personal-acct

Active account: true 가 붙은 쪽이 git push 시 사용된다.

[05] 활성 계정 전환 — `gh auth switch`

# 두 번째 계정으로 전환
gh auth switch -u personal-acct

# 결과 확인
gh auth status | grep -A1 "Active account"

# 이제 모든 git push가 personal-acct 로 나간다
git push

gh auth switch 는 머신 전역에 적용된다. 저장소·디렉토리별 분리가 아니다. 다른 작업 디렉토리에서도 영향을 받으니, 작업 시작 전에 gh auth status 로 활성 계정을 한 번 확인하는 습관을 들이자.

[06] 실전 시나리오 — 잘못된 계정으로 push 하려 할 때

remote: Permission to org-a/repo.git denied to personal-acct.
fatal: 'https://github.com/org-a/repo.git/'에 접근할 수 없습니다: 403

push 대상 저장소의 권한 소유자와 활성 계정이 일치하지 않는다는 뜻이다.

복구 절차:

# 1. 현재 활성 계정 확인
gh auth status | grep "Active account"

# 2. 필요한 계정으로 전환
gh auth switch -u <correct-account>

# 3. 재push
git push

[07] 검증 명령어 모음

작업 도중 의심스러우면 다음 세 줄로 즉시 진단할 수 있다.

# helper 확인
git config --list | grep credential

# gh 등록 계정 + 활성 계정
gh auth status

# git이 실제로 받는 자격증명 시뮬레이션 (가장 강력함)
echo -e "protocol=https\nhost=github.com\n" | gh auth git-credential get

마지막 명령은 git이 push 시 받게 되는 username/password를 콘솔에 출력해준다. 디버깅에 매우 유용 — 활성 계정 전환이 제대로 반영됐는지 한 번에 검증된다.

[08] 함정 5가지

8-1. switch 했는데도 여전히 옛 계정으로 push됨

원인은 대부분 remote URL에 username이 박혀 있는 경우:

git remote -v
# origin  https://old-user@github.com/...

URL의 username은 helper보다 우선된다. 다음과 같이 정리:

git remote set-url origin https://github.com/<owner>/<repo>.git

8-2. PAT 만료

PAT는 만료기한이 있다. push 시 401이 발생하면 가장 먼저 확인한다.

# 갱신
gh auth refresh -h github.com

# 또는 재로그인
gh auth login

8-3. 두 계정을 동시에 사용해야 한다

gh 의 active는 1개뿐이다. 저장소별로 다른 계정이 필요하면:

방법	설명	추천도
A. 저장소별 helper 오버라이드	`git config --local credential.helper` 로 다른 helper 지정	★★
B. SSH + `~/.ssh/config` Host alias	호스트별로 다른 SSH 키 매핑	★★★
C. PAT를 remote URL에 직접 박아두기	편하지만 평문 노출	★ (권장하지 않음)

대부분의 경우 SSH alias가 가장 깔끔하다.

8-4. macOS Keychain과 `gh` 가 충돌

macOS는 osxkeychain helper가 자동 등록될 수 있다. gh 와 둘 다 활성화되면 우선순위가 불명확해진다.

# 충돌 정리
git config --global --unset credential.helper
gh auth setup-git

8-5. private fork 에 push 안 됨

PAT scope이 부족하거나 Fine-grained PAT의 Repository access에 fork가 빠진 경우에 발생한다. PAT 설정 화면에서 해당 fork를 access list에 추가해야 한다.

[09] 정리

git push 인증의 본질
  └─ helper가 어떤 자격증명을 반환하는가

gh를 helper로 쓰면
  └─ 계정 관리는 아래 gh 명령으로 처리
       ├─ 추가:    gh auth login
       ├─ 전환:    gh auth switch -u <user>
       ├─ 확인:    gh auth status
       └─ 재발급:  gh auth refresh

함정 1순위
  └─ remote URL의 username이 helper보다 우선
       → git remote set-url 로 정리

머신 전역 vs 저장소 단위
  ├─ 머신 전역:    gh auth switch
  └─ 저장소 단위:  SSH alias / 로컬 helper 오버라이드

작업 시작 전에 gh auth status 로 활성 계정을 확인하면 403 에러 대부분을 피할 수 있다.

cmaven

GitHub 멀티 계정 전환 — gh auth switch 활용 가이드

[01] 멀티 계정이 필요한 상황

[02] credential helper의 동작 원리

[03] 내 시스템 helper 확인

[04] 두 번째 계정 추가하기

4-1. PAT 발급 (Fine-grained 권장)

4-3. 등록 결과 확인

[05] 활성 계정 전환 — `gh auth switch`

[06] 실전 시나리오 — 잘못된 계정으로 push 하려 할 때

[07] 검증 명령어 모음

[08] 함정 5가지

8-1. switch 했는데도 여전히 옛 계정으로 push됨

8-2. PAT 만료

8-3. 두 계정을 동시에 사용해야 한다

8-4. macOS Keychain과 `gh` 가 충돌

8-5. private fork 에 push 안 됨

[09] 정리

참고

외부 Ceph 클러스터 지표를 Prometheus로 수집하기 — 정적 scrape vs Rook ServiceMonitor

Ollama 모델 2개로 AI 코드 리뷰 자동화: OpenCode 서브에이전트로 구현·검토 분리하기

Ollama 멀티GPU 운영·트러블슈팅: 100% CPU, 드라이버 550, 모델 저장 경로

로컬 LLM 입문 개념: VRAM·양자화·KV Cache·MoE를 한 번에 정리

cmaven

[01] 멀티 계정이 필요한 상황

[02] credential helper의 동작 원리

[03] 내 시스템 helper 확인

[04] 두 번째 계정 추가하기

4-1. PAT 발급 (Fine-grained 권장)

4-2. gh auth login

4-3. 등록 결과 확인

[05] 활성 계정 전환 — gh auth switch

[06] 실전 시나리오 — 잘못된 계정으로 push 하려 할 때

[07] 검증 명령어 모음

[08] 함정 5가지

8-1. switch 했는데도 여전히 옛 계정으로 push됨

8-2. PAT 만료

8-3. 두 계정을 동시에 사용해야 한다

8-4. macOS Keychain과 gh 가 충돌

8-5. private fork 에 push 안 됨

[09] 정리

참고

외부 Ceph 클러스터 지표를 Prometheus로 수집하기 — 정적 scrape vs Rook ServiceMonitor

Ollama 모델 2개로 AI 코드 리뷰 자동화: OpenCode 서브에이전트로 구현·검토 분리하기

Ollama 멀티GPU 운영·트러블슈팅: 100% CPU, 드라이버 550, 모델 저장 경로

로컬 LLM 입문 개념: VRAM·양자화·KV Cache·MoE를 한 번에 정리

4-2. `gh auth login`

[05] 활성 계정 전환 — `gh auth switch`

8-4. macOS Keychain과 `gh` 가 충돌