SSH 키를 사용한 Git 푸시

SSH 키로 Git 브랜치를 푸시하려면 키 쌍을 만들고, 공개 키를 Git 호스팅 계정에 등록한 다음, 저장소의 원격 주소를 SSH URL로 설정하고 푸시할 브랜치를 지정합니다. 개인 키는 사용자 컴퓨터에 보관합니다. SSH는 호스트에 사용자를 인증하고, 호스트는 해당 계정에 저장소 쓰기 권한이 있는지 별도로 확인합니다.

SSH 키 쌍 생성

이 계정에 사용할 키가 아직 없다면 ssh-keygen으로 Ed25519 키 쌍을 생성합니다. 아래 예제는 명령을 보여 주기 위한 임시 키 쌍을 만들며, 평소 사용하는 ~/.ssh 파일은 변경하지 않습니다. POSIX 셸에서 실행하며 SSH 설정도 수정하지 않습니다.

set -e
key_dir=$(mktemp -d)
trap 'rm -rf "$key_dir"' EXIT
ssh-keygen -q -t ed25519 -C "git@example.com" -f "$key_dir/id_ed25519" -N ""
test -s "$key_dir/id_ed25519.pub"
printf 'Created the Ed25519 public key file.\n'

Created the Ed25519 public key file.

이 예제는 -N ""을 사용해 암호 문구를 비워 두므로 ssh-keygen이 대화형 질문을 하지 않습니다. 계속 사용할 키를 만들려면 -f를 생략해 기본 저장 위치를 사용하거나 ~/.ssh/id_ed25519_work 같은 경로를 지정할 수 있습니다. ssh-keygen은 저장 위치와 암호 문구를 차례로 묻습니다. 저장된 키를 보호하려면 암호 문구를 입력하고, 비워 두려면 Enter를 두 번 누릅니다. .pub 확장자가 없는 파일이 개인 키이므로 비밀로 보관하고 업로드하지 마세요. .pub 파일은 공개 키입니다. 이미 적합한 키 쌍이 있다면 새로 만들지 않고 기존 키를 사용해도 됩니다.

Git 호스팅 계정에 공개 키 등록

선택한 공개 키 파일을 표시한 뒤(예: cat ~/.ssh/id_ed25519.pub) 파일의 전체 한 줄을 복사합니다. Git 호스트의 계정 설정에서 SSH 키 항목을 열고 공개 키를 추가합니다. GitHub, GitLab 등 제공업체마다 메뉴 이름과 계정 정책이 다르므로 해당 제공업체의 안내를 따르세요. 개인 키를 붙여 넣거나 업로드해서는 안 됩니다.

SSH에서 하나 또는 여러 키 설정

SSH의 기본 키 선택을 사용할 수도 있고, 여러 계정이나 키를 사용한다면 호스트 별칭으로 특정 키를 선택할 수도 있습니다. 다음 항목 전체를 ~/.ssh/config에 추가합니다.

다음 명령으로 항목 전체가 포함된 예제를 출력한 뒤 ~/.ssh/config에 복사합니다.

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

~/.ssh/id_ed25519_work는 예시 경로이므로 실제 개인 키의 경로로 바꾸세요. Git 원격 주소에는 Host 항목과 동일한 github-work 별칭을 사용해야 합니다. IdentityFile에는 개인 키 경로를 지정합니다. IdentitiesOnly yes는 SSH가 에이전트의 다른 키를 차례로 시도하는 대신 설정한 키를 제공하도록 합니다. 다른 계정에는 별도의 별칭과 키 경로를 사용하세요. Git 원격 주소의 별칭은 Host 값과 정확히 일치해야 합니다. 파일 권한 설정과 SSH 에이전트 시작 방법은 운영체제와 셸에 따라 다릅니다. 에이전트를 사용한다면 환경에서 지원하는 방식으로 에이전트를 시작한 다음 ssh-add로 개인 키를 불러오세요. SSH가 키를 직접 읽을 수 있다면 이 단계는 선택 사항입니다.

저장소의 SSH 원격 주소 설정

로컬 저장소에서 git remote -v로 현재 원격 주소를 확인합니다. GitHub SSH 원격 주소 형식은 git@github.com:OWNER/REPOSITORY.git입니다. 두 자리표시자를 계정 또는 조직 이름과 저장소 이름으로 바꾸세요. 기존 origin 주소를 git remote set-url origin git@github.com:OWNER/REPOSITORY.git으로 변경한 다음, git remote -v를 다시 실행해 SSH URL로 표시되는지 확인합니다. 원격 이름이 origin이 아니라면 기존 이름을 그대로 사용하세요.

github-work 같은 별칭을 설정했다면 URL에도 그 별칭을 사용합니다. 예를 들면 git@github-work:OWNER/REPOSITORY.git입니다. 다른 호스트에서는 해당 제공업체가 안내하는 SSH URL을 사용하세요. URL이 여전히 https://로 시작하면 HTTPS 인증을 사용 중입니다. 원격 주소를 SSH로 변경하기 전에는 키를 바꿔도 인증 방식에 영향을 주지 않습니다.

변경 사항 커밋 및 푸시

커밋에 포함할 파일을 선택해 git add path/to/file처럼 명시적으로 스테이징하세요. 현재 디렉터리의 모든 변경 사항을 이 커밋에 포함할 때만 git add .을 사용합니다. git commit -m "Describe the change"로 커밋을 만듭니다. 그런 다음 git push origin BRANCH로 원하는 브랜치를 푸시하세요. origin과 BRANCH는 저장소에서 사용하는 원격 및 브랜치 이름으로 바꿉니다. 브랜치를 처음 푸시할 때 git push -u origin BRANCH를 사용하면 해당 원격 브랜치가 업스트림으로도 기록됩니다.

SSH 인증 확인 및 일반적인 문제 해결

ssh -T git@github.com으로 호스트 연결을 확인하거나, SSH 별칭을 사용하는 경우 ssh -T git@github-work처럼 바꿔 실행합니다. 호스트 응답은 제공업체마다 다르며, 계정을 확인해 주더라도 대화형 셸은 제공하지 않는 호스트가 있습니다. 인증은 키가 어떤 계정에 연결되는지만 확인합니다. 해당 계정에 저장소 푸시 권한이 있다는 뜻은 아니며, 인증 성공 메시지가 표시되어도 제공업체에 따라 종료 상태가 0이 아닐 수 있습니다.

테스트에서 다른 계정이 확인되거나 인증에 실패하면 공개 키를 해당 계정에 등록했는지, IdentityFile이 짝이 맞는 개인 키를 가리키는지, 원격 주소가 올바른 Host 별칭을 사용하는지 확인하세요. ssh -vT git@github-work를 실행하면 SSH가 어떤 키를 제공하는지 확인할 수 있습니다. 진단 출력은 로컬에서 검토하고 개인 키 내용은 공유하지 마세요. git remote -v로 원격 URL도 확인합니다. 인증은 성공했지만 푸시가 거부된다면 저장소 쓰기 권한, 브랜치 이름, 호스트 측 브랜치 규칙을 확인하세요.

개인 키를 잃어버렸거나 노출했다면 새 키 쌍을 만들고 공개 키를 호스트에 등록한 다음, 필요한 경우 SSH 설정이나 원격 주소를 업데이트하고 계정에서 이전 공개 키를 삭제하세요. 공개 키는 Git 호스트와 공유해도 되지만 개인 키는 비밀로 유지해야 합니다.