GitHub Pages에서 Jekyll 빌드 실패? 로컬 테스트로 밤샘 작업 끝내기

프로롤로그: 새벽 3시의 깨달음

작년 이맘때쯤, 나는 은퇴 후 취미로 시작한 개인 블로그를 GitHub Pages로 운영하기로 결심했다. 평생을 컴퓨터공학을 가르쳐온 내가 만만하게 생각했던 첫 배포는 악몽이 었다. 코드를 수정해서 GitHub에 푸시할 때마다 빌드 실패 에러 메일이 들어왔고, 변경사항을 확인하려면 한 시간을 기다려야 했다. 그렇게 며칠을 허비한 후에야 나는 깨달았다. 로컬 환경에서 먼저 테스트하는 것이 얼마나 중요한지 말이다.

오늘 나누고자 하는 것은 바로 그 경험담과 해결책이다.

로컬 환경 구축: Jekyll 설치부터 시작하기

Ruby 언어를 기반으로 하는 Jekyll을 사용하려면 먼저 로컬 컴퓨터에 개발 환경을 갖춰야 한다. 나는 macOS를 사용하고 있는데, 다행히 Homebrew를 통해 간단하게 설치할 수 있었다.

터미널을 열고 brew install ruby를 입력하면 최신 Ruby 버전이 설치된다. 그 다음 gem install bundler jekyll로 Jekyll과 Bundler를 설치하는 것이다. Bundler는 프로젝트의 의존성을 관리해주는 도구인데, 이것이 정말 중요하다.

GitHub Pages에서 제공하는 Chirpy 테마를 사용한다면, 먼저 해당 저장소를 클론해야 한다. 그 후 프로젝트 폴더로 이동해서 bundle install을 실행하면 Gemfile에 명시된 모든 의존성이 설치된다. 이 단계가 바로 나중에 GitHub에서의 빌드 실패를 줄여주는 핵심이다.

당시 나는 이 과정을 너무 대충 넘어갔는데, Windows 사용자라면 WSL(Windows Subsystem for Linux)을 설치하는 추가 단계가 필요할 수 있다. 은퇴 후 기술이 많이 바뀌었다고 생각했지만, 이 부분만큼은 여전히 개발자들이 고생하는 부분이더라.

로컬 서버 실행과 실시간 테스트의 마법

로컬 환경이 준비되면 bundle exec jekyll serve 명령어를 실행하자. 이 한 줄이 정말로 내 인생을 바꿨다. 이 명령어를 실행하면 로컬 서버가 4000번 포트에서 시작되고, http://localhost:4000에서 즉시 블로그를 확인할 수 있다.

더욱 놀라운 점은 이 상태에서 마크다운 파일을 수정하면 자동으로 다시 빌드되어 브라우저를 새로고침하면 바로 변경사항이 반영된다는 것이다. 이전처럼 GitHub에 푸시하고 한 시간을 기다릴 필요가 없다는 뜻이다.

나는 이 기능을 발견했을 때 정말 환호성을 질렀다. 레이아웃 변경, 플러그인 추가, 새로운 포스트 작성 등 모든 것을 즉시 확인할 수 있게 된 것이다. 특히 Chirpy 테마의 다크 모드, 라이트 모드 전환을 테스트할 때 이 기능의 진가가 드러났다.

GitHub과의 완벽한 동기화를 위한 체크리스트

로컬에서 완벽하게 작동하는 것을 확인했다고 해서 GitHub에서도 바로 성공하리라는 보장은 없다. 나는 몇 가지 실수를 더 겪어야 했다.

먼저 _config.yml 파일을 꼼꼼히 확인해야 한다. baseurl, url, timezone 등의 설정이 GitHub Pages 환경과 일치하는지 검토하는 것이다. 내 경우 baseurl을 빈 문자열로 설정해야 했는데, 초반에 이 부분을 놓쳤다.

두 번째로 중요한 것은 Gemfile.lock 파일이다. 이 파일은 현재 로컬에 설치된 정확한 gem 버전 정보를 담고 있다. 이 파일을 GitHub에 함께 올리면 GitHub Pages의 빌드 서버도 동일한 버전으로 빌드하게 되어 호환성 문제가 최소화된다.

세 번째는 .gitignore 파일 확인이다. Chirpy 테마는 이미 적절한 gitignore 설정을 제공하지만, 혹시 모르니 _site 폴더나 .jekyll-cache 같은 빌드 산출물이 무시되는지 확인해야 한다.

마치며

은퇴 후 새롭게 배운 기술들이 많지만, 이렇게 시행착오를 거쳐 습득한 내용이 가장 기억에 남는다. Jekyll과 GitHub Pages로 블로그를 운영하면서 나는 개발 과정에서 로컬 테스트가 얼마나 중요한지 다시 한번 깨달았다.

혹시 당신도 GitHub Pages에서 Jekyll 빌드로 고민 중이라면, 지금 바로 로컬 환경을 구축하고 bundle exec jekyll serve를 실행해보길 권장한다. 그것이 가장 빠르고 확실한 길이 될 것이다.