GitHub Pages로 정적 사이트를 호스팅했는데 자신의 도메인을 연결하면 브라우저에 빨간 자물쇠(보안 경고)가 뜨거나, HTTPS 연결이 안 되는 경험을 해봤을까. 다만 대부분의 개발자들은 DNS 설정이 정확히 뭔지, Let's Encrypt 자동 갱신이 어떻게 작동하는지 모른 채 GitHub 설정 패널만 건드리다가 포기한다. 이번에는 GitHub Pages 커스텀 도메인 연결부터 HTTPS 인증서 자동 갱신까지 정확히 뭔지, 왜 필요한지, 어떻게 하는지 완벽하게 정리해서 소개하겠다.
GitHub Pages는 기본적으로 username.github.io 형태의 서브도메인을 제공한다. 하지만 직접 구매한 example.com 같은 루트 도메인이나 blog.example.com 같은 서브도메인을 연결하려면 DNS 레코드를 수정해야 한다. GitHub Pages는 A 레코드(IPv4 주소)나 CNAME 레코드(도메인 이름)를 통해 트래픽을 자신의 서버로 라우팅한다.
GitHub Pages가 제공하는 IP 주소는 다음 4개다. 루트 도메인(example.com)을 연결할 때는 이 IP 주소들에 대한 A 레코드를 만들어야 한다.
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153서브도메인(www.example.com, blog.example.com)을 연결할 때는 CNAME 레코드를 사용해서 username.github.io를 가리키면 된다. 이 차이를 이해하는 것이 DNS 설정의 핵심이다.
루트 도메인 연결(example.com)
루트 도메인을 GitHub Pages에 연결하려면 DNS 제공업체(예: Namecheap, Godaddy, 가비아)의 관리 패널에서 A 레코드 4개를 모두 추가해야 한다. 많은 개발자들이 1개나 2개의 IP만 등록했다가 간헐적인 연결 끊김을 경험한다. 4개를 모두 등록해야 GitHub의 로드밸런싱이 정상 작동한다.
| 필드 | 값 |
|---|---|
| Type | A |
| Name | @ (루트 도메인) |
| Value | 185.199.108.153 |
위 과정을 185.199.109.153, 185.199.110.153, 185.199.111.153에 대해서도 반복해야 한다.
서브도메인 연결(www.example.com)
www 서브도메인이나 blog.example.com 같은 경우 CNAME 레코드를 사용한다.
| 필드 | 값 |
|---|---|
| Type | CNAME |
| Name | www (또는 blog) |
| Value | username.github.io |
DNS 변경은 보통 24시간 이내에 전 세계 DNS 서버에 반영되지만, 경우에 따라 수 시간이 걸릴 수 있다.
DNS 레코드를 설정한 후, GitHub 저장소의 CNAME 파일과 Settings 패널도 함께 설정해야 한다. 저장소 루트 디렉토리에 CNAME이라는 파일을 만들고, 그 안에 사용할 도메인을 한 줄로 적는다.
example.com또는 www를 쓰려면
www.example.com이 파일이 저장소에 커밋되어야 GitHub Pages가 이를 인식한다. 동시에 GitHub 저장소의 Settings > Pages 탭에서도 Custom domain 필드에 도메인을 입력해야 한다. 여기서 값을 저장하면 GitHub가 자동으로 CNAME 파일을 생성한다. 만약 수동으로 CNAME 파일을 만들었다면 Settings 패널에서만 입력해도 괜찮다.
✗ 흔한 실수. DNS 레코드와 CNAME 파일을 설정한 후 몇 분만 기다리고 Settings > Pages에서 Enforce HTTPS 체크박스를 바로 체크하는 경우다. GitHub Pages는 Let's Encrypt를 통해 무료 SSL 인증서를 발급하는데, 이 과정은 DNS 전파 후 몇 분에서 최대 수십 분까지 걸릴 수 있다.
✓ 올바른 방법. 먼저 DNS 변경과 GitHub CNAME 설정을 완료한 후, 몇 분 기다렸다가 https://example.com에 접속해서 브라우저 주소창의 자물쇠 아이콘이 초록색(또는 회색)으로 표시되는지 확인한다. Let's Encrypt가 인증서를 발급했다는 신호다. 그다음에 Settings > Pages에서 Enforce HTTPS를 체크하면 안전하다.
Let's Encrypt는 90일마다 인증서를 갱신하는데, GitHub Pages는 이를 자동으로 처리한다. 개발자가 별도로 할 일은 없다. 다만 도메인을 여러 개 등록해서 한 저장소에서 여러 도메인을 호스팅하려는 경우, Settings 패널에는 하나의 도메인만 입력할 수 있다는 점을 주의해야 한다.
아래는 GitHub Pages 커스텀 도메인이 제대로 작동하는지 확인하는 dig 명령어다.
dig example.com +short다음과 같이 GitHub의 IP 주소 중 하나가 나타나면 A 레코드가 정상이다.
185.199.108.153CNAME 레코드를 확인하려면
dig www.example.com +shortusername.github.io가 나타나면 성공이다.
www.example.com. 1800 IN CNAME username.github.io.
username.github.io. 60 IN A 185.199.108.153HTTPS 인증서 상태는 OpenSSL로 확인할 수 있다.
openssl s_client -connect example.com:443 -servername example.com < /dev/null | grep -A 5 \"Certificate\"또는 온라인 SSL 체커 도구(예: sslchecker.com)를 사용해서 인증서 만료 날짜와 발급자(Let's Encrypt)를 확인하는 것도 빠르다.
문제 1. 도메인 연결 후 404 Not Found
✗ 잘못된 것: CNAME 파일이 저장소에 커밋되지 않았거나, Settings 패널의 Custom domain 입력 후 저장하지 않음.
✓ 올바른 것: git log로 CNAME 파일이 실제로 커밋되었는지 확인. GitHub Settings > Pages에서 Custom domain 필드에 도메인이 입력되고 저장되었는지 확인.
문제 2. HTTPS 아이콘이 안 떠서 보안 경고가 나타남
✗ 잘못된 것: DNS 전파 직후 바로 Enforce HTTPS를 활성화하려고 시도.
✓ 올바른 것: DNS 전파를 기다린 후(통상 5~10분, 최악 1시간) 브라우저 캐시를 지우고 https://example.com에 접속. GitHub Settings > Pages 패널에서 인증서 상태를 확인(Certificate provisioning에 체크가 떠야 함).
문제 3. www와 루트 도메인 중 하나만 작동
✗ 잘못된 것: 루트 도메인 A 레코드와 www CNAME 중 하나만 설정.
✓ 올바른 것: 루트 도메인(example.com)은 4개의 A 레코드로, www.example.com은 CNAME으로 각각 설정. 또는 모두 www로 통일하고 301 리다이렉트 사용.
문제 4. www에서 루트로(또는 반대로) 리다이렉트되지 않음
GitHub Pages 자체는 리다이렉트를 자동으로 처리하지 않는다. Jekyll 또는 별도의 _redirects 설정(Netlify 스타일)이 필요하지 않다면, 차라리 한 버전만 사용하거나 HTML 메타 태그로 canonical을 명시하는 것이 SEO에 안전하다.
DNS 변경 후 실제로 얼마나 전파되었는지 확인하려면 온라인 도구를 써야 한다. whatsmydns.net에 접속해서 example.com을 입력하면 전 세계 주요 DNS 서버에서 현재 도메인이 어느 IP를 가리키는지 실시간으로 볼 수 있다. 대부분의 서버(초록색)가 GitHub IP를 가리키면 안전하다.
GitHub Pages 커스텀 도메인 연결은 DNS 레코드, CNAME 파일, GitHub 설정 3가지가 모두 일치해야 작동한다. 하나라도 빠지면 404나 보안 경고가 나타난다. Let's Encrypt 인증서 발급도 자동이지만 DNS 전파가 먼저 완료되어야 하므로, 성급하게 Enforce HTTPS를 활성화하지 말고 실제 HTTPS 접속이 되는지 먼저 확인하자. dig와 openssl 같은 간단한 명령어로 DNS와 인증서 상태를 확인하는 습관이 모여서 도메인 트러블슈팅 시간을 크게 단축할 것이다. 이 글의 4단계 HTTPS 설정 부분과 6단계 흔한 문제 섹션을 참고해 GitHub Pages 커스텀 도메인을 완벽하게 구성하면, 1회 설정 후 몇 년 동안 추가 유지보수 없이 안전한 HTTPS 호스팅을 누릴 수 있을 것이다.