GitHub Pages에서 Jekyll 빌드 실패? 로컬 테스트로 99% 해결된다

나는 왜 GitHub Pages에서만 계속 실패했을까

대학을 정년퇴직한 지 5년 차, 취미로 시작한 블로깅이 꽤 재미있어서 Jekyll과 GitHub Pages로 개인 블로그를 만들어보기로 했습니다. 처음엔 간단할 거라 생각했죠. 마크다운 파일을 작성하고 GitHub에 push하면 자동으로 사이트가 빌드되는 것 아닙니까. 하지만 현실은 달랐습니다.

포스트를 작성하고 푸시한 지 2분 후 GitHub에서 빌드 실패 알림이 옵니다. 원인을 찾기 위해 GitHub Actions 로그를 들여다보면 “liquid exception” 이런 식의 모호한 에러만 뜹니다. 다시 파일을 수정해서 푸시하고, 또 실패하고… 이 악순환을 반복하다 보니 어느 순간부터는 GitHub Pages 자체가 두려워졌습니다.

그러던 어느 날, 은퇴한 개발자 선배가 물었습니다. “자네, 로컬에서 테스트는 안 해보나?” 그 순간 세상이 바뀌었습니다. 진작 그럴 줄 알았어야 했는데요.

로컬 환경 구성: 30분이면 충분하다

Jekyll을 로컬에서 실행하려면 먼저 Ruby 환경이 필요합니다. 다행히 요즘 macOS에는 기본으로 Ruby가 설치되어 있고, Windows라면 RubyInstaller를 다운로드하면 됩니다.

저는 Mac 환경을 기준으로 설명하겠습니다. 터미널을 열고 다음 명령어를 실행합니다:

gem install bundler
gem install jekyll

그 다음 GitHub Pages 저장소를 클론한 폴더에서 Gemfile이 있는지 확인합니다. Chirpy 테마를 쓰고 있다면 이미 있을 겁니다. 그 폴더에서:

bundle install
bundle exec jekyll serve

이것만으로 끝입니다. 브라우저에서 http://localhost:4000으로 접속하면 로컬 서버가 실시간으로 당신의 블로그를 보여줍니다. 파일을 저장하면 자동으로 새로고침되죠.

이 과정에서 가장 중요한 것은 Gemfile과 Gemfile.lock을 GitHub 저장소에 커밋하는 것입니다. 이것이 로컬 환경과 GitHub Pages 서버의 빌드 환경을 동일하게 만들어주는 핵심입니다. 같은 버전의 Jekyll과 플러그인을 사용하게 되니까요.

로컬 테스트가 막아준 세 가지 에러들

지난 5년간 로컬 테스트로 얼마나 많은 시행착오를 줄였는지 모릅니다. 가장 흔했던 세 가지 에러를 꼽아봅니다.

첫째, YAML Front Matter의 날짜 형식입니다. 저는 처음에 2026-06-14라고만 썼다가 Jekyll이 이를 문자열로 인식해서 날짜 정렬이 안 됐습니다. 로컬에서 테스트했으면 글 목록 순서가 이상한 것을 즉시 알아챘을 텐데, GitHub에 올린 후에야 발견했죠. 정확한 형식은 2026-06-14 09:00:00 +0900입니다.

둘째, 플러그인 호환성입니다. Chirpy 테마에서 권장하는 플러그인들이 특정 Ruby 버전에서는 작동하지 않습니다. 로컬에서 bundle install을 실행하면 즉시 충돌 에러가 나타나고, 이를 수정한 후 GitHub에 올릴 수 있습니다.

셋째, Liquid 템플릿 에러입니다. 블로그 포스트에서 중괄호나 퍼센트 기호를 쓸 때 실수로 Jekyll이 이를 변수로 인식하기도 합니다. 로컬 서버에서는 “liquid exception”이라며 정확히 어느 줄이 문제인지 알려줍니다. 그걸 보고 수정하고 다시 확인할 수 있죠.

결국 시간이 곧 돈이다

은퇴 후 가장 귀한 자산은 시간입니다. 저는 로컬 테스트를 시작한 이후로 GitHub Pages 빌드 실패를 거의 경험하지 않습니다. 가끔 테마를 업데이트할 때마다 새로운 에러가 발생하기도 하지만, 그 모든 것을 로컬에서 먼저 해결하고 푸시합니다.

또한 로컬에서 테스트하면 실시간으로 변화를 볼 수 있어서 블로그 디자인을 손볼 때도 훨씬 효율적입니다. CSS를 수정하면 바로바로 화면에 반영되니까요.

지금 당신이 GitHub Pages에서 빌드 실패로 고민하고 있다면, 오늘 바로 로컬 환경을 구성해보세요. 30분이면 충분합니다. 그것이 당신의 블로깅 경험을 완전히 바꿔놓을 겁니다.