GitHub Pages에서 Jekyll 빌드가 자꾸 실패하는 이유, 드디어 알았습니다

서론: 과거의 답답했던 경험

퇴직 후 블로깅을 시작하면서 Jekyll과 GitHub Pages를 만났습니다. 처음에는 얼마나 멋진 조합인가 싶었는데, 며칠 뒤부터 악몽이 시작되었습니다. 커밋을 푸시할 때마다 GitHub에서 보내는 “Your site failed to build” 이메일이 날아왔거든요. 당시 저는 마치 컴퓨터와 싸우는 기분이었습니다. 하지만 몇 달의 시행착오 끝에 그 원인들을 찾아냈고, 이제는 거의 빌드 실패가 없습니다. 오늘은 제 경험담을 바탕으로 가장 흔한 Jekyll 빌드 실패 원인 세 가지를 공유하겠습니다.

루비 버전 불일치: 보이지 않는 함정

제가 가장 먼저 마주친 문제는 로컬 개발 환경과 GitHub Pages 서버의 루비 버전이 달랐다는 것입니다. 저는 Windows 컴퓨터에 최신 루비 3.2 버전을 설치했는데, GitHub Pages의 기본 설정은 루비 2.7을 사용하고 있었습니다. 로컬에서는 멀쩡히 빌드되던 프로젝트가 GitHub에만 가면 실패했던 이유가 바로 여기였습니다.

해결책은 간단합니다. 프로젝트 루트에 .ruby-version 파일을 생성하고 3.1.4 또는 3.2.0 같은 버전 명시를 해주면 됩니다. 또한 Gemfile에 ruby "~> 3.1.0" 같은 루비 버전 지정을 추가하는 것이 좋습니다. 저는 이 작은 설정 변경만으로도 빌드 성공률이 대폭 올랐습니다.

YAML 프론트매터의 섬세한 문법 오류

블로그 포스트 맨 앞의 YAML 프론트매터 부분도 골칫거리였습니다. 특히 제목이나 설명에 쌍따옴표나 특수문자가 있을 때 문제가 생겼습니다. 예를 들어 제목을 title: "Jekyll로 만든 '블로그' 가이드"라고 쓰면 따옴표 처리 때문에 파싱 오류가 발생합니다.

이를 해결하려면 특수문자가 포함된 텍스트는 반드시 따옴표로 감싸되, 내부 따옴표는 역슬래시로 이스케이프 처리해야 합니다. 또는 더 간단하게 YAML의 파이프 문법을 사용해서 description: |로 시작하고 여러 줄의 텍스트를 작성하는 방법도 있습니다. 저는 이 문법을 배운 뒤로 프론트매터 관련 오류는 거의 사라졌습니다.

플러그인 호환성 문제: 숨겨진 제약사항

가장 은폐하기 쉬운 문제가 Jekyll 플러그인의 호환성입니다. GitHub Pages는 보안상의 이유로 특정 공식 플러그인만 지원합니다. 저는 처음에 jekyll-admin 같은 멋진 플러그인들을 마구 설치했는데, 로컬에서는 잘 작동해도 GitHub Pages에는 반영되지 않았습니다.

GitHub Pages 공식 문서에서 지원하는 플러그인 목록을 확인하고, 그 목록에 있는 것들만 사용해야 합니다. 저 같은 경우에는 jekyll-sitemap, jekyll-feed, jekyll-seo-tag 같은 기본 플러그인들로도 충분하다는 걸 깨달았습니다. 혹시 다른 플러그인이 꼭 필요하다면, GitHub Actions를 사용해서 커스텀 빌드 과정을 설정하는 방법도 있습니다.

결론: 체계적인 접근의 중요성

퇴직 후 블로깅을 시작하면서 배운 가장 큰 교훈은 기술 문제의 대부분은 문서에 답이 있다는 것입니다. 저는 처음 몇 달간 무작정 구글을 뒤지며 헤맸지만, 공식 문서를 차근차근 읽으면서 상황이 나아졌습니다. 루비 버전 관리, YAML 문법 검증, 플러그인 호환성 확인이라는 세 가지만 신경 써도 Jekyll 빌드 성공률은 99%에 가까워집니다.

혹시 지금 여러분도 GitHub Pages 빌드 실패로 고민하고 계신가요? 위의 세 가지 체크리스트를 하나씩 확인해보시고, 문제를 해결하셨다면 댓글로 어떤 원인이었는지 공유해주세요.