문제
사이트를 만들어 GitHub 저장소에 올렸더니 GitHub Pages가 your-username.github.io에서 잘 서빙합니다. 그런데 내 도메인을 가리키게 하고 기다리면 빈 페이지, 404, 인증서 경고, 또는 도메인이 “제대로 구성되지 않았다”는 Pages 설정 메시지가 뜹니다. 내 눈엔 DNS가 맞아 보입니다. 대개 조금 어긋나 있고, 그 이유는 매번 같은 두세 가지입니다.
GitHub Pages 커스텀 도메인은 작고 예측 가능한 방식으로 실패합니다. A 레코드가 있어야 할 apex에 CNAME을 건 경우, 레코드가 엉뚱한 곳으로 해석되는 경우, HTTPS 발급이 끝나지 않는 경우. GitHub가 DNS 계층에서 실제로 뭘 기대하는지 알면 하나도 신비롭지 않습니다.
GitHub Pages가 DNS에서 요구하는 것
GitHub Pages는 커스텀 도메인을 고정된 애니캐스트 주소 세트에서 서빙합니다. apex 도메인(example.com, 앞에 서브도메인 없음)에는 아래 IPv4 4개 모두에 A 레코드를 발행합니다.
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153그리고 IPv6 전용 클라이언트도 닿을 수 있도록 대응하는 AAAA 레코드 4개도 넣습니다.
2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153서브도메인 — www.example.com, blog.example.com, docs.example.com — 에는 저 주소를 쓰지 않습니다. GitHub Pages 호스트명을 가리키는 CNAME 하나를 발행합니다.
www.example.com. CNAME your-username.github.io.대상이 your-username.github.io(조직 사이트라면 your-org.github.io)라는 점에 주의하세요. 저장소 이름도, 지어낸 호스트명도 아닙니다. GitHub는 사이트에 저장한 CNAME 파일로 라우팅하므로, DNS는 트래픽을 GitHub 대문까지만 보내면 됩니다.
apex CNAME 함정
연결이 실패하는 가장 흔한 방식입니다. 호스팅사나 어떤 튜토리얼이 “도메인을 your-username.github.io로 CNAME 하라”고 하고, 당신은 그걸 맨 example.com에 넣습니다. 그러면 패널이 거부하거나 사이트가 끝내 안 뜹니다.
맨 apex에는 CNAME을 걸 수 없습니다. GitHub의 제약이 아니라 RFC 1034 §3.6.2입니다. 한 이름에 CNAME이 있으면 다른 레코드가 함께 있을 수 없는데, 모든 존의 apex는 SOA·NS 레코드를 반드시 가져야 합니다. apex의 CNAME은 그것들과 충돌하므로 정상 네임서버는 거부합니다.
그래서 apex에서 정당한 선택지는 둘입니다.
- 위의 A 레코드 4개(그리고 AAAA). GitHub가 문서화한 방식이고 어디서나 작동합니다.
- ALIAS / ANAME / CNAME 플래트닝. DNS 제공자가 지원하면 씁니다 — Cloudflare는 CNAME flattening, Route 53은 ALIAS 레코드, 다른 곳은 ANAME이라 부릅니다.
your-username.github.io를 대상으로 넣으면 제공자가 응답 시점에 A 레코드로 풀어, 불법 apex CNAME 없이 CNAME 같은 동작을 줍니다.
서브도메인엔 이런 규칙이 없습니다. www와 친구들은 CNAME을 바로 받습니다. www엔 CNAME, apex엔 주소 — 이 비대칭이 바로 사람들이 거꾸로 하는 지점입니다.
먼저 도메인을 인증하고, 그다음 설정
순서를 지키면 사이트가 깨지는 것보다 더 고약한 문제 — 남이 내 도메인을 가로채는 것 — 을 피합니다.
GitHub는 도메인을 저장소에 붙이기 전에 (계정 또는 조직 설정의 Pages에서) 인증(verify) 할 수 있게 합니다. 인증은 그 이름의 소유를 증명해, 다른 GitHub 사용자가 자기 Pages 사이트를 당신 도메인에 가리키지 못하게 합니다. 먼저 인증하고, DNS가 해석되면 저장소에 커스텀 도메인을 설정하세요. 인증을 건너뛰어도 치명적이진 않지만 탈취 틈을 남기며, 그 틈을 열어둘 이유가 없습니다.
Settings → Pages에서 커스텀 도메인을 설정하면 GitHub가 저장소에 도메인을 담은 CNAME 파일을 씁니다. 소스에도 CNAME 파일을 두고 둘이 어긋나면 — 예컨대 빌드가 덮어쓰면 — 사이트가 두 도메인 사이를 오가거나 커스텀 도메인을 아예 잃습니다. 진실의 출처를 하나로 정하세요. Settings 칸으로 관리하거나 파일을 커밋하거나, 둘이 싸우게 두지 마세요.
HTTPS 대기는 정상입니다 (어느 선까지는)
DNS가 GitHub를 가리키면 GitHub는 당신 도메인용 Let’s Encrypt 인증서를 자동 요청합니다. 그 인증서가 발급되기 전까지는 Enforce HTTPS 체크박스가 비활성화되고, 사이트가 잠시 엉뚱한 이름의 인증서를 서빙할 수 있습니다. 정상이며 최대 24시간까지 걸립니다. 더 세게 클릭한다고 고쳐지는 게 아닙니다.
하루를 넘겨 멈추게 하는 원인은 둘입니다.
- Let’s Encrypt를 배제하는 CAA 레코드. CAA 레코드는 어느 인증기관이 발급할 수 있는지 제한합니다. CAA 레코드가 하나라도 있고 거기에
letsencrypt.org가 없으면 GitHub의 발급이 조용히 실패합니다. Let’s Encrypt를 CAA에 추가하거나 레코드를 지우세요. - GitHub 앞단의 프록시 CDN. 레코드 앞에 Cloudflare 프록시(주황 구름)를 두면 도메인 검증 챌린지를 가로채 인증서가 발급되지 않을 수 있습니다. 발급 동안은 DNS 전용으로 두세요. 프록시는 나중에 다시 켜되, HTTPS·캐싱 동작이 달라진다는 점을 알고 하세요.
DNS가 맞고, Let’s Encrypt를 막는 CAA도 없고, 프록시도 없는데 하루가 지나도 멈춰 있으면 Settings에서 커스텀 도메인을 지우고 저장한 뒤 1분 기다렸다 다시 넣어 발급을 새로 시도하게 하세요.
DechoNet으로 점검
- DNS 조회는 이름의 실제 A·AAAA·CNAME 레코드를 읽어줍니다. apex가 GitHub IP 4개(그리고 AAAA 세트)를 진짜로 담았는지,
www가your-username.github.io로 향하는 CNAME인지, apex에 CNAME을 실수로 남기지 않았는지 확인하세요. 인증서를 막고 있을 수 있는 CAA 레코드도 보여줍니다. - DNS 전파는 여러 네트워크의 리졸버에서 레코드를 동시에 확인합니다 — 등록기관에서 레코드를 고친 뒤 “내가 실수했다”와 “아직 안 퍼졌다”를 가르는 방법입니다.
- SSL 점검은 실제로 어떤 인증서가 어느 이름으로 서빙되는지 보여주므로, Let’s Encrypt 인증서 발급이 끝나 apex와 www를 둘 다 덮는지(옛것이나 불일치가 아닌지) 확인할 수 있습니다.
해결 체크리스트
- apex에 A 레코드 4개(
185.199.108.153,.109.153,.110.153,.111.153)와 AAAA 레코드 4개를 발행. 맨 apex엔 절대 CNAME 금지. - www(또는 임의 서브도메인)에
your-username.github.io로 향하는 CNAME 하나 — 저장소 이름도, IP도 아님. - 제공자에 ALIAS/ANAME/플래트닝이 있고 IP를 손으로 베끼기 싫으면, apex에서
your-username.github.io를 대상으로 그걸 사용. - GitHub에서 도메인을 인증한 뒤 Settings → Pages에서 커스텀 도메인을 설정하고
CNAME파일은 GitHub가 관리하게 두기(충돌하는 파일을 따로 커밋하지 말 것). - 무언가 틀렸다고 단정하기 전에 여러 리졸버에서 레코드가 GitHub로 해석되는지 확인하고 TTL을 기다리기.
- Enforce HTTPS는 최대 24시간 그냥 두기. 멈추면
letsencrypt.org를 배제하는 CAA 레코드가 있는지 확인해 지우고, 발급 동안 프록시 CDN을 걷어내기.
언제 에스컬레이션하나
- DNS가 GitHub IP 4개로 해석되고 전파도 일치하는데 사이트가 여전히 404면, 문제는 DNS를 떠난 것입니다. 저장소의 Pages 소스(브랜치·폴더)가 설정됐고 빌드가 실제로 발행됐는지 확인하세요 — DNS 경로가 초록불이어도 발행 안 된 사이트는 못 살립니다.
- DNS가 깨끗하고 막는 CAA도, 앞단 프록시도 없는데 하루가 지나도 인증서가 발급되지 않으면 지원 스레드를 열 시점입니다. 깨끗한 구성에서 끝나지 않는 발급은 GitHub 쪽 결함이며, 그들은 정확한 도메인과 설정한 시각을 원할 것입니다.
- 두 이름이 어긋나면 — apex는 되는데
www가 안 되거나 그 반대 — 잘 되는 쪽을 잘못 설정한 게 아니라 둘 중 하나가 빠진 것입니다. 되는 레코드를 바꾸지 말고, 빠진 apex A/AAAA나 빠진wwwCNAME을 추가하세요.
내 도메인에서 바로 확인
무료, 가입 불필요. 이 가이드가 다루는 항목을 바로 검사하고 조치 방법을 알려드립니다.