GitHub Pages가 갑자기 배포 안 됨? Jekyll 빌드 캐시 문제 해결기

아무것도 바꾼 게 없는데 왜 안 돼?

40년을 대학에서 강의하다가 은퇴하고 난 후, 틈틈이 공부한 내용들을 정리하고 싶어 GitHub Pages에 Jekyll 블로그를 만들었다. 처음 몇 달은 순조로웠다. 마크다운으로 글을 쓰고 푸시하면 자동으로 배포되는 마법 같은 경험을 했다. 하지만 인생의 많은 것이 그렇듯, 이 행운은 오래가지 않았다.

어느 날 아침, 새로운 포스트를 작성하고 깃허브에 푸시했다. 언제나처럼 자동 빌드가 진행될 것이라 생각했는데, 몇 분이 지나도 사이트가 업데이트되지 않았다. GitHub Pages 설정 페이지를 확인해보니 빨간 X 표시와 함께 “Build failed”라는 메시지가 떠 있었다.

“뭐가 문제지?” 라는 생각이 들었다. 코드는 건드리지 않았고, 단지 마크다운 파일 하나를 추가했을 뿐이다. 전 세계 수천 명의 개발자들이 매일 같은 상황에서 헤매고 있다는 걸 나중에 알았지만, 그 순간에는 정말 답답했다.

Jekyll 빌드 캐시의 숨은 얼굴

문제를 해결하기 위해 깃허브 저장소의 Actions 탭을 열었다. 상세 로그를 보니 “Gemfile.lock 파일이 손상되었거나 종속성 버전 충돌”이라는 메시지가 있었다. 내가 로컬에서는 잘 작동하는데 왜 깃허브 서버에서만 문제가 생기는지 궁금했다.

그 이유는 바로 빌드 캐시였다. GitHub Pages의 빌드 시스템은 이전 빌드 결과를 캐시하여 빠른 배포를 제공한다. 하지만 이 캐시가 때로는 방해물이 된다. 특히 Gemfile을 수정했거나, Jekyll 플러그인을 추가했을 때, 아니면 Ruby 버전이 변경되었을 때 캐시된 의존성과 새로운 의존성이 충돌하는 문제가 발생한다.

내가 사용 중인 Chirpy 테마도 수많은 의존성을 가지고 있다. bundle install로 로컬 환경에서는 최신 버전의 gems가 설치되지만, GitHub 서버의 캐시에는 예전 버전 정보가 남아 있을 수 있다. 이것이 정확히 내가 겪은 문제였다.

해결책: 세 가지 방법으로 배포 정상화하기

첫 번째 방법: Gemfile.lock 파일 재생성

가장 간단한 해결책은 Gemfile.lock을 삭제하고 새로 생성하는 것이다. 로컬 터미널에서:

rm Gemfile.lock
bundle install
git add Gemfile.lock
git commit -m "Update Gemfile.lock"
git push

이렇게 하면 깃허브에 가장 최신의 의존성 정보가 푸시되고, 빌드 시스템이 이를 기준으로 새로 캐시를 만든다.

두 번째 방법: GitHub Actions 캐시 강제 삭제

더 강력한 해결책은 GitHub Actions의 캐시를 직접 삭제하는 것이다. 저장소의 Settings > Actions > General > Cache에서 “Clear all”을 클릭하면 된다. 이 방법은 캐시와 관련된 모든 문제를 한 번에 해결할 수 있다.

세 번째 방법: jekyll-cache 폴더 정리

로컬에서 jekyll build --clean 명령을 실행하여 빌드 캐시를 정리한 후 다시 푸시하는 방법도 있다:

jekyll clean
jekyll build
git add .
git commit -m "Clean Jekyll cache"
git push

노교수의 교훈: 예방이 최고의 치료

이 문제를 겪으면서 깨달은 가장 큰 교훈은 무엇인가? 정기적인 유지보수의 중요성이다.

매월 한 번씩 bundle update를 실행하여 의존성을 최신으로 유지하고, 3개월마다 로컬 환경에서 jekyll clean && jekyll build를 실행하는 습관을 들였다. 또한 Gemfile을 수정할 때마다 Gemfile.lock도 함께 업데이트하도록 신경 썼다.

40년을 강의하면서 배운 경험이 여기서도 똑같이 적용되었다. 작은 체계를 꾸준히 유지하는 것이 큰 문제를 예방한다는 것이다. 블로그도, 프로그래밍도, 인생도 마찬가지인 것 같다.

지금은 배포 오류를 거의 겪지 않는다. 그리고 혹시 또 다른 에러가 생기더라도, 문제의 원인이 어디 있을 가능성이 높은지 체계적으로 접근할 수 있게 되었다. 이것이 기술을 배우는 진정한 가치가 아닐까 생각한다.

당신도 Jekyll 블로그를 운영하면서 비슷한 경험을 하고 있다면, 지금 바로 이 세 가지 방법 중 하나를 시도해보세요. 그리고 경험담이나 질문이 있다면 댓글로 남겨주세요!