GitHub Pages에서 Jekyll 블로그가 갑자기 빌드 실패? 내가 3일 밤을 새우며 발견한 해결법

대학을 은퇴하고 나서 지난 5년간 틈틈이 개발 블로그를 운영해오고 있습니다. 요즘 젊은 개발자들이 GitHub Pages와 Jekyll을 많이 사용한다고 해서, 호기심에 직접 시작해본 것이 벌써 5년이 되었네요. 그 과정에서 정말 많은 시행착오를 겪었는데, 그 중에서도 가장 답답했던 것이 바로 ‘갑자기 빌드가 실패한다’는 문제였습니다. 이번 포스팅에서는 제가 3일간의 밤샘 디버깅을 통해 터득한 GitHub Pages의 Jekyll 빌드 실패 원인과 해결 방법을 여러분과 공유하려고 합니다.

그날의 악몽, 빌드 실패의 시작

어느 날 아침, 평소처럼 새 포스트를 GitHub에 푸시하고 메일을 확인했는데, GitHub Pages에서 빌드 실패 알림이 와 있었습니다. 처음에는 대수롭지 않게 생각했어요. 문법 오류 정도겠지 하면서요. 하지만 로컬에서는 jekyll serve가 아무 문제 없이 실행되고 있었습니다. 이것이 시작이었습니다.

저는 즉시 GitHub의 빌드 로그를 확인하려고 했는데, 당시에는 빌드 로그가 제대로 표시되지 않아 정확한 오류 메시지를 파악할 수 없었습니다. 지금도 웃음이 나오지만, 그 당시의 저는 정말 답답했거든요. 손목을 놓고 한참을 고민했습니다.

원인 분석: 로컬과 원격 환경의 차이

결국 깨달은 것은 이거였습니다. 로컬 환경과 GitHub Pages 서버의 Ruby 버전, Gem 라이브러리 버전이 다르다는 점이었어요.

제 노트북에는 Ruby 3.0과 Jekyll 4.3.2가 설치되어 있었습니다. 하지만 GitHub Pages에서는 당시 Ruby 2.7과 Jekyll 3.9를 사용하고 있었던 것입니다. 또한 사용 중인 플러그인들 중 일부가 GitHub Pages의 화이트리스트에 포함되지 않은 것들이었습니다.

가장 큰 문제는 제 Gemfile에 버전을 명시하지 않았다는 점이었어요. 그래서 로컬에서는 최신 버전으로 설치되었지만, GitHub Pages에서는 호환되지 않는 조합으로 빌드되려고 했던 것입니다. 은퇴 후 개발을 새로 배우는 입장이라 이런 기초를 무시했던 거죠.

해결책: GitHub Pages 정확히 알기

제가 찾아낸 해결책은 정말 간단했습니다. 첫 번째는 Gemfile을 GitHub Pages와 정확히 일치시키는 것이었습니다.

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins

이 두 줄만 Gemfile에 추가하고 bundle update를 실행하면, GitHub Pages와 동일한 환경이 로컬에 구성됩니다. 그럼 로컬에서 빌드 실패가 발생하면 즉시 알 수 있고, 푸시 전에 모든 문제를 해결할 수 있게 되는 것이죠.

두 번째는 플러그인 사용 시 주의였습니다. GitHub Pages에서 지원하는 플러그인은 한정되어 있습니다. 저는 여러 멋진 플러그인들을 발견하고 사용하고 싶었지만, GitHub Pages에서 지원하지 않는 것들을 제외해야 했습니다. 만약 꼭 사용해야 한다면, GitHub Actions를 활용하여 CI/CD 파이프라인을 구축해야 합니다.

세 번째는 _config.yml 파일 검증이었습니다. 제가 겪은 또 다른 빌드 실패는 YAML 문법 오류였습니다. 따옴표를 빠뜨리거나, 들여쓰기가 잘못되면 파서가 읽지 못합니다. 이를 확인하려면 온라인 YAML 검증 도구를 사용하거나, VS Code에 YAML 확장을 설치하면 됩니다.

예방은 최고의 약

지금은 더 이상 빌드 실패를 겪지 않습니다. 왜냐하면 제가 습관을 바꿨기 때문입니다.

매번 새 포스트를 작성할 때마다 로컬에서 jekyll serve를 실행하고, 브라우저로 직접 확인합니다. 포스트 전에 bundle update를 주기적으로 실행하여 의존성을 최신으로 유지합니다. 그리고 가장 중요한 것은 깃허브 공식 문서를 정기적으로 확인하는 것입니다.

은퇴 후 개발을 배우면서 배운 교훈은 이겁니다. 문제 해결의 속도는 경험에서 나오지만, 문제 예방의 능력은 문서 읽기와 기초 이해에서 나온다는 것입니다. 저처럼 3일을 밤을 새울 필요는 없습니다. 처음부터 제대로 설정하고, 정기적으로 검증하면 됩니다.

**당신도 GitHub Pages로 블로그를 운영하고 계신가요?