GitHub Pages에서 Jekyll 빌드 실패? 이 한 가지만 확인하세요

은퇴 전 마지막 프로젝트로 만난 블로그 재앙

대학을 정년퇴직한 지도 몇 년이 지났지만, 여전히 손가락이 근질거리던 나는 지난해 GitHub Pages로 개인 블로그를 시작했다. 학생들을 가르쳤던 경험을 정리하고 공유하고 싶었기 때문이다. Jekyll과 Chirpy 테마로 멋진 블로그를 만들었다고 생각했는데, 첫 포스팅을 올리던 날 밤이 문제였다.

깃허브 액션이 빌드에 실패했다는 빨간 X 표시가 떴고, 에러 메시지는 영어로 가득했다. “Bundler can’t find some gems”라는 말이 반복되었다. 컴퓨터를 배운 지 30년이 넘은 나에게도 이건 골치 아팠다. 그래서 나는 깔끔하게 문제를 해결하는 과정을 기록했고, 지금 그 경험을 여러분과 나누려 한다.

Gemfile.lock이 범인이었다

사실 문제는 매우 간단했다. 내 로컬 환경에서는 잘 작동하던 것이 GitHub Pages 서버에서는 작동하지 않았던 이유는 Gemfile.lock 파일의 불일치 때문이었다.

내가 윈도우 10 노트북에서 Jekyll을 설치하고 로컬로 테스트했을 때는 완벽했다. 하지만 GitHub Pages의 우분투 서버 환경에서는 의존성 버전이 맞지 않아 빌드가 계속 실패했던 것이다. Gemfile에는 대략적인 버전만 적혀 있는데, Gemfile.lock에는 정확한 버전 정보가 기록된다. 내 로컬 환경과 깃허브 서버의 OS가 다르면서 gem 버전이 꼬인 것이다.

해결책은 놀랍도록 간단했다. GitHub 저장소의 Settings에서 Pages 섹션을 열고, 빌드 시스템을 확인했다. 그리고 GitHub Actions 워크플로우 파일을 다시 살펴봤다. Jekyll의 공식 Chirpy 테마를 사용하고 있었으므로, 저장소의 .github/workflows 폴더에 있는 yml 파일을 정확히 설정해야 했다.

가장 중요한 부분은 워크플로우에서 Ruby 버전과 Bundle 캐시 설정이었다. 나는 원래 Ruby 3.0.x 버전을 사용 중이었는데, GitHub Actions는 다른 버전을 기본값으로 사용하고 있었다. 명시적으로 ruby-version을 지정하고, Gemfile.lock을 강제로 재생성한 후 커밋했다.

로컬 환경과 서버 동기화하기

두 번째 배운 점은 로컬 환경과 GitHub Pages 서버를 완벽하게 동기화해야 한다는 것이었다. 내가 준비한 체크리스트는 다음과 같다.

먼저 로컬에서 bundle update를 실행하여 모든 gem을 최신 상태로 업데이트했다. 그 다음 bundle lock을 실행하여 Gemfile.lock을 정확히 생성했다. 이 파일은 반드시 깃허브에 커밋되어야 한다. 많은 초보자들이 이 파일을 .gitignore에 추가하는 실수를 하는데, Jekyll 블로그에서는 절대 그래서는 안 된다.

또한 .github/workflows/pages.yml 파일을 검토했다. Chirpy 테마를 사용하는 경우, 이 파일이 올바르게 설정되어 있는지 확인하는 것이 중요하다. 특히 ruby-version: '3.2'와 같은 부분이 명시적으로 기록되어 있는지 확인해야 한다.

마지막으로 내가 포함시킨 커스텀 플러그인들이 GitHub Pages에서 지원되는지 확인했다. GitHub Pages는 보안상의 이유로 모든 Jekyll 플러그인을 지원하지 않는다. 허용된 플러그인 목록을 확인하고, 필요하면 _config.yml의 플러그인 섹션을 수정했다.

이 경험이 주는 교훈

지금 생각해보니 이 문제는 매우 흔한 실수다. 많은 사람들이 로컬에서 완벽하게 작동하는 블로그를 만들었다고 생각하고, GitHub에 올린 후 빌드 실패로 좌절한다. 하지만 실제로는 간단한 설정 문제일 가능성이 높다.

은퇴 후에 배운 또 다른 중요한 점은 문제 해결의 순서였다. 에러 메시지를 천천히 읽고, 로그를 추적하고, 하나씩 확인하는 습관이 있으면 대부분의 문제는 30분 안에 풀린다. 처음부터 모든 것을 알아야 한다고 생각할 필요는 없다는 뜻이다.

지금 나는 GitHub Pages와 Jekyll로 운영하는 블로그를 매달 새 포스팅으로 채우고 있다. 빌드 실패는 이제 과거의 일이 되었다. 혹시 여러분도 같은 문제로 고민 중이라면, 오늘 바로 Gemfile.lock과 워크플로우 파일을 확인해보길 강력히 추천한다. 그리고 좋은 결과가 나왔다면, 댓글로 경험을 나눠주기를 바란다.