GitHub Pages에서 Jekyll 블로그가 자꾸 빌드 실패하는 이유, 20년 경력 교수가 찾아낸 답

은퇴 후 블로그를 시작하며 마주친 문제

2024년 봄, 30년간 대학에서 가르친 후 은퇴하면서 나는 마지막 인생의 챕터를 기록하고 싶은 욕망에 빠졌습니다. GitHub Pages와 Jekyll Chirpy 테마를 선택한 것도 “코딩도 다시 배우고, 무료로 블로그를 운영할 수 있겠지”라는 단순한 생각에서였죠. 하지만 현실은 녹록지 않았습니다.

첫 포스트를 작성하고 GitHub에 push한 후, 나는 초조하게 메일을 기다렸습니다. “Build succeeded” 메시지 대신 들어온 것은 “Build failed” 알림이었습니다. 이것이 제 Jekyll 수난기의 시작이었습니다.

처음에는 단순한 실수라고 생각했습니다. 그러나 20번, 30번의 시도 끝에도 빌드는 계속 실패했습니다. 젊은 시절 프로그래밍을 배웠던 경험이 얼마나 도움이 되는지 깨닫게 되었고, 결국 이 문제를 해결하기 위해 GitHub 문서를 밤새 읽게 되었습니다. 오늘은 제가 발견한 가장 흔한 빌드 실패 원인들과 그 해결책을 여러분과 나누고 싶습니다.

YAML 프론트매터의 날짜 형식 문제

가장 먼저 저를 괴롭혔던 것은 YAML 프론트매터의 날짜 형식이었습니다. 첫 블로그 글을 쓸 때, 저는 아무 생각 없이 다음과 같이 입력했습니다:

date: 2026-05-17 9:00:00 +0900

이것이 빌드 실패의 원인이었습니다. GitHub Pages가 사용하는 Jekyll은 ISO 8601 형식을 엄격하게 요구합니다. 시간과 분, 초를 모두 두 자리로 표현해야 한다는 뜻입니다:

date: 2026-05-17 09:00:00 +0900

작은 것 같지만 이것이 차이를 만듭니다. 대학에서 데이터 포맷의 중요성을 몇십 년간 강조해왔던 저인데, 정작 자신의 블로그에서 같은 실수를 했다니요. 그 순간 웃음이 나왔습니다.

또한 날짜 형식 외에도 제목에 따옴표를 제대로 처리하지 않으면 YAML 파싱 오류가 발생합니다. 제목에 콜론(:)이 들어가면 반드시 따옴표로 감싸야 하는데, 이를 놓치면:

title: 내 블로그: 시작하기  # 오류 발생!
title: "내 블로그: 시작하기"  # 정상 작동

저는 이 규칙을 배우기까지 3일을 낭비했습니다.

한글 파일명과 URL 슬러그의 불일치

다음 문제는 파일명과 관련된 것이었습니다. 저는 제 포스트 파일을 2026-05-17-깃허브페이지스-완벽가이드.md라고 명명했습니다. 한글 파일명이 시스템에서 자동으로 인코딩되면서 URL이 복잡해졌고, 실제 빌드 과정에서 문제가 발생했습니다.

GitHub Pages와 Jekyll은 기본적으로 영문 파일명을 기준으로 설계되었습니다. 제 경험에 따르면, 파일명은 반드시 영문으로 작성하되 다음과 같은 형식을 따르는 것이 최선입니다:

YYYY-MM-DD-post-title-in-english.md

예: 2026-05-17-github-pages-complete-guide.md

한글은 프론트매터의 title 필드에만 사용하는 것이 좋습니다. 이렇게 하면 URL은 깔끔하게 유지되면서도 포스트 제목은 한글로 표시됩니다. 또한 YAML의 permalink 필드를 직접 지정하여 URL 구조를 완전히 제어할 수도 있습니다:

permalink: /posts/깃허브-완벽가이드/

하지만 이 경우에도 한글이 URL 인코딩되므로, 가독성 면에서는 영문 슬러그를 추천합니다.

Gemfile 버전 호환성과 로컬 테스트의 중요성

세 번째 문제는 더 근본적인 것이었습니다. GitHub Pages가 지원하는 Jekyll 버전과 제 로컬 환경의 버전이 맞지 않았던 것입니다.

