GitHub Pages에서 Jekyll 빌드 실패? 로컬 환경 설정이 답이다

대학에서 35년간 컴퓨터공학을 가르치다 은퇴한 나는 요즘 개인 기술 블로그를 운영하며 세월을 보내고 있습니다. GitHub Pages와 Jekyll을 처음 접했을 때만 해도 얼마나 답답했는지요. 로컬에서는 멀쩡히 작동하는데 GitHub에 푸시하면 자꾸만 빌드가 실패하는 경험을 여러 번 겪었습니다. 그렇게 해매던 중 깨달은 핵심적인 해결책을 지금 여러분과 나누고자 합니다.

GitHub Actions와 로컬 환경의 미묘한 차이 이해하기

많은 분들이 놓치는 부분이 바로 이것입니다. GitHub Pages가 자동으로 실행하는 Jekyll 빌드 환경과 여러분의 로컬 개발 환경이 완전히 동일하지 않다는 사실 말입니다. 나도 처음에는 “내 컴퓨터에서 되는데 왜 GitHub에서 안 되지?”라며 한참을 헤맸습니다.

GitHub Pages의 빌드 환경은 Ubuntu 기반의 특정 버전의 Ruby, Bundler, Jekyll을 사용합니다. 반면 개발자 개인의 로컬 환경은 macOS, Windows, Linux 등 다양한 OS에서 다양한 버전의 도구들을 사용합니다. 특히 Ruby 버전이 다르거나, gem의 버전이 정확히 맞지 않으면 로컬에서는 성공해도 GitHub 서버에서는 실패하곤 합니다.

이를 해결하는 가장 효과적인 방법은 로컬 환경을 GitHub Pages와 최대한 동일하게 만드는 것입니다. 나는 정년 후 이 방법을 터득하면서 블로그 운영이 훨씬 수월해졌습니다.

Gemfile과 bundler를 활용한 환경 동기화

제일 먼저 해야 할 일은 프로젝트 루트 디렉토리에 Gemfile을 작성하는 것입니다. 이 파일이 바로 마법의 열쇠라고 생각하면 됩니다. 나는 이것을 처음 알았을 때 정말 신세계를 경험한 듯한 기분이었습니다.

source "https://rubygems.org"
gem "jekyll", "~> 4.3.0"
gem "minima", "~> 2.5"
gem "github-pages", "~> 231"

이렇게 작성한 후, 터미널에서 bundle install 명령어를 실행하면 Gemfile.lock 파일이 생성됩니다. 이 lock 파일이 매우 중요합니다. 여기에는 설치된 모든 gem의 정확한 버전이 기록되기 때문입니다.

나중에 로컬에서 bundle exec jekyll serve 명령어로 서버를 실행하면, GitHub Pages와 동일한 환경에서 테스트할 수 있습니다. 처음엔 이 번거로운 과정이 불필요하다고 생각했지만, 나중에는 이것이 얼마나 효율적인지 깨닫게 되었습니다.

_config.yml과 플러그인 호환성 확인하기

두 번째로 중요한 것은 _config.yml 파일의 설정입니다. 특히 플러그인(plugin) 섹션을 주의깊게 살펴봐야 합니다. 나는 처음 블로그를 시작할 때 여러 플러그인을 무분별하게 추가했다가 큰 코를 다쳤습니다.

GitHub Pages는 보안상의 이유로 모든 Jekyll 플러그인을 허용하지 않습니다. 공식적으로 지원되는 플러그인 목록이 따로 있습니다. 나는 이를 모르고 jekyll-admin 같은 플러그인을 추가했다가 계속 빌드가 실패하는 황당한 경험을 했습니다.

_config.yml에서는 반드시 다음과 같이 github-pages 플러그인만 사용하도록 설정해야 합니다:

plugins:
  - github-pages

또한 safe: true 옵션을 설정하면 GitHub Pages와 동일한 제한된 환경에서 로컬 테스트를 할 수 있습니다. 이렇게 하면 배포 전에 문제점을 미리 발견할 수 있으니, 정말 유용한 팁입니다.

실제 경험으로 배운 체크리스트

은퇴 후 블로그를 운영하면서 나는 다음과 같은 체크리스트를 만들었습니다. 이제 새로운 포스트를 올릴 때마다 이것을 따르면 거의 100% 성공합니다.

첫째, bundle install로 gem 의존성을 모두 설치했는가? 둘째, bundle exec jekyll serve로 로컬에서 먼저 테스트했는가? 셋째, _config.yml의 플러그인 목록이 GitHub Pages 공식 지원 목록에 포함되어 있는가? 넷째, 마크다운 파일의 YAML 프런트매터가 올바르게 작성되어 있는가?

이 네 가지만 확인해도 GitHub Pages 배포 실패는 거의 없습니다. 나는 지난 2년간 이 방법으로 무려 100개 이상의 포스트를 성공적으로 배포했습니다.

정년 후 새로운 분야에 도전하면서 배운 가장 큰 교훈은 기술의 근본을 이해하는 것의 중요성입니다. GitHub Pages와 Jekyll의 관계를 제대로 이해하니 더 이상 답답할 일이 없어졌습니다. 여러분도 이 글의 방법을 따라 환경을 설정하고 로컬에서 충분히 테스트한 후 배포하면, 더욱 안정적인 블로그 운영이 가능할 것입니다. 지금 바로 여러분의 Gemfile을 점검해보시고, 다음 포스팅부터는 이 방식으로 진행해보세요.