GitHub Actions - GHCR에서 Docker 이미지 Pull 중 발생한 문제 해결

🔍 문제를 찾아간 과정

• GitHub Actions에서 실행한 deploy.yml의 Job 수행 과정에서 문제가 발생한 지점을 확인했다.
• 태그(Tag) 생성, 릴리즈(Release) 작업, 도커 이미지 빌드 및 푸시까지는 정상적으로 완료되었다.
  그러나 새로운 이미지를 다운로드하고 컨테이너를 실행하는 과정에서 오류가 발생했다.
  → docker run 명령이 정상적으로 실행되지 않아 컨테이너가 시작되지 않음.
  

🚨 문제 원인: 잘못된 레지스트리 경로 사용

• GHCR과 Docker Hub는 별개의 레지스트리
  ghcr.io는 GitHub Container Registry(GHCR)이고, docker.io는 Docker Hub임.
  즉, GHCR에서 이미지를 가져오려면 GitHub 사용자명 또는 GitHub 조직명을 사용해야 함.

• GitHub 사용자명과 Docker Hub ID는 다를 수 있음

문제가 발생한 코드

docker pull ghcr.io/[dockerhub 아이디]/${{ env.DOCKER_IMAGE_NAME }}:latest

즉, dockerhub 아이디가 아닌 git 사용자명으로 작성해야한다

해결된 코드 (올바른 경로로 수정)

docker pull ghcr.io/[github 아이디]/${{ env.DOCKER_IMAGE_NAME }}:latest

---

오류가 발생했는데도 Job이 실패로 표시되지 않는 이유

• GitHub Actions에서 실행된 명령어가 실패했어도 GitHub Actions가 이를 감지하지 못하는 경우가 있음.

• 특히 외부 실행 환경(AWS SSM, SSH, Docker 내부 실행 등)에서 오류가 발생할 경우, GitHub Actions 자체는 실행 성공(Success)으로 인식할 가능성이 있음.

🔍 오류를 빠르게 찾는 방법

1. GitHub Actions 로그를 확인
   : Actions 페이지에서 실행된 로그를 확인하여 오류 메시지를 찾기.
   
   
2. set -e로 명령이 실패하면 즉시 종료하도록 설정

set -e
docker pull ghcr.io/[dockerhub아이디]/${{ env.DOCKER_IMAGE_NAME }}:latest

3. echo $?로 Exit Code 확인
   : Exit Code가 0이 아니면 오류가 발생한 것을 의미

docker pull ghcr.io/[dockerhub아이디]/${{ env.DOCKER_IMAGE_NAME }}:latest
echo "Docker Pull Exit Code: $?"

4. set -x로 실행되는 명령어 로그 출력

set -x
docker pull ghcr.io/[dockerhub아이디]/${{ env.DOCKER_IMAGE_NAME }}:latest

정리 및 요약

방법	역할
set -e	명령어가 실패하면 즉시 종료하여, 오류 발생 시 Job이 계속 진행되지 않도록 방지
echo $?	각 명령어의 종료 상태(Exit Code)를 출력하여, 오류 발생 여부를 직접 확인 가능
set -x	실행되는 모든 명령어를 로그에 출력하여, 실행 흐름을 디버깅하고 환경 변수 값을 확인 가능

set -e, echo $?, set -x 모두 GitHub Actions에서 실행되는 deploy.yml 내의 run 단계에서 추가하면, 해당 Job에서 발생하는 오류를 효과적으로 파악할 수 있다.