GitHub Pages에서 로컬 Jekyll 빌드가 자꾸 실패하는 이유, 드디어 찾았습니다

나의 GitHub Pages 블로그 여정, 그 첫 번째 난관

올해 67세인 나는 지난 3년간 GitHub Pages와 Jekyll로 기술 블로그를 운영해왔습니다. 정년 이후 남은 시간에 평생 연구해온 컴퓨터과학 지식을 후배 개발자들과 나누고 싶었거든요. 그런데 작년 가을쯤부터 정말 이상한 문제가 발생했습니다. 로컬 환경에서는 완벽하게 작동하는 Jekyll 사이트가 GitHub에 푸시하면 갑자기 빌드에 실패하는 것이었습니다.

처음에는 단순히 Ruby 버전 문제라고 생각했습니다. 하지만 ruby --version을 확인해도, bundle update를 실행해도 문제는 계속되었습니다. GitHub Actions 로그를 살펴봤을 때는 “Liquid Exception” 같은 모호한 에러 메시지만 반복되었죠. 정년을 맞이한 후 블로그가 취미가 되어버렸는데, 이 문제 때문에 며칠을 날밤을 새우다시피 하며 디버깅했습니다.

범인은 바로 테마 버전 불일치였습니다

한 달을 꼬박 고민한 끝에, 마침내 문제의 원인을 발견했습니다. 바로 로컬 머신에 설치된 Chirpy 테마 버전과 GitHub의 Ruby 환경에서 사용되는 Gemfile.lock의 버전이 달랐던 것입니다.

제 경우에는 Chirpy 테마의 로컬 버전이 6.x였는데, Gemfile에는 여전히 5.x 대역의 의존성이 명시되어 있었습니다. 로컬 머신에서는 이미 업그레이드된 테마로 개발했기 때문에 문제가 없었지만, GitHub Actions가 실행될 때는 구 버전의 의존성을 설치하려다 충돌이 발생했던 것입니다.

이는 마치 대학에서 강의할 때 교과서 개정판은 새 것을 쓰는데 학생들에게만 옛 버전을 나눠주는 것과 같은 상황이었습니다. 신기술과 구기술의 혼재로 인한 혼란이 생기는 것이죠. 저는 이 경험을 통해 버전 관리의 중요성을 몸소 깨달았습니다.

해결 방법: Gemfile과 Gemfile.lock의 동기화

문제를 해결하기 위해 저는 다음과 같은 단계를 거쳤습니다.

먼저 로컬 환경에서 bundle update를 실행하여 모든 의존성을 최신 상태로 업데이트했습니다. 그 다음 생성된 Gemfile.lock을 열어 현재 설치된 모든 gem의 정확한 버전을 확인했습니다. 특히 jekyll-theme-chirpy의 버전이 무엇인지 주의 깊게 살펴봤죠.

gem 'jekyll-theme-chirpy', '~> 6.1.0'

이 한 줄의 코드가 GitHub와 로컬 환경 모두에서 동일하게 작동하도록 만들어주었습니다. 그 후 수정된 Gemfile과 Gemfile.lock을 모두 커밋하여 GitHub에 푸시했습니다.

가장 중요한 부분은 GitHub Pages의 설정입니다. 저는 .github/workflows/pages.yml 파일을 확인하고, 이 파일이 최신 Ruby 버전(당시 3.2.x)을 사용하도록 설정되어 있는지 검증했습니다. 때로는 GitHub의 기본 설정이 구버전의 Ruby로 설정되어 있을 수 있기 때문입니다.

선배 개발자로서 드리는 조언

지난 3년간 블로그를 운영하면서 얻은 경험을 바탕으로 말씀드리자면, GitHub Pages와 Jekyll의 조합은 정말 훌륭하지만, 버전 관리를 철저히 하지 않으면 예상치 못한 문제가 발생한다는 것입니다.

특히 로컬 환경과 원격 환경(GitHub)의 차이를 항상 염두에 두어야 합니다. 로컬에서 작동한다고 해서 GitHub에서도 작동하는 것은 아니기 때문입니다. 이를 방지하기 위해 저는 이제 다음과 같은 체크리스트를 사용합니다.

1. 새로운 포스트를 작성한 후, 반드시 bundle exec jekyll serve로 로컬 테스트
2. 매월 한 번씩 bundle update를 실행하여 의존성 최신화
3. GitHub Actions 로그를 항상 확인하고, 에러 발생 시 즉시 대응
4. Gemfile.lock은 절대 .gitignore에 추가하지 않기

이러한 습관이 지금의 저를 불필요한 디버깅 시간으로부터 구해냈습니다. 제 블로그는 이제 매주 안정적으로 새로운 포스트를 배포하고 있으며, 독자분들도 언제나 최신 내용을 볼 수 있게 되었습니다.

혹시 여러분도 GitHub Pages에서 비슷한 문제를 겪고 계신다면, 먼저 버전 불일치를 의심해보세요. 그리고 댓글로 여러분의 경험담을 공유해주시면, 함께 이 문제를 해결하