[QRoad]GitHub Actions로 EC2 CI/CD 구축하며 겪은 문제들과 해결 과정

배경상황

팀원들은 모두 유동 IP 환경에서 작업하고 있었기 때문에, EC2 보안 그룹에 팀원들의 IP를 고정으로 등록하는 방식은 현실적으로 불가능했다.

그 결과 서버 접근 및 배포 작업은 항상 나에게 배포 작업이 집중되는 구조였다.
내가 부재한 상황에서는 서버 코드 수정이나 서버 기반 테스트조차 진행하기 어려운 구조이다.

이러한 상황에서 인프라 담당자로서

특정 개인에게 의존하지 않는 배포 환경을 만드는 것이 중요하다고 판단했고,

 

누구나 main 브랜치에 푸시하면 동일한 방식으로 배포가 이루어지는 자동 배포(CI/CD) 구조를 구축할 필요성을 느끼게 되었다.

---

목표 구조

GitHub Actions 기반 EC2 CI/CD 전체 흐름

 

구현하고자 한 흐름은 단순했다.

main 브랜치 push
→ GitHub Actions 실행
→ EC2 서버에 SSH 접속
→ 빌드 및 배포

Spring Boot 애플리케이션을 EC2 단일 서버에 배포하는 구조이며,
배포 트리거는 main 브랜치 push이다.

---

1. 1차 시도: SSH 키 등록만 하면 될 줄 알았다

가장 먼저 한 일은 다음과 같았다.

• GitHub Secrets에 SSH_PRIVATE_KEY 등록
• deploy.yml, deploy.sh 작성
• GitHub Actions 실행

결과는 실패였다.

처음에는 스크립트 문제라고 생각했지만,
곧 근본적인 문제를 깨달았다.

---

2. 문제 1: GitHub Actions는 내 로컬이 아니다

GitHub Actions는 내 로컬 PC에서 실행되는 것이 아니라 GitHub 서버에서 실행된다.

즉,

• EC2 보안 그룹에 내 IP를 허용해도
• GitHub Actions 서버 IP는 허용되지 않아 SSH 접속이 막힌다.

더 큰 문제는, 이 방식으로는 팀원 모두가 사용할 수 있는 CI/CD 구조가 될 수 없다는 점이었다.

---

3. 해결: GitHub Actions 공인 IP를 보안 그룹에 동적으로 추가

조금 더 찾아본 결과, 다음과 같은 방법을 발견했다.

1. GitHub Actions의 공인 IP 대역을 조회
2. 배포 시작 시 EC2 보안 그룹에 SSH(22) 인바운드로 추가
3. 배포 완료 후 다시 제거

이렇게 하면

• 어디서 push하든
• GitHub Actions를 통해 배포 가능

보안적으로도 필요한 순간에만 SSH 포트를 열 수 있다는 장점이 있다.

---

4. 문제 2: AWS 리전 설정 문제

보안 그룹을 수정하는 과정에서 계속 오류가 발생했다.
AWS 자격 증명 설정도 정상적으로 되어 있었고,
GitHub Actions 로그상에서도 명확한 원인을 찾기 어려웠다.

문제를 하나씩 점검하던 중, AWS 리전 설정을 다시 확인하게 되었다.

GitHub Actions에서는 configure-aws-credentials 액션을 통해

다음과 같이 리전을 명시하고 있었다.

aws-region:ap-southeast-2

문제는 설정 자체가 아니라 내 생각이었다.

한국 서비스이기 때문에 EC2 인스턴스와 보안 그룹이 당연히 ap-northeast-2(서울) 리전에 있을 것이라고 생각했지만, 실제로 사용 중인 리전은 ap-southeast-2(시드니)였다.

이로 인해 보안 그룹 수정 요청이 의도한 리전이 아닌 다른 리소스를 대상으로 실행되고 있었고, 계속해서 실패 원인을 잘못 추적하고 있었다.

