블로그 빌드가 자꾸 멈춘다면? 이미지 변환 작업의 숨은 함정

지난주 금요일 오후, 평소처럼 블로그에 새 포스트를 올렸는데 이상한 일이 발생했습니다. GitHub Actions 빌드 작업이 자꾸만 멈춰 있었던 겁니다. 화면에는 “running jobs”라는 메시지만 계속 떠 있고, 시간이 지날수록 타임아웃 경고가 나타났습니다. 정년퇴직 후 여유 시간을 이용해 운영하던 기술 블로그라 그렇게 급하지는 않았지만, 원인을 파악하고 싶은 호기심은 멈출 수 없었습니다.

빌드 작업이 멈추는 증상 분석

처음에는 단순한 네트워크 연결 문제라고 생각했습니다. GitHub Actions 로그를 자세히 살펴보니, 빌드 프로세스가 “image transformation” 단계에서 끝없이 머물러 있었던 것입니다. Jekyll에서 Chirpy 테마를 사용 중이었는데, 이 테마는 이미지 최적화를 위해 자동으로 여러 형식과 크기의 이미지를 생성하는 기능이 있습니다.

문제의 원인은 두 가지였습니다. 첫째, 처리할 이미지가 너무 많았고, 둘째 일부 이미지 파일이 손상되어 있었습니다. 특히 몇 년 전에 다운로드한 이미지 중 메타데이터가 잘못된 것들이 있었는데, 이들이 변환 작업에서 에러를 발생시키면서도 프로세스가 계속 재시도하는 상황이 반복되고 있었던 것입니다. 로그에는 명확한 에러 메시지가 없어서, 처음에는 무엇이 문제인지 파악하기 어려웠습니다.

실제 해결 방법

먼저 로컬 환경에서 빌드를 시도해보았습니다. Ruby 환경이 제대로 구성되어 있다면, 로컬에서 문제를 재현할 수 있고 더 자세한 디버깅 정보를 얻을 수 있습니다. bundle exec jekyll build 명령어를 실행하면서 -V 플래그를 추가하여 verbose 로그를 확인했습니다.

결과적으로 손상된 이미지 파일 하나가 발견되었습니다. 해당 이미지를 다시 다운로드하고 동일한 파일명으로 저장한 후, 나머지 이미지들도 간단한 검증을 거쳤습니다. 특히 다음과 같은 점들을 확인했습니다:

• PNG와 JPG 파일의 헤더 정보가 올바른지 확인
• 이미지 크기가 극단적으로 크지는 않은지 체크
• 파일명에 특수문자나 공백이 포함되어 있지는 않은지 검증

이 과정에서 20년간 대학에서 가르쳐온 습관이 도움이 되었습니다. 문제를 체계적으로 분해하고, 하나씩 확인하는 방법 말입니다. 손상된 이미지를 제거한 후 다시 빌드를 시도했을 때, 이번에는 깔끔하게 완료되었습니다.

예방과 장기 관리 방법

이 경험을 바탕으로 몇 가지 예방 조치를 취했습니다. 첫째, 큰 이미지 파일들은 미리 로컬에서 최적화한 후 업로드하기로 결정했습니다. 둘째, 블로그 저장소에 이미지 검증 스크립트를 추가했습니다. 이 스크립트는 commit하기 전에 모든 이미지 파일의 무결성을 확인합니다.

또한 GitHub Actions의 타임아웃 시간을 더 관대하게 설정하되, 진정한 문제를 감지할 수 있는 체크 로직을 추가했습니다. 특정 이미지 변환에서 과도하게 시간이 걸린다면, 그 이미지의 경로를 로그에 출력하도록 설정했습니다. 이렇게 하면 다음에 비슷한 문제가 발생했을 때 즉시 원인을 파악할 수 있습니다.

시니어 개발자나 블로거로서 배운 점은 이것입니다. 새로운 기술을 사용할 때는 항상 단순한 예제부터 시작하고, 점진적으로 복잡성을 높여가야 합니다. Jekyll Chirpy 테마의 강력한 이미지 최적화 기능도 마찬가지입니다. 충분히 이해한 후 사용해야 나중에 문제가 발생했을 때 빠르게 대응할 수 있습니다.

혹시 당신의 블로그도 비슷한 증상을 겪고 있다면, 이 글의 해결 방법들을 시도해보시고 댓글로 당신의 경험을 공유해주세요. 함께 배우는 것이 우리 개발 커뮤니티의 가장 큰 자산이니까요.