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

은퇴 후 시작한 블로그, 그 첫 번째 난관

대학을 정년퇴직한 지 어느덧 2년이 되었습니다. 40년간 정보통신학을 가르쳤던 저는 퇴직 후 한 가지 꿈을 품었는데, 바로 그간의 노하우와 경험을 온라인으로 공유하는 것이었습니다. 그래서 선택한 것이 Jekyll과 GitHub Pages였습니다. 무료이고, 깔끔하며, 기술적으로도 흥미로웠거든요.

처음 몇 주는 정말 즐거웠습니다. Chirpy 테마를 다운로드받고, 로컬에서 번들을 설치하고, 첫 번째 포스트를 작성했을 때의 그 희열은 지금도 생생합니다. 그런데 말입니다. GitHub에 push한 지 5분 후, 이메일이 하나 날아왔습니다.

“The page build failed.”

그 메시지를 받는 순간, 제 얼굴은 확 굳어져 버렸습니다.

빌드 실패, 그 미스터리한 에러 메시지

처음엔 원인을 찾기가 정말 어려웠습니다. GitHub에서 제공하는 에러 메시지는 너무 일반적이었거든요. “There was an error building your site.” 이것뿐이었습니다. 마치 의사가 환자에게 “당신은 아픕니다”라고만 하는 것 같은 답답함이었어요.

저는 처음에 Jekyll의 공식 문서를 읽었습니다. 그러다가 문제를 발견했습니다. 바로 Ruby 버전의 호환성 문제였습니다. 제 로컬 머신에는 Ruby 3.2가 설치되어 있었는데, GitHub Pages가 사용하는 Jekyll은 특정 버전의 gem에만 호환되었던 것입니다.

두 번째 문제는 플러그인이었습니다. 저는 흥미로워서 여러 플러그인을 _config.yml에 추가했는데, GitHub Pages가 공식적으로 지원하지 않는 플러그인들이 섞여 있었습니다. Jekyll은 로컬에서는 잘 작동하지만, GitHub Pages의 safe mode에서는 특정 플러그인만 실행되기 때문입니다.

세 번째는 인코딩 문제였습니다. 저는 한글로 된 마크다운 파일 이름을 사용했는데, 이것이 빌드 과정에서 문제를 야기했습니다. Windows 환경에서 작업했던 터라 더욱 그랬던 것 같습니다.

해결책을 찾아낸 경험담

이 문제들을 해결하는 데는 약 3주가 걸렸습니다. 제 해결 과정을 여러분과 공유하겠습니다.

먼저 가장 중요한 것은 GitHub Pages 설정을 확인하는 것입니다. 저는 저장소의 Settings > Pages로 가서, 어떤 브랜치를 사용하고 있는지, 빌드 소스가 무엇인지를 다시 확인했습니다. 현재 GitHub Pages는 GitHub Actions를 기본으로 사용하고 있으므로, 워크플로우 파일도 확인해야 합니다.

두 번째는 로컬 빌드 환경을 GitHub와 동일하게 맞추기였습니다. Gemfile을 열어서 github-pages gem을 추가했습니다.

gem "github-pages", group: :jekyll_plugins

그리고 bundle install을 실행했습니다. 이렇게 하면 로컬에서도 GitHub와 동일한 버전의 gem들이 설치됩니다.

세 번째는 _config.yml을 꼼꼼히 검토했습니다. Chirpy 테마에서 제공하는 기본 설정에서 제가 추가한 부분들을 하나하나 제거해가며 테스트했습니다. 그 결과, jekyll-spaceship 플러그인이 문제였다는 것을 발견했습니다. 이 플러그인은 GitHub Pages의 safe mode에서 지원하지 않았기 때문입니다.

네 번째는 파일 이름 규칙을 준수하는 것이었습니다. 포스트 파일은 반드시 YYYY-MM-DD-title.md 형식으로 작성해야 하며, 제목에 한글을 피하는 것이 좋습니다. 카테고리나 태그는 한글로 지정할 수 있지만, 파일 이름은 영문으로 해야 합니다.

다섯 번째는 GitHub Actions 워크플로우를 확인하는 것입니다. Chirpy 테마를 사용한다면, .github/workflows 디렉토리에 자동으로 생성되는 워크플로우 파일을 살펴봐야 합니다. 저는 이 파일에서 Jekyll 버전과 Ruby 버전을 명시적으로 지정했습니다.

마지막으로, 저는 로컬에서 bundle exec jekyll serve로 테스트한 후에만 GitHub에 push하기로 결정했습니다. 이렇게 하면 로컬에서 실제 빌드 환경과 동일한 조건에서 테스트할 수 있습니다.

교수 경력에서 배운 것들

40년간 학생들을 가르치면서 배운 것 중 하나가 있습니다. 그것은 “작은 것부터 차근차근 확인하라”는 것입니다. 복잡한 문제라도 결국은 작은