GitHub Pages가 갑자기 빌드 실패한다면? Jekyll 종속성 지옥에서 탈출하기

새벽 3시에 받은 GitHub Pages 빌드 실패 알림

은퇴한 지 5년째, 나는 여유로운 시간을 활용해 기술 블로그를 운영하고 있습니다. Jekyll과 GitHub Pages의 조합은 정말 훌륭했습니다. 별도의 서버 비용도 없고, 마크다운으로 편하게 글을 쓸 수 있었으니까요. 그런데 지난주 새벽 3시, 예상치 못한 악몽이 찾아왔습니다.

깃허브에서 “Your site failed to build”라는 알림이 왔던 것입니다. 분명 어제까지는 정상적으로 작동하던 블로그였는데요. 당황한 마음으로 GitHub Actions 로그를 확인해보니 의미 모를 에러 메시지들만 잔뜩 있었습니다. 바로 이 경험이 제 인생에서 가장 유익한 기술 학습의 시작이 되었습니다.

원인의 뿌리: Ruby 버전과 Gem 종속성의 불일치

처음에는 문제를 파악하는 데만 2시간이 걸렸습니다. GitHub Pages의 빌드 실패 원인은 대부분 세 가지입니다. 첫째, Ruby 버전의 변경, 둘째, Jekyll 플러그인의 호환성 문제, 셋째, Gemfile의 종속성 꼬임입니다.

제 경우는 세 가지가 모두 얽혀있었습니다. GitHub Pages가 사용하는 기본 Ruby 버전이 업데이트되었고, 그에 따라 설치된 Gem 라이브러리들이 충돌하기 시작한 것이었습니다. 특히 jekyll-sass-converter와 webrick 패키지가 문제였습니다.

현지적으로는 로컬 개발 환경에서 완벽하게 빌드되고 서빙되는데, GitHub Actions에서는 실패하는 신기한 현상도 발생했습니다. 이는 로컬 환경과 GitHub의 빌드 환경 버전 차이 때문이었습니다.

해결책: Gemfile 정리와 GitHub Actions 워크플로우 수정

첫 번째 해결 단계는 Gemfile을 철저히 점검하는 것이었습니다. 저는 github-pages gem을 명시적으로 지정하여 GitHub의 공식 버전과 동기화하기로 결정했습니다. Gemfile에 다음과 같이 작성합니다:

gem 'github-pages', '~> 231', group: :jekyll_plugins

이렇게 하면 GitHub Pages가 공식적으로 지원하는 Jekyll과 모든 관련 플러그인이 자동으로 호환되는 버전으로 설치됩니다.

두 번째는 .github/workflows/jekyll.yml 파일을 점검하는 것입니다. 저도 처음엔 이 파일의 중요성을 간과했는데, 여기서 Ruby 버전을 명시해야 합니다. 현재 GitHub Pages가 권장하는 Ruby 3.3.x 버전을 지정하는 것이 좋습니다.

세 번째 단계는 로컬 환경에서 bundle install과 bundle exec jekyll serve 명령으로 반드시 테스트하는 습관입니다. 이렇게 하면 배포 전에 문제를 미리 발견할 수 있습니다.

예방이 최고의 치료: 정기적인 의존성 업데이트 전략

이 문제를 해결한 후, 저는 같은 문제가 재발하지 않도록 예방 전략을 수립했습니다. 매월 첫째 주에 bundle update를 실행하고 로컬에서 테스트하는 루틴을 만들었습니다.

또한 .gitignore에 Gemfile.lock을 추적하도록 하여, 로컬과 GitHub의 환경 일관성을 유지합니다. 많은 사람들이 Gemfile.lock을 무시하곤 하는데, 이는 오류의 원인이 될 수 있습니다.

GitHub 저장소의 Dependabot 알림 기능도 활용하기 시작했습니다. 이 기능을 활성화하면 주요 보안 업데이트나 호환성 문제가 자동으로 감지되어 알림을 받을 수 있습니다.

5년간 기술 블로그를 운영하며 배운 것은 작은 실수가 어떻게 큰 문제로 번질 수 있는지, 그리고 체계적인 접근이 얼마나 중요한지입니다. Jekyll과 GitHub Pages는 여전히 개인 블로그의 최고의 선택이지만, 정기적인 관리 없이는 언제 터질지 모르는 시한폭탄이 될 수 있다는 것을 명심해야 합니다.

지금 당신의 블로그도 마찬가지 상황에 처해있다면, 오늘 바로 Gemfile을 점검하고 로컬 환경에서 테스트해보시기 바랍니다. 아직 문제가 없다면, 이 글의 예방 전략들을 미리 적용해두세요.