GitHub Pages Custom Domain and HTTPS

This guide is for maintainers publishing project docs, static handbooks, or small sites from GitHub Pages under a custom hostname.

GitHub Pages has two configuration layers that are easy to conflate: account-level domain verification protects ownership, while repository Pages settings bind one hostname to one published site. The CNAME file is relevant only for some publishing sources, so it should not be treated as a universal fourth DNS record.

Verify ownership before pointing DNS

GitHub recommends verifying a custom domain before adding it to a repository. In personal or organization settings, the Pages domain-verification flow gives you a TXT record to publish. Once verified, repositories outside that account or organization cannot claim the verified domain or its immediate subdomains for their own Pages sites.

Verification matters during retirement as well as launch. A Pages site that is deleted, disabled, or detached while DNS still points at GitHub can create a takeover opportunity when the domain is not verified.

GitHub also warns against wildcard records such as *.example.com: account verification does not remove the takeover risk for every deeper hostname covered by a wildcard. Publish only the specific Pages hostnames you intend to maintain.

Bind the hostname to the repository

In the repository, open Settings → Pages, enter the exact custom domain, and save it before creating the serving DNS record.

Publishing source changes how GitHub handles the repository artifact:

• Publishing from a branch: saving the custom domain creates a CNAME file at the root of the source branch. If a local static-site build overwrites that branch, preserve or regenerate the file.
• Publishing with a custom GitHub Actions workflow: GitHub does not create a CNAME file, and an existing one is ignored and not required. The repository’s Pages setting remains the binding source.

This distinction prevents a common false diagnosis: a missing CNAME file is a problem for some branch-based workflows, but not for a custom Actions deployment.

Choose the GitHub Pages DNS shape

For docs.example.com, create a CNAME that points directly to the account’s Pages default domain, excluding any repository path:

Type: CNAME
Name: docs
Value: username.github.io

An organization site uses organization.github.io. Do not point the record at username.github.io/repository; DNS targets are hostnames, not URLs.

For an apex such as example.com, GitHub supports ALIAS or ANAME to the Pages default domain, or the current A and optional AAAA values listed in its official documentation. Check those live values before a change instead of preserving an old IP list in an internal runbook. The A record versus CNAME guide explains why the apex and subdomain instructions differ.

Verify the public chain

For a subdomain, confirm the CNAME points to the user or organization Pages host:

dig docs.example.com CNAME +short

Expected shape:

username.github.io.

If the result still shows a previous host, wait for the old TTL rather than adding a second CNAME. Use DNS propagation checks to distinguish the authoritative value from a recursive cache.

Illustrative verification record

Illustrative example using reserved example domains and IPs.

Enable and test HTTPS

After GitHub accepts the DNS configuration, Enforce HTTPS may remain unavailable while certificate provisioning completes. GitHub documents that the option can take up to 24 hours to appear.

curl -I https://docs.example.com

Healthy output should show a successful HTTP response over TLS:

HTTP/2 200
content-type: text/html; charset=utf-8

Test both the certificate and the content. A successful TLS handshake that returns the wrong repository, a GitHub 404, or an old generated site is not a completed migration.

GitHub-specific failure diagnosis

• Branch deployment loses its domain after each build: inspect whether the generated source branch removed GitHub’s CNAME file.
• Actions deployment has no CNAME file: that is expected; inspect repository Pages settings and workflow deployment status instead.
• DNS resolves but GitHub warns the domain is taken: complete account or organization TXT verification and check whether another repository still owns the binding.
• Apex works but www does not: configure both record shapes if both should resolve. GitHub can redirect between correctly configured apex and www variants based on the custom-domain setting.
• Pages was disabled but DNS remains: remove the GitHub-facing record immediately or restore a verified, actively maintained Pages binding.

Launch and retirement checklist

Before sharing the custom domain, confirm:

• the domain is verified at the correct personal or organization account
• repository Pages settings show the expected custom domain
• a branch-based source preserves its CNAME file, or a custom Actions workflow relies on the repository setting as documented
• public DNS returns the GitHub Pages target
• HTTPS is valid for the exact hostname
• internal links and canonical tags use the custom domain
• a future unpublish plan includes removing stale DNS

When retiring or moving the site, include the hostname in a broader public subdomain inventory and cleanup so an abandoned GitHub-facing DNS record does not outlive the repository.