GitHub Pages에서 Jekyll 빌드 실패? 로컬 테스트로 99% 해결하는 법

프롤로그: 깃허브에 푸시했는데 왜 자꾸 실패할까?

내가 처음 Jekyll로 블로그를 만들던 2023년만 해도, 로컬 환경에서는 멀쩡히 돌아가던 사이트가 GitHub Pages에 푸시되는 순간 빨간 오류 메일이 날아왔다. 대학에서 30년간 컴퓨터공학을 가르친 경험이 있어도, 이 젊은 도구들은 처음엔 낯설었다. 하지만 문제는 간단했다. 로컬에서 제대로 테스트하지 않았기 때문이다.

지난 2년간 수십 개의 블로그 포스트를 작성하면서 깨달은 황금률이 있다. 로컬 환경에서 완벽하게 작동하는 것을 확인한 후에만 GitHub에 푸시하라는 것이다. 이 원칙 하나만으로도 불필요한 빌드 실패의 99%를 막을 수 있다.

로컬 환경 구축: 처음 한 번만 제대로

은퇴한 후 시간이 많아지니 세팅에 신경을 쓸 수 있었다. 먼저 Ruby와 Jekyll을 설치하는 것부터 시작했다. macOS를 사용한다면 Homebrew로 쉽게 설치할 수 있다. 터미널을 열고 brew install ruby를 입력한다. 그 다음 gem install jekyll bundler로 Jekyll과 번들러를 설치한다.

GitHub에서 내 저장소를 클론한 후, 해당 디렉토리로 이동해서 bundle install을 실행한다. 이 명령어가 핵심인데, Gemfile에 명시된 모든 의존성을 설치하는 역할을 한다. 많은 사람들이 이 단계를 건너뛰다가 나중에 “missing dependency” 오류를 마주친다.

설치가 완료되면 bundle exec jekyll serve를 입력한다. 이 명령어 앞의 bundle exec가 중요하다. 이것이 있어야 Gemfile에 정의된 정확한 버전의 gem들이 사용된다. GitHub Pages도 같은 방식으로 동작하므로, 로컬 환경이 GitHub의 빌드 환경과 일치하게 된다.

포스트 작성부터 배포까지: 실전 워크플로우

이제 실제로 블로그를 운영하는 방식을 공유하겠다. 새로운 포스트를 작성할 때마다 나는 다음 순서를 따른다.

먼저 _posts 폴더에 YYYY-MM-DD-title.md 형식으로 파일을 생성한다. 마크다운으로 콘텐츠를 작성한 후, 즉시 로컬에서 bundle exec jekyll serve를 실행한다. 브라우저에서 http://localhost:4000으로 접속하면 빌드된 사이트를 확인할 수 있다. 여기서 모든 것이 예상대로 작동하는지 확인한다.

레이아웃이 깨져 보이거나, 코드 블록이 제대로 표시되지 않는다면, 마크다운 문법을 다시 확인한다. YAML 프론트매터에서 카테고리나 태그 형식이 잘못되면 빌드가 실패할 수 있다. 로컬 환경의 터미널을 보면 어디서 오류가 발생했는지 명확하게 나타난다.

모든 것이 완벽하면 Git에 커밋하고 GitHub에 푸시한다. 이 정도면 GitHub Pages의 빌드가 성공할 확률이 거의 100%에 가깝다. 내 경험으로는 로컬에서 bundle exec jekyll serve로 확인된 사이트가 GitHub에서 실패한 적이 단 한 번도 없다.

자주 겪는 문제와 해결법

시간이 흐르면서 특정한 패턴의 오류들을 여러 번 마주쳤다. 첫째, Gemfile.lock 파일이 로컬과 GitHub에서 불일치하는 경우다. 이는 bundle update를 실행해서 해결했다. 둘째, 플러그인 버전 문제인데, GitHub Pages가 지원하는 플러그인만 사용하도록 주의해야 한다.

셋째는 마크다운 렌더링 문제다. Chirpy 테마를 사용할 때 특정 마크다운 구문이 예상과 다르게 표시될 수 있다. 로컬에서 미리 확인하면 이런 문제를 즉시 발견하고 수정할 수 있다.

에필로그: 습관이 최고의 도구

지난 2년간 나는 ‘로컬에서 먼저 확인’이라는 단순한 원칙으로 수백 개의 불필요한 빌드 실패를 막았다. 은퇴 후 블로그를 운영하면서 배운 가장 큰 교훈은, 신기술도 결국 기본 원칙을 따를 때 가장 잘 작동한다는 것이다. 당신도 오늘부터 포스트를 작성한 후 바로 GitHub에 푸시하지 말고, 로컬에서 한 번 더 확인해보자. 그 작은 습관이 당신의 블로그 운영을 얼마나 더 즐겁게 만들 것인지 직접 경험하게 될 것이다.