Jekyll 블로그 배포할 때 이미지 변환 작업에서 멈춘다면?

깃허브 페이지 배포 중 갑자기 멈춰버린 경험

지난 2월, 대학에서 은퇴한 지 3년이 지나면서 취미로 시작한 기술 블로그가 제법 궤도에 올랐습니다. Jekyll과 GitHub Pages로 운영하면서 학생들에게 도움이 될 만한 글들을 꾸준히 올리고 있었는데, 어느 날부터 정말 황당한 문제가 발생했습니다. 새로운 포스팅을 작성하고 깃허브에 푸시하면, 배포 작업이 진행 중 상태에서 계속 멈춰있는 것이었습니다.

처음에는 네트워크 문제라고 생각했습니다. 그런데 몇 시간, 며칠을 기다려도 배포가 완료되지 않았습니다. GitHub Actions 로그를 살펴보니 ‘running jobs (image transformation)’에서 무한정 대기 중이라는 메시지가 떴습니다. 같은 문제를 겪는 개발자들의 이슈를 찾아본 결과, 이것이 꽤 흔한 문제라는 사실을 알게 되었습니다.

문제의 근본 원인: 이미지 처리 라이브러리의 한계

Jekyll Chirpy 테마를 사용하는 경우, 블로그 빌드 과정에서 이미지를 자동으로 변환하는 작업이 포함됩니다. 썸네일 생성, 해상도 최적화, 포맷 변환 같은 작업들이 자동으로 진행되는데, 이것이 정말 편리한 기능입니다. 그러나 특정 상황에서 이 과정이 영원히 끝나지 않는 상태에 빠질 수 있습니다.

제 경우를 분석해보니 몇 가지 공통된 원인이 있었습니다. 첫째, 매우 큰 용량의 고해상도 이미지를 여러 장 한 번에 업로드했을 때였습니다. 둘째, 손상되었거나 형식이 이상한 이미지 파일이 포함되어 있었습니다. 셋째, 변환 라이브러리(ImageMagick, libvips 등)가 특정 이미지 포맷을 제대로 처리하지 못했을 때입니다. GitHub Actions의 제한된 리소스 환경에서 이런 상황이 누적되면, 타임아웃이 될 때까지 무한정 대기하게 되는 악순환이 발생합니다.

실질적인 해결 방법들

저는 여러 방법을 시도해봤습니다. 첫 번째 방법은 가장 간단하지만 효과적이었습니다. 블로그 저장소의 GitHub Actions 워크플로우 파일에서 이미지 변환 작업의 타임아웃 값을 명시적으로 설정하는 것입니다. 무한정 기다리기보다는 일정 시간이 지나면 자동으로 중단되도록 설정하면, 어떤 이미지가 문제를 일으키는지 파악할 수 있습니다.

두 번째 방법은 이미지 최적화를 사전에 진행하는 것입니다. 로컬 환경에서 ImageMagick이나 온라인 도구를 사용하여 이미지를 미리 축소하고 변환한 후 업로드합니다. 특히 폭이 1200픽셀을 넘지 않도록 조정하면, GitHub Actions에서의 처리 부담을 크게 줄일 수 있습니다. 저는 모든 이미지를 800x600 정도의 크기로 통일했더니 문제가 거의 해결되었습니다.

세 번째는 이미지 변환 기능을 완전히 비활성화하는 방법입니다. _config.yml 파일에서 image transformation 관련 설정을 수정하여, 자동 변환을 끄고 수동으로 관리하는 방식입니다. 이렇게 하면 빌드 속도도 빨라지고, 예상치 못한 문제도 줄어듭니다.

배운 점과 예방 방법

은퇴 후 시간이 많아서 취미로 블로그를 운영하는 입장에서, 이 문제는 큰 답답함을 안겨주었습니다. 하지만 문제 해결 과정에서 얻은 교훈이 더 크습니다. 기술은 편리함을 제공하지만, 그 편리함이 항상 안정적이지는 않다는 점을 다시 한 번 깨달았습니다.

예방을 위해 현재 저는 다음과 같은 습관을 들였습니다. 포스팅 전에 항상 로컬 환경에서 bundle exec jekyll build를 실행하여 빌드 과정을 미리 테스트합니다. 이미지는 업로드 전에 반드시 최적화 도구로 처리합니다. 그리고 GitHub Actions 로그를 수시로 확인하여 이상 신호를 조기에 포착합니다.

만약 당신도 Jekyll 블로그 배포 중 이미지 변환에서 멈춰있다면, 절대 당황하지 마세요. 이것은 매우 흔한 문제이며, 충분히 해결 가능합니다. 가장 먼저 GitHub Actions 로그를 자세히 살펴보고, 문제가 되는 이미지 파일을 특정한 후, 위의 방법들을 차례대로 시도해보시길 권장합니다. 혹시 같은 문제를 겪고 계신다면, 댓글로 어떤 방법이 가장 효과적이었는지 공유해주시면 좋겠습니다.