GitHub Pages에서 Jekyll 빌드 실패? 로컬 환경 동기화가 답이다

내가 겪었던 악몽 같은 경험

은퇴하기 전, 저는 30년을 소프트웨어 개발자로 일했습니다. 그런데 은퇴 후 취미로 기술 블로그를 시작하려고 Jekyll과 GitHub Pages를 만났을 때, 예상치 못한 벽에 부딪혔습니다. 로컬에서는 완벽하게 작동하는 블로그가 GitHub에 푸시하는 순간 빌드 에러로 실패하는 악순환이 반복되었습니다.

당시 저는 에러 로그를 읽으면서 “이게 뭐 하는 짓인가” 싶었습니다. 하지만 조금씩 원인을 파악하면서 깨달은 것이 있었습니다. 문제는 기술이 아니라 환경 관리의 차이였던 것입니다. 오늘은 제 경험을 바탕으로 이 문제를 어떻게 해결했는지 공유하겠습니다.

GitHub Pages 빌드가 실패하는 진짜 이유

로컬 컴퓨터에서 Jekyll을 실행할 때와 GitHub의 자동 빌드 시스템이 사용하는 환경은 미묘하게 다릅니다. 첫 번째 원인은 Ruby 버전의 차이입니다. 저는 최신 버전의 Ruby를 설치했지만, GitHub Pages는 특정 Ruby 버전만 지원합니다.

두 번째는 Gemfile과 Gemfile.lock의 불일치입니다. 처음에 저는 이 파일들의 중요성을 과소평가했습니다. 그러나 Gemfile은 프로젝트의 의존성 명시서이고, Gemfile.lock은 정확한 버전을 고정하는 역할을 합니다. 로컬에서는 최신 버전으로 설치되지만, GitHub에 Gemfile.lock을 커밋하지 않으면 환경이 달라질 수 있습니다.

세 번째는 플러그인 호환성 문제입니다. GitHub Pages는 안전상의 이유로 특정 플러그인만 허용합니다. 저는 멋진 플러그인을 추가했다가 갑자기 빌드가 실패하는 경험을 여러 번 했습니다. _config.yml에 명시한 플러그인이 GitHub의 화이트리스트에 없으면 배포 단계에서 무시되거나 실패합니다.

로컬 환경을 GitHub Pages와 정확히 동기화하기

제 경험상 가장 효과적인 방법은 처음부터 올바른 환경 설정을 하는 것입니다.

먼저 Gemfile을 제대로 구성해야 합니다. GitHub Pages는 github-pages gem을 사용하므로, 다음과 같이 설정했습니다:

source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins

그 다음 터미널에서 bundle install을 실행하면 Gemfile.lock이 자동으로 생성됩니다. 이 파일을 반드시 GitHub에 커밋해야 합니다. 저는 처음에 .gitignore에 Gemfile.lock을 포함시켜 놓아서 한참 헤맸습니다.

또한 _config.yml의 markdown 설정도 중요합니다. GitHub Pages의 기본값은 kramdown입니다. 저는 로컬에서 다른 마크다운 파서를 사용하고 있었는데, 이것도 빌드 실패의 원인이었습니다.

실전 체크리스트로 문제 예방하기

은퇴한 후 많은 시간이 있었기에 꼼꼼하게 체크리스트를 만들었습니다. 이제 새로운 포스트를 작성하거나 설정을 변경할 때마다 이 리스트를 확인합니다.

로컬 테스트 단계: bundle exec jekyll serve를 실행하여 로컬 서버(http://localhost:4000)에서 완벽하게 작동하는지 확인합니다. 이 명령어는 Gemfile.lock에 명시된 정확한 버전으로 Jekyll을 실행하므로 GitHub 환경과 가장 가깝습니다.

커밋 전 검증: _config.yml의 모든 플러그인이 GitHub Pages 공식 문서에 나열되어 있는지 확인합니다. 필요하면 GitHub Actions를 사용하여 사용자 정의 플러그인을 활용할 수 있습니다.

로그 모니터링: GitHub에 푸시한 후 저장소의 ‘Actions’ 탭에서 빌드 로그를 즉시 확인합니다. 에러 메시지는 매우 구체적이므로 이를 통해 문제를 빠르게 식별할 수 있습니다.

개인적으로 가장 도움이 된 것은 Chirpy 테마의 공식 저장소를 클론하여 기본 설정을 참고한 것입니다. 처음부터 올바르게 구성된 예제를 보면서 제 설정과 비교하니 문제점이 명확해졌습니다.

지금은 이 모든 과정이 당연하지만, 처음 겪을 때는 정말 답답했습니다. 하지만 이 경험을 통해 개발 환경과 배포 환경의 일관성이 얼마나 중요한지 다시 한 번 깨닫게 되었습니다. 혹시 여러분도 같은 문제로 고민하고 계신다면, 이 글의 방법들을 차근차근 따라해보길 강력히 추천합니다. 당신의 GitHub Pages 블로그도 확실하게 성공시킬 수 있습니다.