GitHub Actions EC2 배포 실패: SSH 키 인증 실패 문제 해결

에러 코드 및 문제 정의

GitHub Actions를 이용해 Spring Boot 프로젝트를 EC2 서버에 배포하려는 과정에서 다음과 같은 SSH 인증 실패 에러가 발생했다.

ssh: handshake failed: ssh: unable to authenticate, attempted methods [none], no supported methods remain

 

이 에러는 GitHub Actions에서 사용하는 .pem 개인 키와 EC2 인스턴스의 ~/.ssh/authorized_keys에 등록된 공개 키가 서로 일치하지 않아 인증에 실패한 것이 원인이었다.

 

CI 파이프라인 상에서 다음과 같은 액션을 사용 중이었다.

uses: appleboy/ssh-action@master

 

하지만 EC2 인스턴스는 이 요청을 허용하지 않았고, 인증 handshake에서 즉시 끊겼다.

 

---

 

시도한 해결 방법과 그 이유

처음에는 다음과 같은 가능성을 의심했다.

• GitHub Secrets에 등록한 .pem 키에 줄바꿈(\n) 또는 공백이 누락되었을 가능성
• GitHub Actions의 key 경로 설정이 잘못되었을 가능성
• pem 파일의 포맷이 GitHub Actions에서 파싱되지 않는 문제

그래서 다음과 같은 조치를 시도했다.

• .pem 키를 다시 로컬에서 복사해 GitHub Secrets에 등록했다.
• Actions에서 base64 디코딩 방식을 점검했다.
• key 관련 인자 값을 재확인 하고 수정했다.

하지만 여전히 같은 에러가 발생했고, 결국 EC2 인스턴스에서 등록된 공개키 자체가 잘못되었음을 의심하게 되었다.

 

---

 

최종 문제 해결 방법

1. .pem 파일로부터 공개키 추출

GitHub Actions에서 사용하는 .pem 키 파일로부터

공개키를 직접 추출하여 EC2 인스턴스의 authorized_keys에 등록했다.

ssh-keygen -y -f spring-project.pem > spring-project.pub

 

2. EC2 인스턴스에 접속해 authorized_keys 파일 덮어쓰기

cat ~/.ssh/authorized_keys      # 기존 키 확인
nano ~/.ssh/authorized_keys     # 새 공개키로 완전히 덮어쓰기

 

3. .ssh 디렉토리와 키 파일 권한 설정

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chown ubuntu:ubuntu ~/.ssh -R

 

authorized_keys 파일의 권한이 잘못되면 SSH 인증이 실패하므로 반드시 위 권한을 맞춰야 한다.

 

4. GitHub Actions에서 SSH 액션 최신 버전 사용

uses: appleboy/ssh-action@master
uses: appleboy/scp-action@master

 

---

 

중요 개념

1.  SSH 공개키 인증 방식

SSH는 공개키 기반 인증을 지원한다. 이 방식은 다음과 같은 구조로 작동한다:

• 클라이언트 (GitHub Actions): .pem 형식의 개인키를 가지고 있다.
• 서버 (EC2): ~/.ssh/authorized_keys 파일에 해당 공개키가 등록되어 있어야 한다.
• 클라이언트가 접속할 때 개인키로 서명하고, 서버는 등록된 공개키로 이를 검증하여 인증을 허용하는 것이다.

즉, 공개키와 개인키는 반드시 짝을 이루어야 하며, 하나라도 틀리면 인증이 실패한다.

2.  authorized_keys 파일

• EC2 서버가 허용하는 공개키를 저장하는 파일이다.
• SSH 접속 시 이 파일 내 공개키 목록을 기반으로 클라이언트 키를 검증한다.
• 해당 사용자 홈 디렉토리의 ~/.ssh/authorized_keys 위치에 있어야 한다.

3.  .pem 키 파일

• AWS에서 EC2 인스턴스를 생성할 때 다운로드할 수 있는 개인키 파일이다.
• GitHub Actions의 Secrets에 등록되어, 서버에 접속할 때 사용된다.
• .pem 키 파일로부터 공개키를 추출할 수 있으며, 추출된 키가 서버의 authorized_keys와 정확히 일치해야 한다.

ssh-keygen -y -f spring-project.pem > spring-project.pub

이 명령어는 .pem 키에서 해당하는 공개키를 생성한다.

 

---

 

마무리

이번 에러는 단순히 "키가 안 맞는다"는 메시지로 보였지만,

그 안에는 SSH 인증의 핵심 원리와 EC2 보안 설정의 중요한 개념들이 숨어 있었다.

다음부터는 배포 오류가 발생했을 때 단순히 GitHub Secrets을 의심하기보다는,

공개키와 개인키의 정확한 매칭 여부부터 확인하는 습관을 들여야겠다.