GitHub Pages에서 Jekyll 블로그가 자동 배포 안 될 때, 나는 이렇게 해결했다

은퇴 후의 뜻밖의 도전

올해로 대학을 떠난 지 5년째입니다. 정년퇴직 후 그동안 쌓인 교육 노하우와 기술 경험을 정리하고 싶어 GitHub Pages에 Jekyll 블로그를 개설했습니다. 첫 포스트를 작성하고 GitHub에 푸시했을 때, 분명 모든 파일이 올바르게 커밋되었는데 웹사이트에는 반영되지 않는 일이 발생했습니다. 그때부터 시작된 나의 기술 탐정 활동이 오늘의 이야기입니다.

처음에는 캐시 문제라고 생각하고 몇 시간을 기다렸습니다. 하지만 여전히 변화가 없었습니다. GitHub 저장소 설정도 확인했고, Jekyll 설정 파일도 여러 번 검토했습니다. 그렇게 하루를 허비한 후, 저는 본격적으로 문제를 진단하기 시작했습니다. 대학에서 40년간 학생들을 가르쳐온 경험이 이때 도움이 되었습니다. 체계적으로 접근하는 것의 중요성 말입니다.

첫 번째 발견: Actions 탭의 빨간 불빛

GitHub 저장소의 Actions 탭을 열었을 때, 그 순간 문제를 깨달았습니다. 배포 워크플로우가 실패하고 있었던 것입니다. 빨간 X 표시가 붙은 워크플로우 실행 로그를 들어갔을 때 정확한 오류 메시지가 보였습니다: “GitHub Pages is disabled for this repository.”

이것이 나의 첫 번째 교훈이었습니다. GitHub Pages 기능이 활성화되지 않았던 것입니다. 저장소의 Settings 탭으로 이동해 “Pages” 섹션을 찾았고, 그곳에서 명시적으로 빌드 소스를 설정해야 했습니다. 기본값이 “Deploy from a branch”로 되어 있었는데, 저는 이를 “GitHub Actions”로 변경했습니다.

이 작은 설정 변경이 얼마나 큰 차이를 만드는지 깨달은 순간, 저는 마치 학생들이 복잡한 수식을 단순화했을 때의 그 희열을 느꼈습니다. 많은 초보자들이 이 부분을 놓치고 있다는 것을 알았고, 그것이 바로 제가 이 경험담을 나누려는 이유입니다.

두 번째 발견: Ruby 버전과 의존성 문제

설정을 변경한 후에도 여전히 빌드가 실패했습니다. 이번에는 다른 오류 메시지가 나타났습니다. “Gemfile.lock과 실제 환경의 Ruby 버전이 맞지 않는다”는 내용이었습니다.

Jekyll 블로그를 로컬에서 실행할 때와 GitHub Actions 환경에서의 Ruby 버전이 달랐던 것입니다. 저는 로컬 머신에서 ruby --version으로 확인한 결과를 바탕으로, 같은 버전을 GitHub Actions 워크플로우 파일에서 명시해야 했습니다.

구체적으로는 저장소의 .github/workflows/ 디렉토리에 있는 pages.yml 파일을 수정했습니다:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true

이 과정에서 저는 한 가지 중요한 원칙을 다시 한 번 깨달았습니다. 바로 “개발 환경과 배포 환경의 일관성”입니다. 대학 강의실에서 “프로그래밍은 일관성의 예술”이라고 수없이 말했던 나의 말이 정확했다는 것을 실감했습니다.

세 번째 발견: _config.yml의 숨겨진 설정

마지막 문제는 좀 더 교묘했습니다. 빌드는 이제 성공했지만, 배포된 사이트의 스타일이 완전히 깨져 있었습니다. CSS 파일들이 로드되지 않았던 것입니다.

원인은 _config.yml 파일의 baseurl 설정이었습니다. 저는 저장소 이름이 사용자명과 다르기 때문에 baseurl을 올바르게 설정해야 했습니다:

baseurl: "/repository-name"
url: "https://username.github.io"

만약 사용자 페이지(username.github.io)라면 baseurl을 비워두거나 “/”로 설정하면 되지만, 프로젝트 저장소의 경우 반드시 저장소 이름을 baseurl로 지정해야 합니다.

이 문제를 해결한 후 모든 것이 완벽하게 작동했습니다. 배포 후 약 1-2분이면 웹사이트에 변경 사항이 반영되기 시작했습니다. 그 때의 만족감은 제 인생에서 처음 논문을 게재했을 때의 느낌과 비슷했습니다.

예방 팁: 나처럼 고생하지 마세요

지난 몇 개월간 블로그를 운영하면서, 저는 초기 설정 시 확인해야 할 체크리스트를 만들었습니다:

1. Repository Settings → Pages 확인: “GitHub Actions”가 빌드 소스로 선택되어 있는지