GitHub Pages에서 Jekyll 블로그가 자꾸 배포 안 될 때, 은퇴 교수가 찾아낸 해결책
20년 학술 블로그 운영 경험으로 알려주는 Jekyll 배포 오류 해결 실전 노하우
들어가며: 정년 후 블로그로 시작한 제 두 번째 인생
올해 67세, 30년을 컴퓨터과학과에서 강의한 저는 정년을 맞이했습니다. 그리고 그 해 11월, 제 경력을 정리하고 지식을 공유하고 싶다는 생각에 GitHub Pages로 개인 블로그를 시작했습니다. 처음엔 WordPress를 고려했지만, 한 제자가 추천한 Jekyll과 GitHub Pages의 조합이 너무 매력적이었거든요. 정말 훌륭한 선택이었지만, 그 여정이 항상 순탄했던 것만은 아닙니다.
지난 2년간 제 블로그를 운영하면서 마주친 가장 큰 문제는 “배포 실패”였습니다. 코드를 작성했고, 마크다운으로 글을 썼는데 자꾸만 GitHub Actions가 실패한다는 알림을 받았습니다. 그 당시엔 정말 답답했습니다. 하지만 지금은 이 문제들을 거의 모두 해결했고, 같은 고민을 하는 분들을 위해 이 경험담을 나누고 싶습니다.
Jekyll 배포가 실패하는 가장 흔한 세 가지 이유
1. 테마의 Gemfile과 Ruby 버전 불일치
처음 배포 실패의 원인은 굉장히 단순했습니다. 저는 Jekyll Chirpy 테마를 선택했는데, GitHub Actions에서 실행되는 Ruby 버전과 제 로컬 환경의 Ruby 버전이 달랐던 것입니다.
제 컴퓨터(Windows 10)에는 Ruby 3.1을 설치했고, Gemfile에 명시된 버전도 그랬습니다. 그런데 GitHub Actions는 우분투 환경에서 다른 버전의 Ruby를 사용하고 있었고, Chirpy 테마의 일부 의존성이 호환되지 않았던 것입니다.
해결책은 .github/workflows/pages-deploy.yml 파일에서 Ruby 버전을 명시적으로 지정하는 것이었습니다:
1
2
3
4
5
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 3.1
bundler-cache: true
그리고 Gemfile의 ruby 버전 명시도 중요합니다:
1
ruby '~> 3.1.0'
처음엔 이게 왜 중요한지 이해 못 했습니다. 30년간 학생들을 가르치면서 배운 것이 하나 있다면, “환경 설정의 일관성”이 얼마나 중요한지입니다. 프로그래밍도 결국 같은 원리입니다.
2. 번들 캐시 문제와 의존성 충돌
두 번째 문제는 더 교활했습니다. 배포 로그를 자세히 보니 특정 gem이 설치되지 않는다는 오류였습니다. 특히 webrick이라는 gem이 문제였는데, Ruby 3.0 이상부터는 기본 라이브러리에 포함되지 않기 때문입니다.
1
bundler: failed to load command: jekyll
이 오류를 해결하기 위해 Gemfile에 명시적으로 추가했습니다:
1
gem 'webrick', '~> 1.7'
그리고 GitHub Actions 워크플로우에서 bundler 캐시를 초기화하는 것도 도움이 됐습니다. 때로는 과거의 잘못된 의존성이 캐시에 남아있어서 문제가 되곤 합니다. 정년 후 머리를 정리하듯, 때로는 캐시도 정리가 필요한 법입니다.
3. 포스트 파일명과 프론트매터의 오류
세 번째 문제는 제 실수였습니다. Jekyll은 포스트 파일명이 YYYY-MM-DD-title.md 형식이어야 하는데, 저는 이 규칙을 자주 어겼습니다. 또한 프론트매터의 date 형식도 정확하지 않을 때가 있었습니다.
1
2
3
4
5
6
---
title: "제목"
date: 2026-05-16 09:00:00 +0900
categories: [도구]
tags: [태그]
---
이 부분에서 시간대(timezone) 표기를 빠뜨렸을 때 배포가 실패하기도 했습니다. 정확한 규격을 지키는 것이 얼마나 중요한지 깨달았습니다.
로컬 테스트로 99%의 배포 오류를 예방하기
이제 저는 어떤 포스트도 GitHub에 푸시하기 전에 반드시 로컬에서 테스트합니다. 이것이 가장 현명한 방법이라는 걸 배웠습니다.
1
bundle exec jekyll serve
이 명령어로 로컬 서버를 띄워서 http://localhost:4000에서 직접 확인합니다. 그러면 배포 환경과 동일한 상태에서 미리 문제를 발견할 수 있습니다. 마치 수업 전에 교안을 확인하던 습관처럼, 이제는 배포 전의 로컬 테스트가 제 루틴입니다.
특히 새로운 플러그인을 추가하거나 테마를 변경할 때는 더욱 신중합니다. 한 번은 댓글 기능을 추가하려다가 의도치 않게 전체 빌드를 깨뜨린 적도 있습니다. 그때부터는 변경사항을 한 번에