Jekyll 블로그 빌드가 자꾸 멈춘다면? 이미지 변환 작업 타임아웃 해결법

은퇴 후 블로그를 시작했는데 자꾸만 빌드가 실패한다

작년 대학을 정년퇴직하고 여유로운 일상을 보낼 줄 알았다. 하지만 40년간 연구한 내용을 후학들과 나누고 싶다는 욕심에 Jekyll 기반 GitHub Pages 블로그를 개설했다. 초기엔 텍스트 포스팅만 하니 문제없었다. 그런데 학생들이 논문의 시각화 자료들을 더 보고 싶다고 해서 고화질 이미지를 대량으로 업로드하기 시작했다. 그 순간부터 악몽이 시작됐다.

매번 빌드할 때마다 GitHub Actions에서 몇 분을 버티다가 돌연 실패 메시지를 던졌다. 처음엔 내 마크다운 문법이 잘못된 줄 알고 한 줄 한 줄 점검했다. 젊은 시절 같았으면 바로 해결했을 텐데, 요즘은 새로운 기술이 자꾸만 낯설었다. 그러던 중 GitHub의 공식 이슈 게시판을 발견했고, 정확히 같은 증상을 호소하는 사람들을 수십 명이나 발견했다.

빌드가 멈추는 진짜 이유: 이미지 변환 작업의 타임아웃

알고 보니 이 문제는 매우 흔한 것이었다. Jekyll이 블로그를 빌드할 때 이미지 최적화를 위해 자동으로 변환 작업을 수행한다. 특히 WEBP 형식으로의 변환, 썸네일 생성, 해상도 조정 같은 복잡한 이미지 처리를 진행하게 되는 것이다.

문제는 GitHub Actions의 빌드 환경이 무한정 기다려주지 않는다는 점이었다. 일반적으로 30분 정도의 제한 시간이 있는데, 고해상도 이미지가 많거나 플러그인 설정이 과도하면 이 시간을 초과하게 되는 것이다. 내 경우 학술 자료의 특성상 A4 크기의 고해상도 스캔본들이 무더기로 들어가 있었다. 각 이미지마다 5~10MB가 넘었던 탓이었다.

그 외에도 몇 가지 원인들이 있었다. 플러그인의 의존성 문제로 인한 무한 루프, 캐시되지 않은 상태에서의 반복 처리, 그리고 Ruby 버전과의 호환성 문제도 있었다. 마치 내가 학생들의 논문을 검수할 때처럼 작은 실수들이 쌓여 문제를 일으키고 있었던 것이다.

현명한 해결책들: 경험담과 함께

첫 번째 방법은 가장 기본적이지만 효과적이었다. 바로 이미지 파일 자체를 최적화하는 것이다. 빌드 전에 미리 이미지 압축 도구(TinyPNG, ImageOptim 등)를 사용해서 파일 크기를 줄이는 방식이다. 처음엔 번거로울 것 같았지만, 대학원 시절 데이터 정리하던 습관이 도움이 됐다. 1000개의 이미지를 한 번에 배치 처리할 수 있도록 스크립트를 짜면 되기도 했다.

두 번째는 Jekyll의 설정 파일(_config.yml)을 손보는 방법이다. 불필요한 이미지 변환 플러그인을 비활성화하거나, 병렬 처리 수를 줄이는 식으로 조정할 수 있다. 나는 WEBP 자동 변환 기능을 끄고, 꼭 필요한 경우만 수동으로 처리하기로 결정했다. 이렇게 하니 빌드 시간이 원래 20분대에서 5분 이내로 단축됐다.

세 번째는 GitHub Actions의 워크플로우 파일 자체를 수정하는 것이었다. 타임아웃 시간을 늘리거나(최대 360분까지 가능), 캐싱 메커니즘을 강화하는 방식이다. 이전 빌드의 결과를 재사용하면 다시 처리할 필요가 없으니까 말이다. 사실 이 부분이 가장 효과적이었다.

현재의 안정적인 운영 방식

지금은 매달 30~50개 정도의 포스팅을 하고 있는데, 빌드 실패는 거의 없다. 무엇이 달라졌나? 첫째, 포스팅 전에 이미지를 반드시 최적화한다. 둘째, 불필요한 플러그인은 과감히 제거했다. 셋째, 한 번의 대규모 변경보다는 점진적인 업데이트를 선호한다.

시니어 개발자나 블로거라면 이 경험이 도움될 것 같다. 처음부터 완벽하게 설정하려고 하면 오히려 복잡해진다. 차라리 심플하게 시작해서 문제가 생길 때마다 해결하는 방식이 훨씬 현명하다. 과거 내가 연구 논문을 쓸 때도 그랬으니까.

혹시 당신도 Jekyll 빌드로 고민 중이라면, 위의 세 가지 방법을 차례로 시도해보시길 권한다. 어떤 방법이 가장 효과적이었는지, 또 다른 해결책이 있었는지 댓글로 공유해주시면 좋겠다.