Git config와 인증

Git configuration의 scope와 우선순위, credential.helper, HTTPS token/OAuth, SSH key 인증을 안전하게 구성하는 방법.

Summary

Git remote 인증은 remote URL scheme에 따라 크게 HTTPS와 SSH로 나뉜다.

HTTPS: username과 password 형식의 credential을 사용한다. Hosting service에 따라 password 자리에 personal access token을 입력하거나 OAuth credential helper로 browser login을 수행한다.
SSH: private key로 서명하고 server가 등록된 public key를 확인한다. credential.helper는 SSH key를 저장하거나 관리하지 않는다.
git config user.name과 user.email은 commit 작성자 정보이며 remote login 계정이나 인증 credential이 아니다.

Usage

git config [<options>]
git config [--system|--global|--local|--worktree] KEY VALUE
git config --list --show-origin --show-scope

git config –global KEY VALUE: 사용자 전역 설정을 기록한다.
git config –local KEY VALUE: 현재 repository의 .git/config에 기록한다.
git config –get-all credential.helper: 여러 scope에서 적용되는 helper 값을 모두 확인한다.

Config files and precedence

일반적인 낮은 우선순위에서 높은 우선순위 순서는 system, global, local, worktree, command scope다. 같은 key가 여러 scope에 있으면 더 구체적인 scope가 우선하지만, credential.helper처럼 여러 값을 허용하는 key는 값이 누적될 수 있다.

System: /etc/gitconfig 또는 platform의 system config
Global: ~/.gitconfig, $XDG_CONFIG_HOME/git/config
Local: repository의 .git/config
Worktree: extensions.worktreeConfig를 활성화한 repository의 config.worktree
Command: git -c KEY=VALUE … 또는 관련 environment

# 실제 값, file 위치, scope를 함께 확인
git config --list --show-origin --show-scope
 
# 특정 key의 모든 값 확인
git config --show-origin --show-scope --get-all credential.helper
 
# 사용자 설정 편집
git config --global --edit

인증 문제가 발생하면 git config credential.helper 한 줄만 보지 말고 –get-all, –show-origin, –show-scope를 함께 사용한다. system helper와 global helper가 동시에 등록된 경우가 있다.

Common settings

git config --global user.name "NAME"
git config --global user.email "[email protected]"
git config --global core.editor "code --wait"
 
# 현재 repository에만 다른 identity 적용
git config --local user.name "WORK NAME"
git config --local user.email "[email protected]"
 
# 값 읽기와 삭제
git config --get user.name
git config --global --unset user.name

Line endings

기존 기록의 core.autocrlf 설정은 platform과 repository 정책에 맞게 사용한다.

# Windows checkout에서 CRLF, commit에서는 LF
git config --global core.autocrlf true
 
# macOS/Linux에서 checkout 변환 없이 commit 시 CRLF를 LF로 정규화
git config --global core.autocrlf input

Repository가 .gitattributes로 line ending을 고정한다면 그 정책을 우선한다. 설정 변경 후 기존 file 전체가 수정된 것처럼 보일 수 있으므로 clean worktree에서 적용하고 git diff –check로 확인한다.

Alias

git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"
git lg

git config –global alias.NAME "COMMAND": alias를 설정한다.
git NAME: 등록한 alias를 실행한다.

HTTPS authentication

HTTPS remote에서는 Git이 credential helper에 get, store, erase 요청을 전달한다. Helper가 credential을 제공하지 못하면 GIT_ASKPASS, core.askPass, SSH_ASKPASS, terminal prompt 순서로 입력을 요청할 수 있다.

git remote -v
git config --global --get-all credential.helper
git help -a

Hosting service가 account password 기반 Git 인증을 허용하지 않으면 personal access token을 password 입력란에 사용하거나 OAuth helper로 로그인한다. Token scope와 만료 기간은 필요한 repository 작업에 필요한 최소 범위로 제한한다.

Token, password, private key를 remote URL, shell history, tracked .gitconfig, wiki, script에 넣지 않는다. https://USER:[email protected]/repo.git 형식은 process 목록, log, config와 history에 노출될 수 있다.

credential.helper 선택

안전한 persistent storage가 필요하면 OS keychain 또는 OAuth helper를 우선한다.

Environment	Helper 예	특성
Git Credential Manager	`manager`	Windows, macOS, Linux에서 HTTPS와 OAuth/MFA를 지원한다. Git for Windows에 포함된다.
Linux desktop	`libsecret`	Secret Service를 사용하는 secure persistent storage. Helper가 별도로 설치되어 있어야 한다.
macOS	`osxkeychain`	macOS Keychain에 persistent storage.
Windows legacy	`wincred`	Windows Credential Manager 사용. 새 구성은 Git Credential Manager를 우선 검토한다.
Unix-like temporary	`cache`	memory에 임시 저장하며 기본 timeout은 900초다. Reboot 또는 daemon 종료 시 사라진다.
모든 platform	`store`	disk에 무기한 평문 저장. 보안 tradeoff를 이해한 제한된 환경 외에는 권장하지 않는다.

Helper가 실제로 설치되어 있는지 먼저 확인하고 구성한다.

# 설치된 credential helper 탐색
git help -a
 
# Git Credential Manager
git config --global credential.helper manager
 
# macOS Keychain
git config --global credential.helper osxkeychain
 
# Linux Secret Service
git config --global credential.helper libsecret
 
# Unix-like system에서 1시간 memory cache
git config --global credential.helper 'cache --timeout=3600'

