30초 요약
- 저장소 Settings → Pages의 Custom domain에 서브도메인(예:
blog.example.com)을 먼저 저장한다. - DNS 공급자에서 그 서브도메인의 CNAME 레코드를
<user>.github.io로 만든다. 저장소 이름은 붙이지 않는다. dig blog.example.com +noall +answer -t A로 확인하고, 인증서가 나오면 Enforce HTTPS를 켠다.
증상/목표
https://<user>.github.io/<repo>/ 대신 https://blog.example.com/ 같은 내 서브도메인으로 사이트를 열고, HTTP 요청은 HTTPS로 넘어가게 하는 것이 목표다. 이 글은 GitHub Actions 워크플로로 배포하는 저장소를 기준으로 쓴다.
원인
서브도메인이 열리지 않을 때 대부분은 순서나 값이 어긋난 경우다. 조건은 넷이다.
- DNS 레코드만 만들고 GitHub에 도메인을 저장하지 않으면 Pages가 그 도메인을 사이트와 연결하지 않는다.
- CNAME 값은 항상
<user>.github.io또는<organization>.github.io여야 하고 저장소 이름을 뺀다. Pages 설정에 보이는 고유*.pages.github.io주소로 향하게 하지 않는다. - 사용자 지정 Actions 워크플로로 배포하면
CNAME파일이 만들어지지 않고, 있어도 무시된다. 도메인은 저장소 설정에서만 정한다. - DNS 변경은 반영까지 최대 24시간이 걸릴 수 있다.
해결 방법
1. GitHub에 사용자 지정 도메인 저장
저장소의 Settings → Pages에서 Custom domain에 blog.example.com을 입력하고 저장한다. 문서는 도메인을 저장소에 추가하기 전에 먼저 소유권을 검증(domain verification)하기를 권한다. 검증하지 않고 DNS를 먼저 설정하면 다른 사람이 그 서브도메인에서 사이트를 호스팅할 수 있기 때문이다.
2. DNS 공급자에서 CNAME 레코드 만들기
DNS 관리 화면에서 다음 레코드를 추가한다. 이름 칸 표기(blog 또는 blog.example.com)는 공급자마다 다르다.
| 유형 | 이름 | 값 |
|---|---|---|
| CNAME | blog | <user>.github.io |
문서는 *.example.com 같은 와일드카드 DNS 레코드를 쓰지 말라고 강하게 권한다. 도메인을 검증해도 도메인 탈취 위험이 즉시 생기기 때문이다.
3. dig로 확인
macOS·리눅스·Git Bash에서는 dig를 쓴다. Windows PowerShell에서는 Resolve-DnsName을 쓴다.
dig blog.example.com +noall +answer -t A응답에 <user>.github.io와 GitHub Pages의 IP 주소가 보이면 레코드가 반영된 것이다. 아직 비어 있으면 반영을 기다린다.
4. HTTPS 강제
Settings → Pages에서 Enforce HTTPS를 선택한다. 저장소 관리자 권한이 필요하고, 켜면 HTTP 요청이 HTTPS로 리디렉션된다. 인증서는 Let’s Encrypt에서 받는다. 저장하고 몇 분이 지나도 인증서가 만들어지지 않으면 Custom domain 옆 Remove를 누른 뒤 도메인을 다시 입력하고 저장한다. 프로비저닝이 취소되고 다시 시작된다. 인증서 발급 방식 자체가 바뀌는 흐름은 Cloudflare CA 신청과 Merkle Tree Certificates 정리에 있다.
커스텀 도메인으로 바꾼 뒤 Astro의 site·base 설정은 Astro 사이트 CSS·JS 404 해결에 있다.
확인
러너 안에 로컬 DNS 서버(dnsmasq, 127.0.0.1:5353)를 띄워 blog.example.test가 myuser.github.io를 가리키는 CNAME 레코드를 흉내 내고 dig로 조회했다. 실제 DNS 공급자나 GitHub Pages가 아니라 흉내 낸 환경에서의 결과다.
검증 범위: dig로 CNAME 값을 읽는 과정은 로컬 DNS 서버에서 실행으로 확인했고, Custom domain 저장·도메인 검증·인증서 발급·Enforce HTTPS 동작은 공식 문서로 대조했다.
검증 환경 4항목
| OS | Ubuntu 24.04.5 |
|---|---|
| dnsmasq | 2.91 |
| 실행 날짜 | 2026-10-20 |
| 작성자 기재 환경 | DNS 확인 단계는 러너 안 로컬 DNS 서버(dnsmasq)로 흉내 냄. GitHub 설정 화면 단계는 공식 문서 대조 |
Running kernel seems to be up-to-date. No services need to be restarted. No containers need to be restarted. No user sessions are running outdated binaries. No VM guests are running outdated hypervisor (qemu) binaries on this host. [PASS] dnsmasq 실행 파일이 있다 서버 시작: 127.0.0.1:5353 (/usr/sbin/dnsmasq --keep-in-foreground --user=runner --port=5353 --listen-address=127.0.0.1 --bind-interfaces --no-resolv --no-hosts --host-record=myuser.github.io,192.0.2.10 --cname=blog.example.test,myuser.github.io)
[XFAIL] 등록되지 않은 www.example.test의 CNAME 조회 — 예상된 실패 재현됨 (/no-record-found/)
> no-record-found[PASS] dig가 CNAME 값을 돌려줬다 [PASS] CNAME 값이 myuser.github.io.이다(저장소 이름 없음) [PASS] CNAME을 따라 가면 A 레코드까지 풀린다
주의
- CNAME 값에 저장소 이름을 붙이지 않는다. DNS는 호스트만 가리키고 경로는 모른다. 붙이면 레코드 자체가 틀린다.
- 와일드카드 DNS 레코드(
*.example.com)를 쓰지 않는다. 문서는 이것이 도메인 탈취 위험을 만든다고 설명한다. @호스트에 불필요한A,AAAA,ALIAS,ANAME레코드가 있거나www등 다른 서브도메인을 가리키는 CNAME이 있으면 HTTPS 인증서 생성이 막힐 수 있다.- HTTPS를 켠 뒤에도 HTML이
http://주소로 리소스를 불러오면 혼합 콘텐츠가 된다. 소스에서http://를 검색해https://로 바꾼다. - Astro 등에서
site값을 바꿔야 하는 경우가 많다. 서브도메인을 연결하면 사이트 주소가 바뀌므로 빌드 설정의site를 새 주소로 맞춘다.
자주 묻는 질문
저장소에 CNAME 파일을 만들어야 하나?
사용자 지정 GitHub Actions 워크플로로 배포하면 필요 없다. 이 방식에서는 CNAME 파일이 만들어지지 않고 있어도 무시된다. 브랜치에서 게시하는 방식이면 저장소 설정에 도메인을 저장할 때 소스 브랜치 루트에 CNAME 파일이 만들어진다.
CNAME 값을 <user>.github.io/<repo>로 적어도 되나?
안 된다. DNS 레코드에는 경로를 넣을 수 없다. 값은 저장소 이름을 뺀 <user>.github.io다.
Windows에는 dig가 없다. 어떻게 확인하나?
PowerShell의 Resolve-DnsName blog.example.com 명령을 쓴다.