GitHub Pages 배포 실패? Jekyll 빌드 캐시 문제를 아시나요

은퇴 후 만난 예상 밖의 난제

저는 지난 30년간 대학에서 전산학을 가르쳤습니다. 은퇴 후 조용한 시골집에서 지나온 세월을 기록으로 남기고 싶었고, 그 방법으로 선택한 것이 바로 Jekyll과 GitHub Pages였습니다. 무료이면서도 깔끔하고, 기술적으로 도전할 수 있는 플랫폼이었기 때문입니다.

처음 블로그 셋업은 순조로웠습니다. Ruby를 설치하고, Jekyll을 로컬에서 빌드한 후 GitHub에 푸시했을 때 마법처럼 웹사이트가 나타났죠. 그런데 며칠 뒤 문제가 터졌습니다. 로컬에서는 완벽하게 작동하는 포스트가 GitHub Pages에서는 CSS가 깨지거나 일부 레이아웃이 사라지는 현상이 발생한 것입니다. 처음엔 제 실수라 생각했지만, 같은 코드를 여러 번 푸시해도 문제는 계속되었습니다.

결국 저는 GitHub의 지원팀과 Jekyll 커뮤니티 포럼에서 수십 개의 글을 찾아 읽었고, 그 과정에서 깨달았던 진실이 바로 “빌드 캐시 문제”였습니다. 오늘은 제가 겪었던 이 문제와 해결책을 여러분과 나누겠습니다.

GitHub Pages의 보이지 않는 캐시 메커니즘

GitHub Pages는 여러분의 저장소를 푸시할 때마다 서버에서 자동으로 Jekyll을 실행하여 정적 HTML을 생성합니다. 이 과정 자체는 매우 효율적이지만, GitHub는 성능 최적화를 위해 여러 단계의 캐싱을 적용하고 있습니다.

가장 흔한 문제는 GitHub의 빌드 캐시입니다. 저장소를 새로 푸시했을 때, GitHub는 이전 빌드 결과를 메모리에 보관해두고 있습니다. 만약 _config.yml 파일은 변경하지 않고 포스트 내용만 수정한다면, GitHub는 이전 설정값을 그대로 사용할 수 있다고 판단하는 것입니다. 제 경험상 이것이 CSS 경로가 깨지거나, 테마 설정이 제대로 적용되지 않는 주요 원인이었습니다.

더 복잡한 경우는 gem 의존성 캐시 문제입니다. Gemfile.lock 파일이 로컬과 GitHub 서버에서 다른 버전의 플러그인을 참조하게 되면, 로컬에서는 잘 작동하던 기능이 라이브 서버에서는 예기치 않게 동작합니다. 제가 Chirpy 테마를 처음 설정했을 때, 로컬의 Jekyll이 4.2.1이었는데 GitHub 서버는 여전히 4.1.1을 사용하고 있었던 것입니다.

실제로 효과가 있었던 해결 방법

먼저 가장 간단한 방법부터 설명하겠습니다. GitHub Pages의 빌드 캐시를 강제로 초기화하려면, 저장소의 Settings 탭에서 Pages 섹션을 찾아 현재 배포 소스를 변경했다가 다시 복원하는 방법입니다. 예를 들어 “Deploy from a branch”에서 “GitHub Actions”로 변경한 후 다시 돌아오는 식입니다. 이렇게 하면 GitHub는 이전 캐시를 무효화하고 처음부터 빌드를 수행합니다.

더 근본적인 해결책은 _config.yml 파일을 수정하는 것입니다. 제가 실행했던 방법은 다음과 같습니다. 파일 끝에 간단한 주석이나 공백을 추가하여 파일 해시값을 변경하는 것입니다. 예를 들어:

# Build settings
markdown: kramdown
theme: jekyll-theme-chirpy
# Cache invalidation - 2026-05-18

이렇게 하면 GitHub는 설정 파일이 변경된 것으로 인식하여 전체 빌드 프로세스를 다시 실행합니다. 제 경험상 이 방법이 가장 신뢰할 수 있었습니다.

세 번째로, Gemfile.lock 파일을 명시적으로 업데이트하는 방법도 있습니다. 로컬 머신에서 bundle update 명령을 실행한 후 새로운 Gemfile.lock 파일을 GitHub에 푸시하면, GitHub 서버도 같은 버전의 gem들을 사용하게 됩니다. 저는 이 방법으로 플러그인 호환성 문제를 완전히 해결할 수 있었습니다.

장기적인 예방과 모니터링

정기적인 로컬 테스트 없이는 이러한 문제를 사전에 방지할 수 없습니다. 저는 이제 매주 한 번씩 bundle exec jekyll serve 명령으로 로컬 서버를 띄우고, 생성된 결과물을 충분히 검증한 후에만 GitHub에 푸시합니다. 이 과정이 번거로워 보일지 모르지만, 은퇴 후 배운 가장 중요한 교훈 중 하나는 “시간이 많을 때 철저함으로 미래의 문제를 줄인다”는 것이었습니다.

또한 GitHub의 Actions 탭에서 빌드 로그를 주기적으로 확인하는 습관도 매우 중요합니다. 배포 후에 모든 게 잘됐다고 가정하지 말고, GitHub에서 실제로 어떻게 빌드되었는지 직접 확인해야 합니다. 로그에서 경고 메시지나 deprecated 플러그인에 대한 알림이 있다면, 그것이 바로 향후 캐시 문제의 예신일 수 있습니다.

마지막으로, Jekyll과 GitHub Pages 커뮤니티는 생각보다 활발합니다. 제가 겪은 대부분의 문제들은 이미 누군가 다른 사람이 경험했던 것들이었고, GitHub Discussions나 Stack Overflow에서 답을 찾을 수 있었습니다. 기술적 난제에 부딪혔을 때 혼자 고민하기보다 커뮤니티에 물어보는 것이 훨씬 효율적입니다.

지금 여러분도 비슷한 문제로 고민하고 계신다면, 위의 방법들을 순서대로 시도해보시기 바랍니다. 특히 _config.yml 파일 수정과 GitHub 빌드 로그 확인은 정말로 효과적이었습니다. 혹시 이 글이 도움이 되었다면, 댓글로 여러분의 경험도 공유해주세요.