GitHub Pages에서 Jekyll 블로그가 갑자기 빌드 실패한 이유, 이제 알았습니다
은퇴 교수의 10년 블로깅 경험에서 배운 Jekyll 빌드 실패의 숨겨진 원인들과 해결책
정년을 맞이하고 취미로 시작한 Jekyll 블로그가 벌써 10년이 되었습니다. 대학에서 30년간 컴퓨터과학을 가르쳤지만, 정작 손으로 직접 기술을 구현해보는 것은 블로그를 시작하면서였습니다. 그 과정에서 GitHub Pages와 Jekyll로 얼마나 많은 시행착오를 겪었는지 모릅니다.
특히 어느 날 갑자기 블로그 배포가 실패했던 경험이 있는데, 그때의 좌절감과 그 후로 터득하게 된 해결책들을 여러분과 나누고 싶습니다. 제 경험이 혹시 모를 상황에서 여러분의 소중한 시간을 아껴드릴 수 있다면 얼마나 좋을까요.
GitHub Pages 빌드가 실패하는 가장 흔한 이유들
제 블로그가 처음 빌드 오류를 일으켰을 때는 정말 난감했습니다. 며칠 전까지 멀쩡하던 것이 갑자기 배포가 안 되니까요. GitHub에서 보낸 이메일에는 “Build failed”라고만 적혀 있었고, 구체적인 원인은 전혀 나와 있지 않았습니다.
처음 의심했던 것은 마크다운 파일의 문법 오류였습니다. 교수 시절 습관대로 포스트에 특수 기호를 많이 사용했거든요. 하지만 그것도 문제가 아니었습니다. 며칠을 헤맨 끝에 알게 된 것은 _config.yml 파일의 설정 오류였습니다.
제가 Chirpy 테마를 업데이트하면서 YAML 파일의 들여쓰기가 깨져버린 것이 원인이었습니다. YAML은 들여쓰기를 공백으로만 해야 하는데, 제 에디터가 탭을 섞어서 저장했던 것이죠. 이건 사람의 눈으로는 구분이 거의 불가능합니다. 그래서 저는 이후로 항상 YAML 린터(linter)를 온라인에서 확인하는 습관을 들였습니다.
또 다른 흔한 원인은 gemfile.lock 파일의 충돌입니다. 로컬 환경과 GitHub Actions의 Ruby 버전이 맞지 않으면서 의존성 문제가 생기는 경우가 있습니다. 저는 macOS, Windows, 심지어 Linux 환경에서까지 블로그를 관리해본 적이 있는데, 각각의 환경에서 나타나는 오류가 전부 달랐습니다. 한 번은 M1 맥에서 인텔 맥용 gem을 설치했다가 며칠을 낭비한 적도 있습니다.
Chirpy 테마의 버전 업데이트 함정
Jekyll을 처음 배울 때만 해도 블로그는 정적인 것이라고 생각했습니다. 파일을 올리면 그것으로 끝이라고요. 하지만 현실은 결코 그렇지 않았습니다. 특히 인기 있는 Chirpy 테마는 꽤 자주 업데이트되는데, 매번 업데이트할 때마다 새로운 문제가 생겼습니다.
한 가지 기억에 남는 사건은 Chirpy 버전 5.0으로 업그레이드했을 때입니다. 새로운 기능들이 정말 좋아서 바로 적용했는데, 제 포스트들의 날짜 형식이 모두 깨져버렸습니다. 이전 버전에서는 2026-05-16 형식을 허용했지만, 새 버전에서는 더 엄격한 ISO 8601 형식만 인정했던 것입니다. 150개가 넘는 포스트의 front matter를 모두 수정해야 했습니다.
그 경험 이후로 저는 주요 버전 업그레이드는 항상 테스트 브랜치에서 먼저 해본다는 원칙을 세웠습니다. GitHub의 무료 용량을 활용해서 test 브랜치를 만들고, 거기서 먼저 배포를 시켜본 후 문제가 없으면 main으로 병합하는 방식이죠. 이 방법으로 얼마나 많은 사고를 예방했는지 모릅니다.
또한 Chirpy의 공식 GitHub 저장소를 주기적으로 확인하면서 릴리스 노트(Release Notes)를 꼼꼼히 읽어봅니다. 특히 “Breaking Changes” 섹션은 절대 놓쳐서는 안 됩니다. 사소한 업데이트라고 생각했던 것이 나중에 큰 문제를 일으킬 수 있으니까요.
로컬 환경과 GitHub Actions의 동기화 문제
가장 답답했던 경험은 “로컬에서는 잘 되는데 GitHub Pages에서는 안 되는” 상황입니다. Jekyll을 설치해서 bundle exec jekyll serve 명령으로 로컬 서버를 띄우면 완벽하게 작동하는데, GitHub에 push하면 갑자기 빌드가 실패하곤 했습니다.
원인은 GitHub Actions의 실행 환경이었습니다. 제 로컬 머신에는 Ruby 3.1.2가 설치되어 있었지만, GitHub Actions의 기본 이미지에는 Ruby 3.0.0이 설치되어 있었습니다. 이 버전 차이가 일부 gem