GitHub Pages 배포 실패? Jekyll 빌드 에러를 5분 안에 해결하는 법

서문: 잔뜩 고장난 블로그를 보며 느낀 답답함

저는 지난 3년간 GitHub Pages와 Jekyll로 기술 블로그를 운영해왔습니다. 정년을 맞고 여유로워진 시간에 그동안 쌓인 개발 경험을 정리하고 싶었거든요. 처음 며칠은 즐거웠습니다. 하지만 얼마 지나지 않아 악몽이 시작되었습니다. 매번 새 포스트를 올릴 때마다 GitHub Actions에서 빨간 X 표시가 나타났고, 로컬에서는 멀쩡한데 배포되면 스타일이 깨져 보였습니다.

그 답답함을 겪으며 깨달은 것들을 오늘 공유하려고 합니다. 제가 겪은 대부분의 문제들은 불과 5분 안에 해결할 수 있는 것들이었습니다.

GitHub Actions 실패 로그를 제대로 읽는 법

가장 첫 번째로 배워야 할 것은 “어디서 문제가 났는지 정확히 파악하기”입니다. 저도 처음에는 Actions 탭에서 붉은 X만 보고 당황했습니다. 그러나 로그를 자세히 읽으면 대부분의 경우 원인이 명확하게 드러납니다.

GitHub 저장소의 Actions 탭을 열고, 실패한 워크플로우를 클릭하세요. 그 안에 “Jekyll build” 같은 항목이 있을 것입니다. 여기서 “Run jekyll build” 섹션을 펼쳐보면, 에러 메시지가 구체적으로 나타납니다. 예를 들어 “Liquid Exception”은 마크다운 파일 내 템플릿 문법 오류를 뜻합니다.

저는 처음 3개월간 이 로그를 제대로 읽지 못했습니다. 그냥 “오류 발생”이라는 메시지만 보고 다시 시도하곤 했거든요. 하지만 한 번 정확한 에러 메시지를 읽고 나니, 문제 해결 속도가 10배 이상 빨라졌습니다. 로그에는 정확히 어느 파일의 몇 번째 줄에서 문제가 났는지까지 표시되어 있습니다.

Gemfile 버전 관리: 로컬과 배포 환경의 차이 줄이기

두 번째 문제는 로컬 환경과 GitHub Pages 환경의 불일치입니다. 저는 Mac에서 블로그를 작성하고 테스트한 후 푸시했는데, 배포되면 갑자기 스타일이 깨지거나 플러그인이 작동하지 않는 경험을 여러 번 했습니다.

원인은 Gemfile.lock이었습니다. GitHub Pages의 빌드 환경과 제 로컬 Ruby 버전이 달랐던 것입니다. 저는 Ruby 3.2를 사용했지만, GitHub Pages는 특정 버전의 dependencies를 요구했습니다.

해결책은 간단합니다. Chirpy 테마를 사용 중이라면, 공식 Gemfile을 그대로 사용하고, 필요한 gem은 최소한으로 유지하세요. 저는 다음과 같이 정리했습니다:

source "https://rubygems.org"

gem "jekyll-theme-chirpy", "~> 6.1"
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw]
gem "tzinfo"

이후 터미널에서 bundle install을 실행하고, Gemfile.lock을 깃에 커밋했습니다. 이것만으로도 배포 에러의 80%가 사라졌습니다.

Front Matter와 파일명: 작은 실수가 초래하는 큰 문제

세 번째는 마크다운 파일의 front matter(YAML 헤더)와 파일명 관련 오류입니다. Jekyll은 특정한 포맷을 엄격하게 요구합니다.

저는 처음에 이런 실수들을 했습니다:

• 파일명에 공백 포함: “2026-06-03 my post.md” (안 됨, 하이픈으로 연결해야 함)
• Front matter의 날짜 형식 오류: “2026-06-03” (시간 없음. 시간:분:초 필수)
• categories와 tags가 배열이 아님: tags: [GitHub, Jekyll] ✓ 이 형태여야 함

저는 이런 작은 실수 때문에 하루를 낭비한 적이 여러 번 있습니다. 특히 복잡한 마크다운을 작성한 후 “왜 안 되지?” 하며 고민했는데, 알고 보니 파일명이 “my-post.md”가 아니라 “my post.md”였던 것입니다.

해결책은 체크리스트를 만드는 것입니다. 매 포스트마다 다음을 확인하세요: 파일명이 YYYY-MM-DD-slug.md 형식인가? front matter의 date는 정확한가? categories와 tags는 배열 형식인가?

마치며: 블로그는 마라톤

3년간 이 과정을 거치며 깨달은 것은, 기술 블로그 운영은 마라톤이라는 점입니다. 처음 몇 주는 환경 설정과 오류 처리로 힘들 수 있습니다. 하지만 올바른 구조를 한 번 만들어놓으면, 이후로는 포스트 작성에만 집중할 수 있습니다.

혹시 현재 Jekyll 블로그 배포 오류로 고민 중이라면, 위의 세 가지를 차례대로 확인해보세요. 놀랍게도 대부분의 경우 5분 안에 해결될 것입니다. 그리고 해당 오류를 겪으셨다면, 이 글의 댓글 섹션에 어떤 에러였는지 공유해주시면 좋겠습니다. 더 많은 분들이 같은 실수를 피할 수 있도록 말입니다.