GitHub Pages에서 Jekyll 블로그가 갑자기 빌드 실패? 나는 이렇게 해결했다

서론: 은퇴 후 시작한 블로그 여정

저는 올해 67세인 은퇴한 컴퓨터과학 교수입니다. 30년간 대학에서 학생들을 가르치다가 은퇴한 후, 남은 인생을 의미 있게 보내기 위해 기술 블로그를 시작하기로 결심했습니다. GitHub Pages와 Jekyll을 선택한 이유는 간단했습니다. 무료이고, 마크다운으로 글을 쓸 수 있으며, 버전 관리가 가능하다는 점이 매력적이었거든요.

처음 3개월은 순조로웠습니다. Chirpy 테마를 적용하고, 몇 개의 포스트를 올렸고, GitHub에 커밋하면 자동으로 블로그가 업데이트되는 마법에 빠져 있었습니다. 그런데 어느 날 아침, 갑자기 모든 것이 무너졌습니다. GitHub Pages의 빌드가 실패했다는 이메일이 날아온 것입니다.

Jekyll 빌드 실패의 원인: 나의 실수들

당시 저는 매우 당황했습니다. 데이터베이스 마이그레이션부터 레거시 시스템 통합까지 무수한 기술 문제를 해결해온 교수였지만, 왜 이렇게 간단해 보이는 정적 사이트 생성기가 작동하지 않는지 이해할 수 없었습니다.

먼저 GitHub의 Actions 탭을 확인했습니다. 여기서 “Build with Jekyll” 워크플로우의 로그를 보니 정확한 오류 메시지가 있었습니다. 처음에는 그 메시지를 제대로 읽지 않았습니다. 교수 시절의 습관이 문제였어요. 학생들의 코드를 읽을 때처럼 꼼꼼하게 읽지 않았던 것입니다.

첫 번째 실수: YAML 프론트매터의 오류

제가 작성한 포스트의 프론트매터를 다시 확인해보니, 날짜 형식이 일관되지 않았습니다. 어떤 포스트는 2026-05-10, 어떤 것은 2026/05/10 형식이었습니다. Jekyll은 매우 까다로운 도구라는 것을 깨달았습니다. 한 글자의 오류도 전체 빌드를 멈출 수 있습니다.

두 번째 실수: Gemfile 의존성 충돌

로컬에서 테스트하기 위해 내 노트북에 Ruby를 설치했는데, GitHub Actions 환경과 내 로컬 환경의 Ruby 버전이 달랐습니다. 로컬에서는 잘 작동하지만 GitHub에서는 실패하는 현상이 반복되었습니다. 이는 매우 답답했습니다. 마치 학생이 제 컴퓨터에서는 작동하는데 교수실 컴퓨터에서는 작동하지 않는다고 할 때의 그 황당함이 었습니다.

세 번째 실수: 플러그인 호환성 문제

Chirpy 테마를 커스터마이징하려다가 추가 플러그인을 설치했는데, GitHub Pages의 안전 모드에서 허용되지 않는 플러그인이었습니다. GitHub Pages는 보안상의 이유로 특정 플러그인만 화이트리스트에 올려두고 있습니다.

해결 방법: 체계적인 접근

이 문제들을 해결하기 위해 저는 체계적인 방법을 택했습니다. 데이터베이스 최적화 작업을 할 때처럼 단계별로 접근했습니다.

Step 1: GitHub Actions 로그 상세 분석

먼저 GitHub repository의 Settings → Pages에서 빌드 프로세스를 확인했습니다. “Actions” 탭의 최근 워크플로우를 클릭하여 정확한 오류 메시지를 읽었습니다. 마크다운에서 특수문자가 제대로 이스케이프되지 않았다는 메시지를 발견했습니다.

Step 2: 로컬 환경 정리

로컬 개발 환경을 GitHub Pages와 일치시키기 위해 다음을 수행했습니다:

gem install bundler
bundle install
bundle exec jekyll serve

이렇게 하면 로컬에서도 GitHub와 동일한 환경에서 테스트할 수 있습니다. 매우 중요한 발견입니다!

Step 3: 프론트매터 검증

모든 포스트의 프론트매터를 표준화했습니다:

---
title: "제목"
date: 2026-05-11 09:00:00 +0900
categories: [카테고리]
tags: [태그1, 태그2]
---

Step 4: jekyll-compose 사용

이후로는 다음 명령어로 새 포스트를 생성합니다:

bundle exec jekyll post "포스트제목"

이 명령어가 올바른 형식의 파일을 자동으로 생성해줍니다.

당신이 배울 수 있는 교훈

저의 실패 경험에서 파생된 몇 가지 중요한 교훈이 있습니다:

첫째, 로컬 환경과 배포 환경을 일치시키는 것의 중요성입니다. 이는 제가 30년 전 학부 시절부터 배웠어야 하는 기본 원칙입니다.

둘째, 오류 메시지를 꼼꼼히 읽는 것의 중요성입니다. GitHub Actions의 로그는 매우 상