GitHub·GitLab SSH 키가 안 될 때: 단계별 해결법

2026년 8월 17일 · 업데이트 2026년 9월 29일 · Termalin Team sshgittroubleshootingssh-keys

GitHub나 GitLab에 인증되지 않는 SSH 키는 개발자가 가장 많이 검색하는 문제 중 하나이고, 절반은 사실 키가 멀쩡합니다. 진단이 틀렸을 뿐입니다. 그러니 무언가를 다시 만들기 전에, 테스트 하나를 돌리고 그 답을 읽는 법을 익히세요. 그런 다음 실제로 원인이 되는 빈도 순서대로 용의자를 처리하세요.

“You’ve successfully authenticated, but GitHub does not provide shell access”

이 줄이 돌아왔다면, 멈추세요. 키는 이미 작동합니다. GitHub와 GitLab은 셸을 내주지 않습니다. SSH 위로 git만 말하므로 인증한 뒤 곧바로 연결을 끊고, “does not provide shell access”는 그걸 말하는 것이지 오류가 아닙니다. GitLab의 표현은 조금 다르지만(Welcome to GitLab, @you!) 같은 뜻입니다. 키가 작동하는데도 git push가 여전히 비밀번호를 묻는다면, 키는 처음부터 문제가 아니었습니다. 아래의 HTTPS 원격 용의자로 건너뛰세요. 그게 보통 진짜 원인입니다.

0단계: 애초에 고장인지 알려 주는 테스트

git 호스트에게 내 키를 알아보는지 직접 물어보세요:

ssh -T git@github.com        # GitHub
ssh -T git@gitlab.com        # GitLab

이제 응답을 주의 깊게 읽으세요. 성공 메시지가 오류처럼 보이기 때문입니다:

Hi <username>! You've successfully authenticated, but GitHub does not
provide shell access.

그게 성공입니다. “Does not provide shell access”는 실패가 아닙니다. GitHub와 GitLab은 셸을 주지 않고 SSH 위로 git만 말하므로, 인증한 뒤 연결을 끊습니다. 사람들은 “does not provide”를 보고 멀쩡한 구성을 디버깅하기 시작합니다. 그 줄에 내 사용자명이 보이면 키는 작동하는 것이고, 문제는 다른 데 있습니다(아래 HTTPS 원격 용의자로 건너뛰세요. 그게 보통의 진짜 문제입니다).

진짜 실패는 대신 이렇게 생겼습니다:

git@github.com: Permission denied (publickey).

그게 우리가 고치러 온 것입니다. 끝 부분에 주목하세요. Permission denied (publickey)는 서버가 제시한 키를 하나도 받지 않았다는 뜻입니다. 목록을 따라 내려가며 처리하세요.

용의자 1: 키가 계정에 추가되지 않음

가장 흔한 진짜 원인입니다. 노트북의 키는 공개 쪽이 git 호스트에 등록되기 전까지 아무 일도 하지 않습니다. 공개 키를 복사하세요:

cat ~/.ssh/id_ed25519.pub     # note the .pub — this is the safe half to share

그걸 GitHub → Settings → SSH and GPG keys → New SSH key, 또는 GitLab → Preferences → SSH Keys에 붙여 넣으세요.

규칙 하나, 예외 없음: .pub 파일을 붙여 넣고, .pub이 없는 파일은 절대 붙여 넣지 마세요. 공개 키는 ssh-ed25519 AAAA…(또는 ssh-rsa AAAA…)로 시작하는 한 줄입니다. 붙여 넣으려는 것이 -----BEGIN OPENSSH PRIVATE KEY-----로 시작한다면 멈추세요. 그건 개인 키이고, 내 신원 그 자체인 비밀입니다. 그걸 웹 폼에 붙여 넣는 것은 그 페이지를 읽을 수 있는 누구에게나 내 자격 증명을 넘기는 일입니다. 공개 쪽은 공유하고, 개인 쪽은 지키세요.

(아직 키가 없나요? 하나 만드세요 — 거의 모든 경우 Ed25519(영어): ssh-keygen -t ed25519 -C "you@device".)

용의자 2: 엉뚱한 키가 제시됨

키는 등록됐는데 SSH가 다른 키를 제시하고 있습니다. 키를 여러 개 들고 다니고 에이전트가 서버가 거부하는 순서로 시도할 때 흔합니다. 어떤 키가 전송되는지 정확히 보세요:

ssh -vT git@github.com

Offering public key: 줄을 찾으세요. 등록한 키가 그중에 없거나 엉뚱한 키가 수락되고 있다면, ~/.ssh/config에 호스트별로 맞는 키를 고정하세요:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

IdentitiesOnly yes가 핵심 줄입니다. SSH에게 지정한 IdentityFile만 제시하고 에이전트의 모든 키를 서버에 흩뿌리지 말라고 지시합니다(덤으로 Too many authentication failures도 낫습니다). GitLab에는 Host gitlab.com으로 똑같이 하세요. 파일 구성에 대한 자세한 내용은 ssh_config 안내(영어)에 있습니다.

용의자 3: 에이전트가 안 돌거나 키가 안 올라감

키에 암호구가 있는데 에이전트가 그걸 쥐고 있지 않으면, SSH가 조용히 건너뛸 수 있습니다. 에이전트가 무엇을 가졌는지 확인하세요:

ssh-add -l

The agent has no identities(또는 Could not open a connection to your authentication agent)는 에이전트를 시작하고 키를 올려야 한다는 뜻입니다:

eval "$(ssh-agent -s)"        # start the agent in this shell
ssh-add ~/.ssh/id_ed25519     # load the key (prompts for the passphrase once)

