GitHub Pages에서 Jekyll 블로그가 갑자기 빌드 실패한다면? 은퇴 교수의 3년 삽질 경험담

은퇴 후 시작한 블로그 여정

대학을 정년퇴임한 지 3년째, 저는 인생 2막을 기술 블로그로 채우고 싶었습니다. 평생 연구 결과와 지식을 정리하고 공유하고 싶었던 것이죠. GitHub Pages와 Jekyll을 추천받고 설레는 마음으로 시작했습니다. 처음 몇 개월은 정말 순탄했습니다. Chirpy 테마를 적용하고 포스팅을 올렸고, 모든 것이 예상대로 작동했습니다.

하지만 약 8개월이 지났을 때 문제가 터졌습니다. 평소처럼 마크다운 파일을 작성해서 GitHub에 push했는데, 빌드가 실패했다는 이메일이 왔습니다. 그 순간의 당황스러움, 혼란스러움은 지금도 생생합니다. 처음으로 마주한 이 문제를 해결하기 위해 저는 3년간 수많은 시행착오를 겪게 되었습니다.

번번이 실패하는 빌드 - 원인을 찾기까지

처음 빌드 실패는 매우 신비로웠습니다. GitHub에서 제공하는 에러 메시지는 너무나 간단했습니다. “Build failed”라는 문구만 있었고, 구체적인 원인은 나와 있지 않았습니다. 저는 마치 어두운 방에서 불을 찾으려는 것처럼 이곳저곳을 헤매야 했습니다.

제일 먼저 깨달은 것은 로컬 환경에서 먼저 테스트하는 것의 중요성이었습니다. GitHub의 온라인 빌드 환경과 제 로컬 환경이 미묘하게 달랐던 것입니다. 저는 Windows 머신을 사용하고 있었는데, Ruby와 Jekyll의 의존성 문제가 있었습니다. 처음에는 Ruby를 설치했다고 생각했지만, 정확한 버전 관리가 부족했습니다.

교수 시절 연구 논문을 다루던 것처럼, 저는 체계적으로 접근하기로 결심했습니다. 로컬에서 bundle exec jekyll serve 명령어를 실행해서 먼저 빌드 에러를 확인하기 시작했습니다. 이제야 구체적인 에러 메시지가 보였습니다. Gemfile의 의존성 문제, 플러그인 호환성 문제, 그리고 Chirpy 테마 특화 설정 문제들이 차례로 드러났습니다.

가장 골치 아팠던 것은 gem 버전 충돌이었습니다. GitHub Pages가 사용하는 jekyll, jekyll-paginate-v2, rouge 등의 버전과 제 로컬 환경의 버전이 달랐습니다. 나이가 들어도 배울 것이 많다는 것을 다시 깨달았습니다.

Chirpy 테마의 특수한 요구사항 - 모른다는 것의 위험성

그 다음 난관은 Chirpy 테마 자체의 복잡성이었습니다. 단순히 Jekyll을 설치하고 테마를 입혀서 끝나는 것이 아니었습니다. Chirpy는 빌드 프로세스에서 추가적인 단계를 요구합니다.

처음에 저는 Chirpy의 공식 문서를 대충 읽고 넘어갔습니다. 젊을 때처럼 빠르게 행동하려던 습관 때문이었습니다. 하지만 은퇴한 나이에 이 실수는 큰 대가를 요구했습니다. Chirpy는 sass 파일들을 컴파일해야 하고, assets를 특정 방식으로 처리해야 하며, 특정 플러그인들이 필수적이라는 것을 나중에야 알았습니다.

가장 자주 마주했던 에러 중 하나는 Liquid Exception 에러였습니다. 포스팅에 특수 문자나 중괄호를 잘못 사용하면 템플릿 엔진이 혼란스러워했습니다. 저는 수십 개의 포스트를 다시 검토해야 했습니다. 한글 키워드 안에 특정 기호가 있으면 문제가 되기도 했습니다.

또 다른 문제는 플러그인이었습니다. GitHub Pages는 안전상의 이유로 특정 플러그인만 허용합니다. Chirpy가 사용하는 모든 플러그인이 허용된 목록에 있는지 확인해야 했습니다. 저는 결국 GitHub의 공식 문서에 있는 ‘Whitelisted plugins’ 목록을 외우다시피 했습니다.

문제 해결의 체계적 접근 - 노 교수의 방식

이런 시행착오를 겪으면서 저는 체계적인 디버깅 방법을 개발하게 되었습니다. 이것이 제 인생의 가장 큰 배움이었습니다.

첫 번째 단계: 로컬 환경을 GitHub Pages와 완벽하게 동기화하기. .ruby-version 파일을 만들고, Gemfile을 정확하게 관리하기. bundle update를 정기적으로 실행하기.

두 번째 단계: 포스팅 전에 반드시 로컬 서버에서 확인하기. bundle exec jekyll serve로 http://127.0.0.1:4000에서 실시간으로 확인하는 습관을 들이기.

**