출처 대조 B · DNS 확인 단계는 러너 안 로컬 DNS 서버로 흉내 냄. GitHub 설정 화면 단계는 공식 문서 대조

검증 환경: DNS 확인 단계는 러너 안 로컬 DNS 서버(dnsmasq)로 흉내 냄. GitHub 설정 화면 단계는 공식 문서 대조

게시 2026-10-20최종 확인 2026-10-20읽기 5분

GitHub Pages 서브도메인 연결: DNS CNAME 설정과 HTTPS 강제

GitHub Pages에 blog.example.com 같은 서브도메인을 연결하는 순서. Custom domain 입력, DNS CNAME 레코드, dig 확인, Enforce HTTPS까지 정리한다.

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)는 공급자마다 다르다.

유형이름값
CNAMEblog<user>.github.io

문서는 *.example.com 같은 와일드카드 DNS 레코드를 쓰지 말라고 강하게 권한다. 도메인을 검증해도 도메인 탈취 위험이 즉시 생기기 때문이다.

3. dig로 확인

macOS·리눅스·Git Bash에서는 dig를 쓴다. Windows PowerShell에서는 Resolve-DnsName을 쓴다.

Terminal window
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 동작은 공식 문서로 대조했다.

CI 실행 결과 · 수정 전 재현 1건 · 수정 후 4/4 단계 성공
검증 환경 4항목
OSUbuntu 24.04.5
dnsmasq2.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)
수정 전 재현 · 예상된 실패 1건 재현됨수정 전: 서브도메인에 CNAME 레코드가 없다
[XFAIL] 등록되지 않은 www.example.test의 CNAME 조회 — 예상된 실패 재현됨 (/no-record-found/)
    > no-record-found
수정 후 확인 · 3/3 단계 성공수정 후: blog.example.test에 CNAME 레코드가 있다
[PASS] dig가 CNAME 값을 돌려줬다
[PASS] CNAME 값이 myuser.github.io.이다(저장소 이름 없음)
[PASS] CNAME을 따라 가면 A 레코드까지 풀린다
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • 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 명령을 쓴다.

참고 자료