GitHub Pages에서 Jekyll 블로그가 갑자기 안 보인다? 빌드 실패의 진짜 원인을 찾아라

정년 후 취미로 시작한 블로깅이 벌써 3년째다. 대학에서 40년간 전산학을 가르쳤지만, Jekyll과 GitHub Pages는 확실히 다르더라. 젊은 시절의 나는 이런 정적 사이트 생성기가 없어서 직접 HTML을 손으로 작성했으니까. 어제도 새로운 글을 올렸는데 GitHub Pages에 아무것도 안 보였다. 그 황당함이란… 이 글에서 내 경험을 바탕으로 해결책을 공개한다.

GitHub Actions 탭에서 빌드 로그를 확인하는 게 첫 번째 원칙

대부분의 사람들은 자신의 블로그가 안 보이면 당황해서 처음 할 일이 뭘까? 보통 레포지토리를 다시 고쳐보거나, 파일을 다시 올려본다. 하지만 내 경험상 정답은 다르다. 바로 GitHub Actions 탭을 열어보는 것이다.

레포지토리 페이지에서 “Actions” 탭을 클릭하면, Jekyll이 빌드를 시도한 히스토리가 보인다. 빨간 X 표시가 있다면? 그건 빌드 실패 신호다. 그 로그를 클릭해서 상세 내용을 보면, 보통 다음 같은 메시지들이 나온다:

“The jekyll-feed plugin is disabled” 또는 “Gem not found” 같은 메시지들이다. 내가 처음 겪은 문제도 바로 이거였다. 새로 추가한 플러그인이 Gemfile에는 없었던 것이다. 젊은 개발자들은 이런 기본을 아는데, 손이 굳은 내 같은 사람은 그냥 “왜 안 되지?” 하고 한참을 헤맸다.

_config.yml 파일의 문법 오류가 범인이 될 수 있다

두 번째로 자주 만나는 문제는 YAML 파일의 문법 오류다. Jekyll의 설정 파일인 _config.yml은 들여쓰기와 콜론 뒤의 공백이 정확해야 한다.

내가 겪은 사건을 예시로 들자면, 어느 날 블로그 제목을 수정하면서 이렇게 적었다:

title: "나의 블로그: 정년 후의 새로운 시작"

보기에는 별 문제 없지만, YAML 문법상 콜론이 있으면 값 부분을 따옴표로 감싸야 한다. 내 경우엔 이미 감싸져 있었지만, 다른 항목에서 실수가 있었다. 예를 들어:

description: 지난 40년 동안의 교수생활 경험을 나눕니다

여기서 “경험을 나눕니다” 부분에 특수문자가 있거나, 들여쓰기가 한 칸 잘못되면 Jekyll은 바로 울음을 그만춘다.

해결책은 간단하다. YAML 온라인 검증 도구(YAML Validator)에 _config.yml 내용을 붙여넣어보는 것이다. 5초 만에 오류를 찾을 수 있다. 이 방법으로 내 문제의 70%를 해결했다.

Gemfile과 플러그인 버전 호환성 문제

세 번째 문제는 좀 더 심각했다. Chirpy 테마를 최신 버전으로 업그레이드한 후, 갑자기 빌드가 실패했던 것이다.

GitHub Actions의 로그를 보니 “jekyll-archives” 플러그인 버전이 맞지 않는다는 메시지였다. 아, 이건 정말 골치 아픈 문제다. 왜냐하면 로컬에서는 잘 작동하는데, GitHub Pages 서버의 Ruby 버전과 충돌하는 경우가 있기 때문이다.

내 경우, 다음과 같이 해결했다:

1) GitHub Pages가 지원하는 공식 플러그인 목록을 확인했다. (GitHub Pages 공식 문서 참고) 2) Gemfile의 버전 제약 기호를 재검토했다. 예를 들어 ~> 1.0은 “1.0 이상 2.0 미만”을 의미한다. 3) 로컬에서 bundle update를 실행해 Gemfile.lock을 갱신했다. 4) 그 결과물을 GitHub에 푸시했다.

40년 교수생활에서 배운 한 가지는 ‘문제를 정확히 진단하는 것’의 중요성이다. 즉각적인 해결보다는 원인 파악이 우선이라는 뜻이다. GitHub의 로그 메시지들은 사실 매우 친절하다. 다만 영어로 되어 있고, 처음 봤을 때는 해석이 어렵기만 하다.

마지막 팁: 로컬 테스트를 먼저 하자

지금은 블로그를 올리기 전에 항상 로컬에서 bundle exec jekyll serve 명령어로 테스트한다. 로컬에서 성공했다면, GitHub에서도 99% 성공한다. 아직도 1%의 환경 차이가 있을 수 있지만, 최소한 YAML 오류나 플러그인 문제는 미리 찾을 수 있다.

지난 3년간 블로깅하면서 배운 게 많다. 젊은 개발자들이 당연하게 여기는 것들이 나에게는 새롭고 신기했다. 하지만 그만큼 해결할 때의 쾌감도 크다. 정년 후 이런 작은 문제들을 해결하는 과정 자체가 내게는 큰 공부가 되었다.

혹시 당신도 GitHub Pages 블로그에서 비슷한 문제를 겪고 있다면, 위의 방법들을 차례대로 시도해보기 바란다. 특히 Actions 탭의 빌드 로그는 정말로 모든 답을 담고 있다. 그리고 혹시 이 글로 문제를 해결했다면, 아래 댓글로 어떤 원인이었는지 공유해줄 수 있을까? 당신의 경험담이 다른 블로거들을 도울 수 있으니까.