GitHub Pages에서 Jekyll 블로그가 갑자기 빌드 실패한 이유, 드디어 찾았습니다

30년 경력 교수도 당황했던 순간

작년 가을, 저는 대학에서의 퇴직을 앞두고 지난 30년간의 강의 노트와 연구 자료를 정리하기로 마음먹었습니다. 그동안 쌓아둔 기술 블로그를 만들어 후학들과 나누고 싶었던 것입니다. Jekyll과 GitHub Pages를 선택한 것은 깔끔한 마크다운 문법과 무료 호스팅이 매력적이었기 때문입니다.

처음 3개월은 순조로웠습니다. Chirpy 테마를 설치하고, 포스트를 작성하고, 깔끔한 블로그가 완성되었을 때의 희열은 지금도 생생합니다. 그런데 어느 날 갑자기 악몽이 시작되었습니다. 평소처럼 포스트를 커밋했는데, GitHub Pages의 빌드가 실패했다는 이메일을 받은 것입니다.

공식 가이드에도 나오지 않는 숨은 함정

처음에는 간단하다고 생각했습니다. “파일 이름 형식이 잘못되었겠지” 하는 생각으로 Jekyll 공식 문서를 다시 읽었습니다. 포스트 파일명은 YYYY-MM-DD-제목.md 형식이어야 한다고 명시되어 있었고, 저는 이미 그렇게 하고 있었습니다.

다음으로 의심한 것은 마크다운 문법입니다. 65세가 된 지금도 기술 학습에는 게으르지 않지만, 마크다운 문법까지 완벽하게 알지는 못했습니다. 혹시 잘못된 문법이 있나 싶어 여러 번 점검했지만, 문제는 없었습니다.

GitHub의 빌드 로그는 답답하게도 일반적인 에러 메시지만 보여주고 있었습니다: “Build failed”. 실제 원인이 무엇인지는 명확하지 않았습니다. 제 학생들에게 물어도 “GitHub 액션 로그를 확인해보세요”라는 답변만 돌아왔습니다.

결국 발견한 진짜 원인: Gemfile과 플러그인 버전 충돌

3주일간의 디버깅 끝에, 저는 매우 기초적인 실수를 범하고 있었음을 깨달았습니다. 문제는 다름 아닌 Gemfile에 있었습니다.

제 로컬 환경에서는 Jekyll 4.3.2 버전을 사용하고 있었는데, GitHub Pages에서는 특정 버전의 jekyll-github-metadata 플러그인이 필요했습니다. 더욱이 제가 설치한 몇몇 플러그인들이 서로 의존성 충돌을 일으키고 있었던 것입니다.

해결 방법은 생각보다 간단했습니다:

1. 로컬 환경에서 bundle install을 다시 실행하여 Gemfile.lock을 최신화했습니다.
2. GitHub Pages 공식 권장 버전의 플러그인들만 유지하도록 Gemfile을 정리했습니다.
3. 특히 중요한 것은 jekyll-github-metadata 플러그인이 반드시 포함되어 있어야 한다는 점입니다.

이 과정에서 저는 매우 귀한 교훈을 얻었습니다. 우리는 종종 복잡한 것만 찾으려 하지만, 대부분의 기술 문제는 기초적인 설정의 불일치에서 비롯된다는 것입니다.

실제 해결 과정과 예방 방법

제가 실제로 적용한 해결책을 구체적으로 공유하겠습니다.

먼저 저는 GitHub 저장소의 Actions 탭에 들어가 실패한 빌드의 상세 로그를 다시 확인했습니다. 이전에는 대충 넘어갔던 부분을 이번에는 줄 단위로 꼼꼼히 읽었습니다. 그 결과 bundle exec jekyll build 명령어에서 플러그인 로딩 실패 메시지를 발견할 수 있었습니다.

다음으로 제가 한 일은 로컬 환경을 GitHub Pages와 완전히 동일하게 맞추는 것이었습니다. Chirpy 테마의 공식 GitHub 저장소에서 원본 Gemfile을 다시 복사했고, 필요한 의존성만 추가했습니다.

특히 중요했던 설정은 다음과 같습니다:

• github-pages gem을 명시적으로 Gemfile에 포함시키기
• 로컬에서만 사용하는 플러그인은 development 그룹으로 분리하기
• 정기적으로 bundle update를 실행하여 의존성을 최신 상태로 유지하기

이 과정을 거친 후, 제 블로그는 다시 정상적으로 빌드되기 시작했습니다.

경험 많은 사람도 놓칠 수 있는 부분

이 경험을 통해 저는 한 가지 깨달음을 얻었습니다. 기술 경력이 길수록 때로는 기초를 간과하기 쉽다는 것입니다. 제가 30년간의 프로그래밍 경험이 있다고 해서 Jekyll의 기초적인 설정 원리를 100% 이해하고 있던 것은 아니었습니다.

특히 GitHub Pages 같은 클라우드 기반 서비스에서는 로컬 환경과