cache는 long-lived personal access token의 persistent storage에 적합하지 않다. store는 ~/.git-credentials 또는 $XDG_CONFIG_HOME/git/credentials에 credential을 암호화하지 않고 기록한다.

기존 환경과의 호환 때문에 store를 사용해야 한다면 다음 설정의 위험과 file permission을 먼저 검토한다.

git config credential.helper store

Host별 설정

같은 host의 여러 repository가 서로 다른 credential을 사용한다면 URL context를 좁힌다.

git config --global credential.https://example.com.username USERNAME
git config --global credential.useHttpPath true

credential.useHttpPath=true는 HTTPS credential을 host뿐 아니라 URL path까지 구분한다. 같은 host의 모든 repository가 같은 계정을 사용하는 환경에서는 불필요할 수 있다.

Helper 변경과 credential 삭제

먼저 모든 scope의 helper를 확인한 후 변경한다.

git config --show-origin --show-scope --get-all credential.helper
git config --global --unset-all credential.helper

저장된 HTTPS credential을 지울 때 secret을 command line에 쓰지 않는다.

printf 'protocol=https\nhost=example.com\n\n' | git credential reject
 
# memory cache 전체를 즉시 종료하고 삭제
git credential-cache exit

OS keychain 또는 Git Credential Manager에 남은 항목은 해당 helper나 OS credential UI에서도 확인한다. credential.helper 설정을 지우는 것과 이미 저장된 credential을 삭제하는 것은 별도 작업이다.

SSH authentication

SSH remote는 [email protected]:OWNER/REPOSITORY.git 또는 ssh://[email protected]/OWNER/REPOSITORY.git 형식을 사용한다.

git remote -v
git remote set-url origin git@example.com:OWNER/REPOSITORY.git
 
# agent 시작과 private key 등록
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
 
# host key와 계정 인증 확인
ssh -T git@example.com

Public key만 hosting service나 Git server 계정에 등록한다.
Private key는 공유하거나 repository에 commit하지 않고 permission을 제한한다.
처음 접속할 때 표시되는 host key fingerprint는 hosting service의 공식 문서나 관리자가 제공한 값과 대조한다.
여러 계정이나 key를 사용하면 ~/.ssh/config의 Host, HostName, User, IdentityFile, IdentitiesOnly를 이용해 alias별로 분리한다.

SSH private key passphrase와 remote account password는 서로 다르다. ssh-agent는 복호화된 private key 사용 권한을 session 동안 중개하며 credential.helper와 독립적으로 동작한다.

Troubleshooting

계속 credential을 묻는 경우

git remote -v로 HTTPS인지 SSH인지 확인한다.
git config –show-origin –show-scope –get-all credential.helper로 helper 중복과 source를 확인한다.
선택한 helper executable이 설치되어 있고 현재 Git에서 보이는지 확인한다.
잘못 저장된 credential을 git credential reject와 OS keychain에서 삭제하고 다시 인증한다.
Host의 token 만료, scope, SSO 승인, account 정책을 확인한다.

잘못된 계정이 선택되는 경우

HTTPS: host별 username, credential.useHttpPath, OAuth helper의 account binding을 확인한다.
SSH: ssh -vT [email protected]으로 제시되는 key를 확인하고 ~/.ssh/config에서 account별 host alias를 사용한다.

Automation / CI

Interactive prompt가 없어야 하는 환경에서는 credential helper UI를 기대하지 않는다.

git -c credential.interactive=false fetch

CI provider의 secret store와 short-lived token을 사용하고 log redaction을 확인한다. Token을 tracked Git config나 remote URL에 영구 저장하지 않는다.

Help

git config -h

usage: git config [<options>]
 
Config file location
    --[no-]global         use global config file
    --[no-]system         use system config file
    --[no-]local          use repository config file
    --[no-]worktree       use per-worktree config file
    -f, --[no-]file <file>
                          use given config file
    --[no-]blob <blob-id> read config from given blob object
 
Action
    --[no-]get            get value: name [value-pattern]
    --[no-]get-all        get all values: key [value-pattern]
    --[no-]get-regexp     get values for regexp: name-regex [value-pattern]
    --[no-]get-urlmatch   get value specific for the URL: section[.var] URL
    --[no-]replace-all    replace all matching variables: name value [value-pattern]
    --[no-]add            add a new variable: name value
    --[no-]unset          remove a variable: name [value-pattern]
    --[no-]unset-all      remove all matches: name [value-pattern]
    --[no-]rename-section rename section: old-name new-name
    --[no-]remove-section remove a section: name
    -l, --[no-]list       list all
    --[no-]fixed-value    use string equality when comparing values to 'value-pattern'
    -e, --[no-]edit       open an editor
    --[no-]get-color      find the color configured: slot [default]
    --[no-]get-colorbool  find the color setting: slot [stdout-is-tty]
 
Type
    -t, --[no-]type <type>
                          value is given this type
    --bool                value is "true" or "false"
    --int                 value is decimal number
    --bool-or-int         value is --bool or --int
    --bool-or-str         value is --bool or string
    --path                value is a path (file or directory name)
    --expiry-date         value is an expiry date
 
Other
    -z, --[no-]null       terminate values with NUL byte
    --[no-]name-only      show variable names only
    --[no-]includes       respect include directives on lookup
    --[no-]show-origin    show origin of config
    --[no-]show-scope     show scope of config
    --[no-]default <value>
                          with --get, use default value when missing entry

History

codex:: 2026-07-26 Added Git configuration scopes, credential helper selection, HTTPS token/OAuth, SSH authentication, credential removal, and troubleshooting guidance.

config

목차