은퇴 후 이제 시간이 넉넉했기에 저는 로컬에서 Jekyll을 구축하기로 결정했습니다. bundle install을 실행하고 bundle exec jekyll serve로 로컬 서버를 띄웠을 때, 처음에는 로컬에서 문제가 없었습니다. 하지만 GitHub에 push하면 빌드가 실패했습니다.

원인은 GitHub Pages가 지원하는 특정 버전의 gem들과 제 환경의 버전이 다르기 때문이었습니다. GitHub Pages는 공식적으로 지원하는 gem 목록이 있습니다:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins

이 한 줄이 핵심입니다. 이 gem을 사용하면 GitHub Pages가 공식 지원하는 모든 플러그인과 라이브러리가 정확한 버전으로 설치됩니다. 저는 처음에 각 gem을 개별적으로 설치하려다가 버전 충돌로 고생했습니다.

또한 로컬 테스트의 중요성을 강조하고 싶습니다. 변경사항을 GitHub에 push하기 전에 반드시 로컬에서 bundle exec jekyll build 명령으로 빌드 검증을 해야 합니다. 저는 매번 이 한 단계를 거치면서 빌드 오류를 사전에 잡을 수 있었습니다.

플러그인 호환성 문제

네 번째 문제는 Jekyll 플러그인들이었습니다. Chirpy 테마를 설치한 후 추가 플러그인을 몇 개 더하려다가 다시 빌드가 실패했습니다.

GitHub Pages는 보안상의 이유로 특정 플러그인만 공식 지원합니다. 제가 시도했던 플러그인 중 일부는 GitHub Pages에서 작동하지 않았습니다. 로컬에서는 잘 작동하지만 GitHub에서 실패하는 현상이 발생한 것입니다.

해결책은 _config.yml에서 플러그인 선택을 신중하게 하는 것입니다:

plugins:
  - jekyll-feed
  - jekyll-paginate-v2
  - jekyll-redirect-from

이런 플러그인들은 GitHub Pages에 공식 포함되어 있으므로 안전합니다. 추가 플러그인이 필요하다면 GitHub의 공식 문서에서 지원 목록을 확인해야 합니다.

캐시와 깃 문제

다섯 번째로 겪었던 문제는 약간 신비로웠습니다. 제 변경사항이 GitHub에 제대로 push되었음에도 불구하고, 몇 분 후 빌드가 실패했습니다. 확인해보니 제가 수정한 파일이 실제로는 push되지 않았던 것입니다.

이는 git 캐시 문제였습니다. 파일을 생성한 후 .gitignore를 추가하면, 이전 캐시로 인해 간헐적인 문제가 발생할 수 있습니다:

git rm --cached <파일명>
git add <파일명>
git commit -m "Update cache"

또한 _site 폴더는 절대 git에 포함되어서는 안 됩니다. .gitignore에 반드시 다음을 추가합니다:

_site/
.jekyll-cache/
.bundle/
vendor/

빌드 시스템은 자동으로 이 폴더들을 생성하므로 버전 관리에 포함할 필요가 없습니다.

결국 배운 것

은퇴 후 3개월간의 블로그 투쟁 끝에, 저는 다음을 깨달았습니다:

1. 정확성이 중요하다: 코딩의 세계에서 작은 오타 하나가 모든 것을 망칠 수 있습니다
2. 표준을 따라야 한다: 날짜 형식, 파일 구조 같은 표준은 이유가 있어서 존재합니다
3. 로컬 테스트가 필수다: push 전에 항상 검증하는 습관이 얼마나 소중한지 알았습니다
4. 문서를 읽어야 한다: GitHub의 공식 문서와 Jekyll 문서는 거짓말을 하지 않습니다

지금 제 블로그는 완벽하게 작동하고 있으며, 매주 새로운 글을 올리고 있습니다. 여러분이 제 경험에서 조금이라도 배울 수 있기를 바랍니다.

혹시 당신도 Jekyll 빌드 문제로 고민하고 있다면, 이 글의 체크리스트를 하나씩 따라가보세요. 그리고 해결되지 않는다면 GitHub Actions 탭에서 상세한 빌드 로그를 확인하는 것을 잊지 마세요. 제게는 이 로그가 진짜 영웅이었습니다. 당신의 첫 번째 성공적인 빌드를 위해 지금 바로 로컬 환경을 점검해보는 것은 어떨까요?