이제 ssh-add -l이 내 키의 지문을 보여 줘야 합니다. (에이전트가 실제로 무엇이고 어떻게 키를 쥐는지는 SSH 에이전트란 무엇인가(영어)를 보세요.)

용의자 4: SSH가 아니라 HTTPS 원격을 쓰고 있음

이것이 ‘키는 되는데(ssh -T 성공) git push는 여전히 비밀번호를 묻는다’ 뒤에 있는 용의자입니다. 저장소가 HTTPS를 쓰도록 설정되어 있고, HTTPS는 SSH 키를 완전히 무시하고 토큰을 원합니다. 확인하세요:

git remote -v

https://github.com/you/repo.git이 보이면 그게 문제입니다. HTTPS는 SSH 키에 전혀 손대지 않습니다. 원격을 SSH로 바꾸세요:

git remote set-url origin git@github.com:you/repo.git      # GitHub
git remote set-url origin git@gitlab.com:you/repo.git      # GitLab

git remote -v를 다시 실행해 이제 git@으로 시작하는지 확인하세요. 이 한 번의 수정이, 키는 처음부터 멀쩡했던 ‘SSH 키가 안 돼요’ 신고의 큰 몫을 해결합니다.

용의자 5: ~/.ssh 권한

SSH는 남이 손댈 수 있는 키와 설정을 쓰길 거부합니다. verbose 출력이 잘못된 모드를 언급하거나, 뚜렷한 이유 없이 키가 무시된다면:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519          # private key
chmod 644 ~/.ssh/id_ed25519.pub      # public key
chmod 600 ~/.ssh/config

Windows에서는 동기화 드라이브에서 키를 빼내거나 머신 간에 복사한 뒤 드러납니다. 파일의 보안 속성에서 고치거나, 키를 클라우드 동기화 폴더에 두지 마세요.

용의자 6: 매번 암호구를 묻는 경우

모든 git 작업이 키 암호구를 요구한다면, 에이전트가 그걸 캐시하지 않는 것입니다. ssh-add(영어)로 한 번 올리고(용의자 3), ~/.ssh/config에 추가해 세션 간에도 유지되게 하세요:

Host github.com gitlab.com
    AddKeysToAgent yes

macOS에서는 ssh-add --apple-use-keychain ~/.ssh/id_ed25519가 암호구를 Keychain에 저장해 재부팅 후에도 남습니다.

용의자 7: 계정 둘, 호스트 하나

회사와 개인 GitHub 계정은 키 하나를 공유할 수 없습니다. 주어진 공개 키는 정확히 한 계정에 속합니다. 각각에 자체 키와, 그것을 고르는 Host 별칭을 주세요:

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

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

그런 다음 호스트로 별칭을 써서 클론하거나 원격을 설정하세요: git@github-work:org/repo.git. SSH가 github-work를 매칭해 회사 키를 고르고, 내부적으로 연결을 github.com으로 다시 씁니다.

용의자 8: 조직 SSO 미승인 (GitHub)

내 저장소에는 잘 인증되는데 SAML SSO 뒤에 있는 조직 저장소에서 Permission denied가 납니다. 키는 있지만 그 조직에 대해 승인되지 않은 것입니다. Settings → SSH and GPG keys로 가서 키를 찾아 Configure SSO를 클릭하고, 그 조직에 대해 승인하세요. GitLab에는 만료된 키가 조용히 거부되는 비슷한 경우가 있습니다. 잘되던 키가 갑자기 멈췄다면 SSH Keys에서 키의 만료일을 확인하세요.

그래도 여전히 `Permission denied (publickey)`일 때

목록을 다 처리했는데도 여전히 막힌다면, 진짜 키 수락 문제로 좁혀진 것입니다. 바로 그 오류를 위한 체계적인 루프(ssh -vvv 읽기, 서버의 방식 목록, 제시된 키 vs 수락된 키)는 permission denied (publickey), 빠르고 체계적인 해결(영어)에 있고, SSH 오류의 더 넓은 지도는 SSH 오류 해부에 있습니다. 하지만 git 호스트에 한정하면 위 순서가 거의 모든 것을 잡습니다. 공개 키를 등록하고, 맞는 키를 제시하고, 에이전트에 올리고, 정말로 SSH 원격을 쓰고 있는지 확인하세요.

클라이언트가 그 설정 전체를 없애 주는 지점

이 마찰의 대부분은 장부 정리입니다. 어떤 키가 어떤 호스트에 속하는지, 올라가 있는지, 원격이 SSH이기나 한지. Termalin은 키를 그것이 속한 호스트와 함께 보관하고, 내장 에이전트로 키를 한 번 잠금 해제해 암호구를 다시 입력하지 않게 하며(취소한 프롬프트가 키를 조용히 건너뛰는 일도 없습니다), 표준 ssh-agent 프로토콜을 쓰므로 git과 CLI가 바로 그 에이전트를 거쳐 서명할 수 있습니다. 지문은 키마다 보이므로, GitHub나 GitLab에 맞는 공개 쪽을 등록하는 일이 ~/.ssh 폴더 다섯 개를 뒤지는 대신 복사-붙여넣기가 됩니다. 위의 계정과 별칭 저글링은 설정 파일 퍼즐이 아니라 호스트별 설정이 됩니다.

Termalin은 무료 크로스 플랫폼 SSH 클라이언트로, git이 거쳐 서명할 수 있는 한 번 잠금 해제 에이전트로 키를 관리합니다. 다운로드하거나, 키를 안전하게 다루는 방식을 읽어 보세요.