GitHub Pages에서 로컬 Jekyll 블로그가 갑자기 깨진 이유, 그리고 해결책

은퇴 후 블로그를 시작한 노교수의 예상 밖의 경험

제 이름은 김성수이고, 대학에서 35년간 전산학을 가르치다가 2년 전 은퇴했습니다. 정보기술이 빠르게 변하는 분야라는 것을 누구보다 잘 알고 있었지만, 정작 은퇴 후에 최신 기술을 따라가는 것이 얼마나 어려운지 깨닫게 되었습니다. 특히 GitHub Pages와 Jekyll 조합으로 블로그를 운영하면서 말입니다.

처음에는 Chirpy 테마가 얼마나 깔끔한지에 매료되어 블로그를 시작했습니다. 약 6개월간 순조롭게 포스팅을 했고, 로컬 환경에서 jekyll serve 명령어를 치면 정말 잘 작동했습니다. 그런데 어느 날 아침, 아무것도 건드린 게 없는데 갑자기 블로그가 빌드되지 않는 문제가 발생했습니다. 젊은 시절 같았으면 바로 해결했을 문제들인데, 당시의 저는 한참 헤매야 했습니다.

그날의 악몽: Ruby 버전 충돌

처음 만난 오류 메시지는 이것이었습니다:

Bundler could not find compatible versions for gem "jekyll"

저는 처음에 이게 무슨 말인지 이해가 안 됐습니다. 지난 6개월간 아무것도 변한 게 없는데 왜 갑자기 이런 오류가 나타났을까요? 당시에는 컴퓨터를 업데이트한 기억이 있었는데, 그것이 결정적인 원인이었습니다.

제 맥북이 자동으로 Ruby 버전을 업그레이드했던 것입니다. 저는 ruby --version으로 확인해봤고, 충격을 받았습니다. 이전에는 3.0.0이었는데 지금은 3.3.0이 설치되어 있었습니다. 10년 전의 제 자신 같았다면 이것이 심각한 문제라는 것을 즉시 알았을 텐데, 지금의 저는 “숫자만 좀 올라갔잖아?”라고 생각했습니다. 하지만 Ruby의 세계에서는 그렇지 않았습니다.

Gemfile.lock 파일의 비밀

가장 먼저 해야 할 일은 제 로컬 환경을 점검하는 것이었습니다. 명령어를 입력했습니다:

bundle install

이 명령어는 Gemfile과 Gemfile.lock 파일을 읽고, 정확히 맞는 gem 버전들을 설치하라는 의미입니다. 젊은 시절의 저는 이 두 파일의 차이를 명확히 이해했지만, 지금의 저는 다시 한 번 학습해야 했습니다.

Gemfile은 프로젝트에 필요한 gem들을 대략적으로 나열하는 문서이고, Gemfile.lock은 정확한 버전을 기록하는 잠금 파일입니다. 마치 음악 악보와 그 악보를 연주한 실제 녹음본의 차이라고 할 수 있습니다.

제 경우, Gemfile.lock 파일이 오래된 Ruby 3.0.0 버전에서 만들어진 것이었습니다. 새로운 Ruby 3.3.0에서는 일부 gem이 호환되지 않았던 것입니다. 해결책은 간단했습니다:

rm Gemfile.lock
bundle install

Gemfile.lock을 삭제한 후 다시 설치하면, 새로운 Ruby 버전에 맞는 gem들이 설치됩니다. 이것은 은퇴 후 처음 제대로 마주한 ‘버전 관리’라는 개념이었습니다.

GitHub와 로컬 환경의 불일치 문제

하지만 오류는 여기서 끝나지 않았습니다. 로컬에서는 완벽하게 작동했는데, GitHub Pages에 푸시하면 빌드가 실패한다는 알림을 받았습니다. 이것은 더욱 답답한 문제였습니다. 제 컴퓨터에서는 잘되는데 GitHub의 서버에서는 왜 안 되는 걸까요?

GitHub Pages는 GitHub Actions라는 자동화 서비스를 사용합니다. 제 로컬 환경과 GitHub의 빌드 환경이 완벽히 일치해야 합니다. 예를 들어, 저는 최신 Ruby를 사용하고 있었지만, GitHub Actions의 빌드 환경은 여전히 구형 Ruby를 사용하고 있었을 수 있습니다.

이를 확인하기 위해서는 .github/workflows/pages-deploy.yml 파일을 살펴봐야 했습니다. 이것이 바로 GitHub이 어떻게 블로그를 빌드하는지를 정의하는 파일입니다. 저는 그 안에서 Ruby 버전을 명시하는 부분을 찾았습니다:

ruby-version: 3.1

아, 그렇군요! GitHub은 Ruby 3.1을 사용하고 있었습니다. 저는 로컬에서 Ruby 3.3을 사용하고 있었으니 불일치가 생길 수밖에 없었던 것입니다.

해결책은 두 가지였습니다. 첫 번째는 GitHub의 Ruby 버전을 3.3으로 업데이트하는 것, 두 번째는 제 로컬 환경을 3.1로 맞추는 것입니다. 저는 rbenv라는 Ruby 버전 관리 도구를 설치했습니다:

brew install rbenv
rbenv install 3.1.0
rbenv local 3.1.0

이렇게 하면 이 프로젝트 폴더에서는 항상 Ruby 3.1.0을 사용하게 됩니다. 은퇴 후 처음으로 제가 배운 것은 이것이었습니다: 개발 환경의 일관성이 얼마나 중요한가.

마지막 교훈: 문서화의 중요성

모든 것을 해결한 후, 저는 깨달았습니다. 이런 문제들이 왜 더 많은 사람들에게 공유되지 않았는지 말입니다. 물론 공식 문서들이 있었지만, 그것들은 다소 딱딱하고 실제 경험담이 부족했습니다.

저는 이제 정기적으로 환경을 점검하는 습관을 들였습니다:

ruby --version
jekyll --version
bundle --version

그리고 .ruby-version 파일을 프로젝트 루트에 만들어서 Ruby 버전을 명시해두었습니다. 이것은 앞으로 같은 문제가 재발하는 것을 방지하기 위한 작은 예방입니다.

은퇴 후 이 경험은 제게 중요한 교훈을 주었습니다. 기술은 멈추지 않으며, 끊임없이 변합니다. 하지만 기본 원리를 이해하면 새로운 버전에도 대응할 수 있다는 것을 다시 한 번 느꼈습니다.

혹시 당신도 비슷한 문제를 겪고 있다면, 먼저 자신의 Ruby 버전과 Gemfile.lock의 상태를 확인해보세요. 많은 경우가 이 두 가지 것으로 해결됩니다. 댓글 섹션에서 당신의 경험을 나누어주시면, 저와 다른 독자들도 함께 배울 수 있습니다.