이 경험을 통해 AWS 리전은 사용자의 위치나 서비스 대상 국가 기준이 아니라,
리소스가 실제로 생성된 리전 기준으로 동작한다는 점을 명확히 이해하게 되었다.

---

5. 문제 3: AWS 자격 증명 누락

다음으로 마주한 에러는 AWS 인증 관련 문제였다.

로컬에서는 aws configure로 설정해두었지만, GitHub Actions 환경에서는 별개였다.

해결 방법은 명확했다.

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

를 GitHub Secrets에 등록하고 Actions에서 사용하도록 설정했다.

---

6. 문제 4: SSH 키는 “문자열”이 아니라 “파일”이다

이후 SSH 단계에서 다시 실패했다.

원인은 SSH_PRIVATE_KEY를 Secret으로만 등록하고,

실제 파일로 생성하지 않았기 때문이었다.

해결은 다음과 같았다.

Secret은 문자열일 뿐이고, SSH는 실제 키 파일을 요구한다는 점을 놓치고 있었다.

---

7. 문제 5: 자잘한 오타들

이 시점부터는 정말 사소한 문제들이 발목을 잡았다.

• 경로 오타
• 명령어 오타
• 스크립트 실행 순서 문제

로직이 아닌 오타 문제로인해 많은 시간이 소모되었다.

오류의 원인이 오타라는것을 발견했을때는 큰 허무함을 느꼈다.

---

8. GitHub Actions 성공… 그런데 배포는 안 됨

드디어 GitHub Actions는 정상적으로 성공했다.

하지만 서버에는 아무 변화가 없었다.
빌드와 배포 명령이 제대로 동작하지 않고 있었다.

---

9. 문제 6: env 환경변수 미인식

원인은 환경변수였다.

• EC2 서버에는 .env 설정이 되어 있었지만
• GitHub Actions에서 SSH로 실행한 세션에서는 이를 읽지 못했다

결국 해결 방법은 다음과 같았다.

• GitHub Actions에서 직접 환경변수 주입
• 민감한 값은 GitHub Secrets 사용

---

10. 운영 중 발생한 문제: 디스크 용량 부족

CI/CD 구축 이후 며칠 동안은 배포가 정상적으로 동작했다.
하지만 일정 시간이 지난 후, 서버가 정상적으로 동작하지 않는 문제가 다시 발생했다.

로그를 확인해보니 원인은 디스크 용량 부족이었다.

GitHub Actions를 통한 배포 과정에서
빌드 결과물과 로그 파일이 지속적으로 누적되었고,
이를 정리하지 않은 상태로 운영하다 보니 디스크가 가득 차게 되었다.

 

해결 방법:

• 오래된 빌드 파일 정리
• 불필요한 로그 및 캐시 삭제
• 디스크 클린 명령을 배포 스크립트에 추가

이후에는 배포가 반복되더라도 디스크 용량 문제가 발생하지 않도록 개선했다.

---

11. 회고

처음에는 “금방 끝나겠지”라고 생각했다.
조금만 더, 조금만 더 하다 보니 결국 밤을 새웠고,

다음 날 학교에 택시를 타고 가는 상황까지 갔다.

신기하게도, 잠을 자고 맑은 정신으로 다시 보니
그동안 보이지 않던 오타들과 실수들이 한눈에 들어왔다.

이번 경험을 통해 느낀 점은 분명하다.

• GitHub Actions는 단순한 YAML 자동화 도구가 아니다
• 네트워크, 보안, 서버 환경을 함께 이해해야 제대로 쓸 수 있다
• 그리고 삽질은 결국 이해로 이어진다

---

마무리

GitHub Actions를 이용한 CI/CD 구축은 강력하지만,

처음 접하면 생각보다 많은 함정이 있다.

이 글이 비슷한 구조를 구현하려는 분들께 조금이나마 도움이 되었으면 좋겠다.

CI/CD 관련 설정 코드는 https://github.com/kakao-techforimpact-qroad/BE/tree/main/.github/workflows에 정리되어 있다.

BE/.github/workflows at main · kakao-techforimpact-qroad/BE