How do you put a GitHub Pages site on a custom apex domain with HTTPS, and what DNS records and safeguards does that involve?

## The DNS half A custom domain on Pages is two independent configurations that must agree: DNS pointing at GitHub, and GitHub knowing which repository that hostname belongs to. Either one alone gives you a broken site. **Subdomain (`www.example.com`, `docs.example.com`).** One `CNAME` record pointing at `<owner>.github.io`. The target is the *account* host, not `<owner>.github.io/<repo>` — a CNAME's right-hand side is a hostname and cannot carry a path. GitHub resolves which repository to serve from the domain configured in that repository's settings. **Apex (`example.com`).** DNS forbids a CNAME at the zone apex, because the apex must also hold `SOA` and `NS` records. Two legal options: - `A` records to GitHub's published Pages addresses, plus `AAAA` records to their IPv6 counterparts. GitHub documents the exact set; take the values from the current Pages documentation rather than from memory or an old blog post, since the anycast set has changed before. - An `ALIAS`, `ANAME` or "CNAME flattening" record to `<owner>.github.io`, if your DNS provider offers one. This is usually the better choice: the provider resolves the target for you, so an address change on GitHub's side never requires an edit to your zone. A reasonable production layout is the apex handled by A/AAAA or ALIAS and `www` as a CNAME, with GitHub configured for one of them — it redirects between the two forms automatically. ## The GitHub half Enter the hostname in **Settings → Pages → Custom domain**. With a branch publishing source, saving that writes a file literally named `CNAME` — containing just the hostname — to the root of the publishing source. That file is the durable record of the setting, and it is the thing that breaks: any deploy that replaces the branch wholesale (a force-pushed `dist/` directory, a generator that cleans the branch) removes it, and the custom domain silently reverts. Fix it in the build, by emitting the `CNAME` file into the output directory, not by re-typing the domain after every deploy. GitHub then runs a DNS check. Until it passes, the site is not served on the custom name, and the settings panel says why — the error messages distinguish "not pointed at Pages" from "pointed at Pages but claimed elsewhere". ## HTTPS Once DNS resolves correctly, GitHub requests a certificate from **Let's Encrypt** on your behalf, with no action from you. Provisioning is not instant — it can take up to roughly 24 hours — and until it completes, the **Enforce HTTPS** checkbox is unavailable. Enabling it makes Pages redirect plain HTTP to HTTPS; leaving it off means the site is reachable over unencrypted HTTP, which is a finding in any review. Renewal is automatic thereafter. The usual reasons provisioning fails are worth knowing: the record still points somewhere else or a stale record lingers; the domain sits behind a proxying CDN in full-proxy mode so the ACME challenge never reaches GitHub; or a `CAA` record on the zone forbids Let's Encrypt from issuing. Changing the custom domain resets the process, so removing and re-adding it is the standard way to force a fresh attempt after fixing DNS. ## The safeguard people forget: domain takeover This is the part that turns the question from configuration into judgment. If `docs.example.com` points at `<owner>.github.io` but no repository in your account currently claims that hostname, someone else can create a repository, set that domain, and serve their content on your name — a classic dangling-DNS takeover. It is a real, exploited class of bug, and it fires exactly when a team archives or deletes a docs repository without cleaning up DNS. The defence is **domain verification**: in your user or organization settings, add the `_github-pages-challenge-<owner>` TXT record that GitHub gives you. Once verified, only repositories inside that account may serve Pages on the domain and its subdomains. The operational rule that goes with it is simple — when you retire a Pages site, remove the DNS record in the same change that removes the repository, and never leave a record pointing at a host you no longer claim. ## What HTTPS on Pages does not give you You get a valid certificate and a redirect. You do not get control over response headers: no custom `Content-Security-Policy`, `Strict-Transport-Security`, or cache-control tuning, because there is no server configuration surface. If your threat model or compliance requirement needs specific headers, Pages is the wrong host and a CDN or static host with edge configuration is the right one.