GitHub allows to publish a website with static pages under either their own domain ( or with your own domain. They also provide HTTPS support, including generating automatically an SSL certificate from Lets Encrypt.


Setup DNS records

GitHub provides the website under

subdomain CNAME

Protect the subdomain with a SPF record

subdomain TXT v=spf1 -all

If the site is the primary one www, also set the domain

domain CNAME

this is not allowed according to the DNS RFS but many DNS hosting will expand or flatten into the A and AAAA records.

if not, add them manually

host -t A has address has address has address has address bruno$ host -t AAAA has IPv6 address 2606:50c0:8001::153 has IPv6 address 2606:50c0:8000::153 has IPv6 address 2606:50c0:8002::153 has IPv6 address 2606:50c0:8003::153

Add a CAA record so GitHub and LetsEncrypt can generate a SSL certificate

subdomain CAA 0 issue

also add one to the root domain

domain CAA 0 issuewild

If using CloudFlare, set the CNAME (or A + AAAA) records to NOT be proxied for now

Setup GitHub repository

create a new repository

create a default and set it to something welcoming to other people, also adding the domain so it can easily distinguishable from other repositories

echo '# mydomain' >

create a new branch docs so the website updates do not pollute the home of the repository on GitHub

create a folder docs

add a file CNAME with the domain name

echo > docs/CNAME

don't add all content yet. add a dummy index inside for testing

echo "Hello World" > docs/index.html

commit and push the docs branch

Setup GitHub Pages

Go to GitHub, "Repository", "Settings", "Pages"

On "Build and deployment" ensure "Deploy from a branch"

Set the branch to docs and the folder to /docs and click Save

The "Custom domain" field should be pre-populated already, from the docs/CNAME file that was committed.

GitHub should report "DNS check successful".

If not… FIXME

Enable "Enforce HTTPS"

If the option is not available:

  • ensure the CAA records are set up correctly

$ host -t CAA has CAA record 0 issue ""
$ host -t CAA has CAA record 0 issue "; cansignhttpexchanges=yes" has CAA record 0 issuewild "" has CAA record 0 issuewild "; cansignhttpexchanges=yes" has CAA record 0 issuewild "" has CAA record 0 issuewild "; cansignhttpexchanges=yes" has CAA record 0 issue "" has CAA record 0 issue "; cansignhttpexchanges=yes" has CAA record 0 issue ""
  • ensure CloudFlare proxy is disable, so GitHub can see the original CNAME (A / AAAA) record pointing to and not to CloudFlare

Enable Website

the page will only be deployed upon updates on the branch

change the index.html or add more content, commit and push

go to GitHub repository, Actions, and check if the "pages build and deployment" ran and was successful

on your browser visit your domain and verify the content is correct

try loading the site as http and ensure it gets redirected to https

for the root domain with www, also check if the domain redirects to www.domain, with and without https

Customized Action

to customize the action e.g. to run some code that auto-generates files into docs, see GitHub Pages with Custom Action

a custom action is also required in case there's dot files under docs, as the default action will not pick them up. This is required e.g. for MTA-STS that needs a .well.known/mta-sts.txt