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

은퇴 후 블로그를 시작하며 겪은 첫 번째 충격

저는 대학에서 30년을 가르친 후 올해 초 은퇴했습니다. 한가한 시간을 활용해 기술 블로그를 운영해야겠다는 생각에 Jekyll과 GitHub Pages를 선택했는데, 첫날부터 난관에 봉착했습니다. 로컬에서는 완벽하게 작동하던 블로그가 GitHub에 푸시하는 순간 빌드 오류로 실패하는 것이었습니다.

처음에는 GitHub의 자동 알림 메일이 오면 뭔가 설정이 잘못된 줄 알았습니다. 하지만 같은 오류가 반복되자 체계적으로 문제를 파악해야겠다고 느꼈습니다. 교수 시절 자문했던 선배 개발자들의 조언과 제 나름의 시행착오를 거쳐 결국 패턴을 발견했습니다. 지금부터 그 경험을 여러분과 나누겠습니다.

Jekyll 빌드 실패의 99%는 세 가지 원인에서 나온다

제 경험상 GitHub Pages에서 Jekyll 빌드가 실패하는 경우는 대부분 다음 세 가지 중 하나입니다.

첫째는 _config.yml 파일의 문법 오류입니다. YAML 포맷은 들여쓰기(인덴테이션)가 생명입니다. 스페이스와 탭을 혼용하면 안 되며, 콜론 뒤에는 반드시 공백이 있어야 합니다. 제가 겪은 사례를 말하자면, url: https://myblog.com 이라고 적어야 하는데 실수로 url:https://myblog.com 이라고 작성했던 적이 있습니다. 로컬에서는 작동했지만 GitHub의 Jekyll 엔진은 이를 거부했습니다.

둘째는 호환되지 않는 플러그인 사용입니다. GitHub Pages는 보안상 특정 플러그인만 공식 지원합니다. 제가 Chirpy 테마를 사용하며 커스터마이징하다 보니, 추가로 설치한 플러그인 중 일부가 GitHub에서 작동하지 않았습니다. 특히 jekyll-paginate-v2는 로컬에서는 잘 작동했지만 GitHub Pages에서는 오류를 냈습니다.

셋째는 마크다운 파일의 인코딩 문제와 메타데이터 오류입니다. 포스트 맨 앞의 YAML 프론트매터가 제대로 닫혀있지 않거나, 파일이 UTF-8이 아닌 다른 인코딩으로 저장되면 빌드가 실패합니다.

빠른 진단과 해결 방법

Step 1: GitHub Actions 로그 확인하기

GitHub 저장소 → Actions 탭 → 실패한 워크플로우를 클릭하면 상세 로그를 볼 수 있습니다. 오류 메시지는 매우 구체적입니다. “Error: YAML parse error on line 12” 같은 식으로 정확한 위치와 문제를 알려줍니다. 저는 이 로그를 매번 꼼꼼히 읽고 메모장에 기록해두는 습관을 들였습니다.

Step 2: 로컬에서 먼저 검증하기

bundle exec jekyll build

이 명령으로 로컬 빌드를 시도하면, GitHub와 동일한 환경에서 문제를 재현할 수 있습니다. Gemfile과 Gemfile.lock을 GitHub 저장소에 커밋해야 GitHub도 같은 버전의 의존성을 사용합니다.

Step 3: _config.yml 검증 사이트 활용

yamllint.com 같은 온라인 YAML 검증 도구에 _config.yml 내용을 붙여넣으면 문법 오류를 즉시 발견할 수 있습니다. 제가 너무 늦게 알았던 도구인데, 이것을 알았더라면 몇 시간을 절약했을 것 같습니다.

예방책: 스마트한 개발자의 습관

은퇴 후 여유롭게 살고 있지만, 블로그 운영에서만큼은 체계적으로 접근하려 노력합니다. 저는 이제 새로운 포스트를 작성할 때마다 다음 체크리스트를 따릅니다.

• 포스트 파일명이 YYYY-MM-DD-title.md 형식인가?
• 프론트매터의 --- 구분자가 정확히 두 개인가?
• 마크다운 코드 블록의 백틱이 정확히 세 개씩인가?
• 이미지 경로는 상대 경로를 사용했는가?
• 카테고리와 태그 이름에 특수문자가 없는가?

또한 로컬에서 bundle exec jekyll serve로 실행한 후 http://localhost:4000 에서 직접 확인한 뒤에만 GitHub에 푸시합니다. 이 습관 하나가 빌드 실패를 90% 이상 줄여주었습니다.

Jekyll과 GitHub Pages는 매우 강력한 조합이지만, 초반의 작은 설정 실수가 큰 좌절감을 주기도 합니다. 제가 겪은 오류들이 여러분의 귀중한 시간을 절약해주길 바랍니다. 혹시 여전히 빌드 오류로 고민 중이라면, 댓글로 구체적인 오류 메시지를 남겨주세요. 제 경험 범위 내에서 함께 해결해드리겠습니다.