GitHub Pages 배포 실패? Jekyll 빌드 에러를 30초 만에 해결하는 비법

Jekyll 블로그 운영 중 겪는 빌드 실패 문제를 실전 경험으로 풀어낸 해결책

Posted May 12, 2026

By prof park sungtae

6 min read

처음 만난 그 악명 높은 에러 메시지

지난 2024년 봄, 나는 대학 홈페이지와 개인 블로그를 GitHub Pages로 운영하기로 마음먹었습니다. 40년간의 교육 경험을 기록하고 싶었거든요. 그런데 처음 포스팅을 올린 지 5분도 채 되지 않아 이메일 알림이 떨어졌습니다.

“Your site is having problems building.”

세상에, 이게 뭐라는 말인가 싶었습니다. 컴퓨터 과학과에서 40년을 가르쳤지만, GitHub Pages의 자동 빌드 시스템은 처음 다루는 것이었습니다. 당시 나는 YAML 프론트매터가 뭔지도 제대로 몰랐고, Liquid 템플릿 문법이라니 하는 것도 생소했습니다.

그날부터 3주간의 ‘깃허브 페이지 전쟁’이 시작되었습니다. 제 경험담이 지금 블로그를 시작하는 분들에게 도움이 될 것 같아 이 글을 남깁니다.

가장 먼저 깨달은 것은 모든 포스트 파일의 최상단에 있어야 한다는 YAML 프론트매터가 얼마나 엄격한지입니다. 당시 나는 마크다운 파일을 이렇게 작성했습니다:

---
title: 나의 첫 블로그 포스트
date: 2024-05-12
categories: [기술]
---

문제는 date 형식이었습니다. Jekyll은 정확한 ISO 8601 형식을 요구합니다. 제 경우 시간과 타임존까지 명시해야 했습니다:

---
title: "나의 첫 블로그 포스트"
date: 2024-05-12 10:30:00 +0900
categories: [기술]
tags: [jekyll, github]
---

따옴표까지 신경써야 한다는 것도 나중에 알았습니다. 특히 제목에 콜론(:)이 들어가면 반드시 따옴표로 감싸야 합니다. 이것 때문에 한 두 시간을 허비했을 정도입니다.

또 다른 문제는 파일명입니다. Jekyll은 엄격하게 YYYY-MM-DD-제목.md 형식을 요구합니다. 저는 처음에 2024_05_12_나의첫블로그.md 같은 형식으로 저장했다가 포스트가 전혀 인식되지 않아 한참을 헤맸습니다.

정확한 형식은:

파일명의 날짜와 프론트매터의 날짜가 일치할 필요는 없지만, 파일명의 형식이 정확해야만 Jekyll이 포스트로 인식합니다.

가장 큰 실수는 로컬 PC에서 테스트하지 않았다는 점입니다. 저는 GitHub 웹 에디터에서 직접 파일을 만들고 커밋했습니다. 에러가 발생하면 GitHub 이메일을 통해 알게 되었는데, 이렇게 하면 시행착오가 엄청나게 늘어납니다.

나중에 로컬 머신에 Jekyll 개발 환경을 구축하니 모든 것이 달라졌습니다. 포스트를 작성하고 bundle exec jekyll serve 명령으로 localhost:4000에서 실시간으로 확인할 수 있었기 때문입니다.

제가 추천하는 방법은 이렇습니다:

Ruby 설치: Jekyll은 Ruby로 만들어졌으므로 먼저 Ruby가 필요합니다. Windows 사용자라면 RubyInstaller를 받으세요.
Gemfile 확인: 블로그 저장소에 Gemfile이 있는지 확인합니다. Chirpy 테마를 사용한다면 이미 준비되어 있을 것입니다.
의존성 설치: 터미널에서 bundle install을 실행합니다.
로컬 서버 실행: bundle exec jekyll serve로 로컬에서 실시간 프리뷰를 봅니다.

이 과정을 거치면, 포스트를 작성할 때마다 즉시 어디가 잘못되었는지 알 수 있습니다. 제 경우 이 방법으로 배포 실패율을 95%에서 5% 이하로 줄일 수 있었습니다.

한국에서는 많이 알려지지 않았지만, GitHub Pages는 자동으로 GitHub Actions를 통해 Jekyll을 빌드합니다. 저는 처음에 이것을 이해하지 못해서 수동으로 빌드하려고까지 했습니다.

현재는 이렇게 합니다:

이 신뢰할 수 있는

This post is licensed under CC BY 4.0 by the author.