GitHub Pages 무료 호스팅에서 HTTPS까지, 내가 겪은 세 가지 설정 함정

은퇴 후 블로깅을 시작하며 마주한 예상 밖의 기술 과제

올해 68세가 되어 30년간의 교수 생활을 마감하고, 지난 3년간 취미 삼아 기술 블로그를 운영하고 있습니다. 젊은 시절엔 Linux 커널 연구로 논문을 썼지만, 그 이후로는 실무적인 웹 기술과는 거리가 있었습니다. GitHub Pages와 Jekyll을 선택한 이유는 단순했습니다. 무료이고, 버전 관리와 배포가 한 번에 이루어지며, 무엇보다 개발자다운 방식이라고 생각했거든요.

하지만 현대의 웹 표준은 생각보다 복잡했습니다. 특히 HTTPS 설정 부분에서 말입니다. 처음 블로그를 공개했을 때 방문자들로부터 “보안 경고가 떠요”라는 메일을 받고 한참을 헤맸던 기억이 납니다. 그 과정에서 배운 세 가지 주요 함정을 이 글을 통해 공유하겠습니다.

첫 번째 함정: 리포지토리 이름과 도메인의 불일치

GitHub Pages는 두 가지 배포 방식을 제공합니다. 사용자 페이지(username.github.io)와 프로젝트 페이지입니다. 저는 처음에 이 차이를 제대로 이해하지 못했습니다. 리포지토리 이름을 “my-blog”로 설정했는데, GitHub은 자동으로 username.github.io/my-blog 경로에 배포했습니다. 그런데 저는 루트 도메인에서 블로그가 실행될 것으로 예상했던 거죠.

그 결과 Jekyll의 설정 파일(_config.yml)에서 baseurl 설정을 수정해야 했습니다. 이를 생략하면 CSS와 JavaScript 파일들이 올바른 경로에서 로드되지 않아 페이지가 깨져 보입니다. 저는 이것을 “유령 CSS 현상”이라고 부릅니다. 페이지는 열리는데 스타일이 먹지 않는 것이죠. Chirpy 테마를 사용 중이라면 더욱 주의가 필요합니다.

올바른 설정 방법은 다음과 같습니다. 만약 username.github.io라는 리포지토리를 사용한다면 baseurl을 공백으로 두면 됩니다. 반면 프로젝트 페이지라면 /my-blog처럼 설정해야 합니다. 저는 결국 사용자 페이지로 변경하는 것이 더 간단하다고 판단했고, 리포지토리 이름을 username.github.io로 변경했습니다.

두 번째 함정: GitHub Pages의 HTTPS 자동 설정 지연

GitHub Pages는 Let’s Encrypt를 통해 무료 SSL 인증서를 제공합니다. 이는 정말 훌륭한 서비스입니다. 하지만 이 인증서가 자동으로 발급되기까지는 시간이 걸린다는 사실을 알아야 합니다. 리포지토리를 생성하고 즉시 GitHub 설정에서 HTTPS를 활성화해도, 몇 분에서 몇 시간이 필요할 수 있습니다.

저는 처음 배포 후 30분 내에 HTTPS를 강제하도록 설정했다가, 방문자들이 인증서 오류를 보게 되었습니다. Settings > Pages 섹션에서 “Enforce HTTPS” 옵션이 있지만, 이것을 체크하기 전에 충분히 기다려야 합니다. 보통 한 두 시간이면 충분하지만, 때로는 더 오래 걸릴 수도 있습니다.

확인하는 방법은 간단합니다. 브라우저의 개발자 도구에서 콘솔을 열고 경고 메시지가 없는지 확인하거나, 온라인 SSL 체커(ssllabs.com)를 이용하면 됩니다. 제 경험상 GitHub 공식 문서에는 이 대기 시간이 명확하게 명시되지 않아서 많은 사용자가 혼동을 겪고 있습니다.

세 번째 함점: 커스텀 도메인과 HTTPS의 예상치 못한 충돌

개인 도메인(예: myblog.com)을 설정하려고 할 때가 바로 가장 복잡한 상황입니다. 저는 처음에 도메인 레지스트라에서 CNAME을 username.github.io로 설정했습니다. GitHub은 이를 인식하고 자동으로 리다이렉트합니다. 하지만 HTTPS 인증서는 어떻게 될까요?

GitHub Pages의 HTTPS 자동 설정은 기본적으로 username.github.io 도메인에 대해서만 작동합니다. 커스텀 도메인에 대해서도 자동 인증서를 발급하지만, 이 과정에서 DNS 설정이 올바르게 되어야 합니다. A 레코드와 CNAME 레코드가 충돌하면 인증서 발급이 실패합니다.

제가 권장하는 방법은 다음과 같습니다. 첫째, GitHub Settings에 커스텀 도메인을 입력합니다. 둘째, 도메인 레지스트라에서 DNS를 설정합니다(일반적으로 CNAME 또는 A 레코드). 셋째, GitHub에서 HTTPS 활성화 버튼이 나타날 때까지 기다립니다(최대 24시간). 이 과정을 건너뛰고 강제하려다 보니 많은 문제가 발생했습니다.

제 블로그는 이제 완벽하게 작동합니다. HTTPS는 자동으로 모든 방문자에게 강제되고, 페이지 로드 속도도 빠릅니다. 지금 여러분도 같은 문제를 겪고 있다면, 차근차근 위 세 가지를 점검해 보시기 바랍니다. GitHub Pages는 훌륭한 서비스이지만, 세부 사항에서 주의가 필요합니다. 여러분의 블로그도 이 가이드를 따라 완벽하게 설정될 수 있기를 바랍니다.