GitHub Pages에서 Jekyll 블로그가 갑자기 빌드 실패하는 이유, 30년 개발자가 찾은 해답

갑작스러운 빌드 실패로 마주한 좌절감

제가 은퇴 후 취미로 기술 블로그를 시작한 지 어느덧 3년째입니다. 정년퇴직 후 한가로운 시간을 보내려다가 옛 개발자의 본능으로 다시 손에 들게 된 것이 바로 이 GitHub Pages와 Jekyll이었죠. 처음엔 Chirpy 테마를 적용해서 매주 기술 팁을 올리는 것이 얼마나 즐거웠는지 모릅니다.

그런데 어느 날 갑자기 일이 터졌습니다. 평소처럼 마크다운 파일을 작성하고 커밋했는데, GitHub Actions에서 “Build failed” 메시지가 떴던 겁니다. 젊은 시절 같았으면 몇 분 만에 해결했을 문제일 텐데, 한 30분을 헤맸거든요. 그 경험을 오늘 여러분과 나누고 싶습니다.

가장 흔한 범인: YAML 프론트매터의 날짜 형식 오류

처음 마주친 빌드 실패의 원인은 정말 황당했습니다. 바로 포스트의 YAML 프론트매터(Front Matter) 부분에서 날짜 형식이 잘못되었다는 것이었죠.

Jekyll은 매우 까다로운 문법 검사자입니다. 특히 포스트 파일의 맨 앞에 오는 YAML 설정 부분에선 더더욱 그렇습니다. 저는 처음에 다음과 같이 작성했었습니다:

---
title: "제 블로그 첫 포스트"
date: 2026-05-16 9:00:00 +0900
---

문제가 보이시나요? 9:00:00 부분입니다. Jekyll은 숫자 앞에 0을 붙여서 09:00:00으로 써야 한다고 요구합니다. 이것은 ISO 8601 표준 날짜 시간 형식을 따르기 때문인데, 저처럼 오십 몇 년 만에 코딩을 다시 시작한 사람에겐 이런 세부사항이 정말 함정처럼 느껴졌습니다.

Chirpy 테마를 사용할 때는 특히 이 부분이 중요합니다. GitHub Pages가 자동으로 생성하는 _site 폴더의 구조가 이 날짜 형식에 따라 결정되거든요. 날짜가 파싱되지 않으면 전체 사이트 구조가 깨져버립니다.

GitHub Actions 로그를 제대로 읽는 법

두 번째 배운 점은 에러 메시지를 제대로 읽는 것의 중요성입니다. 처음엔 GitHub 저장소의 “Actions” 탭에서 빨간 X 표시만 보고 좌절했는데, 사실 그 안에 매우 상세한 로그가 남아있었습니다.

저는 이렇게 확인했습니다:

1. 저장소의 “Actions” 탭 클릭
2. 실패한 워크플로우 선택
3. “Build with Jekyll” 작업 클릭
4. 로그 전체를 읽기

처음엔 그냥 “Build failed”라는 메시지만 봤는데, 로그 전체를 읽으니 실제로는 “Liquid Exception” 같은 구체적인 오류가 있었습니다. 예를 들어 제 경우엔:

Liquid Exception: Undefined variable: site.title in _layouts/post.html

이런 식의 메시지가 있었는데, 이것은 제가 _config.yml 파일에서 title 값을 제대로 설정하지 않았다는 뜻이었습니다. 젊은 시절 디버깅 경험이 있었기에 이 정도는 쉽게 해결할 수 있었지만, 아무튼 로그를 읽는 것이 얼마나 중요한지 깨달았습니다.

로컬 환경에서 테스트하는 것의 소중함

그 이후로 저는 더 이상 GitHub에 바로 푸시하지 않습니다. 항상 로컬 환경에서 먼저 빌드를 테스트합니다. 은퇴 전에 배웠던 “테스트 주도 개발”이 여기서 다시 빛을 발하네요.

로컬에서 Jekyll을 실행하려면:

bundle exec jekyll serve

이 명령어 하나면 됩니다. 그러면 localhost:4000에서 실시간으로 블로그를 미리 볼 수 있고, 만약 오류가 있다면 터미널에서 즉시 확인할 수 있습니다. 이렇게 하면 마크다운 문법, YAML 설정, CSS 문제 등을 모두 로컬에서 해결한 후 푸시할 수 있습니다.

처음엔 이 과정이 번거롭다고 생각했지만, 이제는 이것이 빌드 실패를 90% 이상 방지해주는 보험이라는 것을 알게 되었습니다. 특히 Chirpy 같은 복잡한 테마를 사용할 때는 더욱 그렇습니다.

의존성 버전 문제도 간과할 수 없다

또 다른 흔한 원인은 Gemfile.lock 파일의 버전 불일치입니다. GitHub Pages가 업데이트되면서 Jekyll이나 플러그인의 버전도 변할 수 있는데, 제 로컬 환경과 GitHub 서버의 버전이 다르면 빌드 결과가 달라질 수