GitHub Pages에서 Jekyll 블로그가 자동 배포되지 않는 이유, 30년 경력 교수가 직접 해결한 방법

들어가며: 60대 교수의 예상 밖의 도전기

저는 30년을 대학에서 전자공학을 가르쳤습니다. 작년 은퇴 후, 평생 정리해온 강의 노트와 연구 자료를 온라인에 공개하고 싶었습니다. 어렸을 때부터 좋아하던 글쓰기도 다시 시작하고 싶었죠. 그렇게 시작한 것이 Jekyll Chirpy 블로그였습니다.

처음 블로그를 만들고 GitHub에 올렸을 때, 저는 자동 배포가 되어야 한다고 생각했습니다. “GitHub Pages는 자동으로 처리해주겠지”라는 막연한 신뢰가 있었거든요. 그러나 현실은 냉혹했습니다. 며칠을 기다려도 블로그가 업데이트되지 않는 것이었습니다. 마치 제 강의 자료가 검은 구멍으로 빨려 들어가는 것 같았습니다.

첫 번째 시도: 문제 인식과 기본 점검

아무리 커밋을 해도 변화가 없자, 저는 체계적으로 접근하기로 했습니다. 학생들을 가르칠 때 항상 “문제를 정확히 파악하고 가설을 세워라”고 했으니까요.

먼저 확인한 것은 GitHub 저장소의 Settings입니다. GitHub Pages가 제대로 활성화되었는지, 어느 브랜치에서 배포되고 있는지를 살폈습니다. 제 경우 문제가 바로 드러났습니다. Build and deployment 섹션에서 “Deploy from a branch”가 선택되어 있었지만, 실제로 Jekyll 빌드 프로세스가 실행되지 않고 있었던 것입니다.

GitHub Pages에서 제공하는 자동 Jekyll 빌드는 일정한 조건을 만족해야 합니다. 특히 저는 Chirpy 테마를 사용했는데, 이것이 기본 Jekyll 테마가 아니라서 자동 빌드가 작동하지 않았던 것이죠.

두 번째 시도: 자동 빌드 파이프라인 구축하기

문제를 파악한 후, 해결책은 명확했습니다. GitHub Actions를 사용하여 직접 빌드 파이프라인을 구축하는 것이었습니다.

GitHub Actions는 GitHub에서 제공하는 자동화 서비스입니다. 저는 처음에 이것을 “복잡한 개발자용 도구”라고 생각했습니다만, 실제로는 상당히 직관적이었습니다. Jekyll 블로그 빌드를 위한 표준 워크플로우가 이미 많이 공개되어 있었거든요.

저는 .github/workflows/ 디렉토리에 build.yml 파일을 생성했습니다. 이 파일에는 다음과 같은 내용이 포함되어 있습니다:

1. Trigger 설정: 언제 빌드가 실행될 것인가 (보통 main 브랜치에 push될 때)
2. 환경 설정: Ruby 버전, gem 의존성 설치
3. 빌드 명령어: Jekyll을 이용해 정적 파일 생성
4. 배포: 생성된 파일을 gh-pages 브랜치로 배포

이렇게 설정하면, 제가 마크다운 파일을 작성해서 GitHub에 푸시하는 순간, 자동으로 전체 프로세스가 시작됩니다. 마치 제 강의실 안의 조수들이 자동으로 수업 자료를 정리하고 게시판에 붙여주는 것처럼요.

세 번째 시도: 세부 설정과 최적화

첫 번째 빌드는 성공했지만, 모든 것이 완벽하지는 않았습니다. 몇 가지 추가 설정이 필요했습니다.

첫째, GitHub Token 권한 문제입니다. GitHub Actions가 gh-pages 브랜치에 쓰기 권한을 가져야 합니다. 저는 Repository Settings에서 “Workflow permissions”를 “Read and write permissions”로 설정했습니다.

둘째, 루비 버전 호환성입니다. Chirpy 테마는 특정 루비 버전과 특정 gem 버전을 요구합니다. 저는 Gemfile을 정확히 구성하고, 로컬에서 bundle exec jekyll serve로 테스트한 후에야 GitHub에 올렸습니다. 이것이 많은 시간을 절약해주었습니다.

셋째, 배포 설정입니다. GitHub Pages Settings에서 “Build and deployment” 섹션의 Source를 “GitHub Actions”로 변경했습니다. 이것이 가장 중요한 부분이었습니다.

실제 해결 과정에서 배운 교훈

이 모든 과정을 거치면서, 저는 몇 가지 중요한 교훈을 얻었습니다.

첫째, 문서를 읽는 것의 중요성입니다. GitHub Pages 공식 문서에는 모든 해답이 있었습니다. 저는 너무 빨리 가정하고 넘어갔습니다.

둘째, 로컬에서의 테스트입니다. GitHub에 바로 올리기 전에 로컬 머신에서 완벽하게 작동하는지 확인하는 것이 얼마나 중요한지 깨달았습니다. 이것이 개발 시간을 절반으로 단축했습니다.

셋째, 커뮤니티의 힘입니다. GitHub의