Set up MTA-STS on a GSuite hosted GitHub pages

Subscribe to my newsletter and never miss my upcoming articles

To further protect my email communication, I have enabled MTA-STS on my GSuite domain. My site is hosted on GitHub pages, so I'll walk you through my setup.

It starts with creating a new GitHub repository that will hold the files for the MTA-STS subdomain. For some reason, the config for the MTA-STS is read from an mta-sts.txt file, located in the .well-known folder, but it has to be loaded from the mta-sts subdomain. Why it can't be done from the main domain is beyond me, but here we are.

Now that I have a repository, I create the .well-known folder and I place the mta-sts.txt file inside that folder. The content of the file can be found in my GSuite Admin section. It is the middle value: MTA-STS Policy Diagnostic. I'll come back to the other values shortly.

Unfortunately, this is where I bumped into the problem with hosting on GitHub pages. By default, it does not expose folders starting with a . (dot). Probably because the servers are Linux based and any Linux folder starting with a dot, is automatically a hidden folder. So Stack Overflow to the rescue!

The fix is as easy as adding a _config.yml file to the base repository with the single line:

include: [".well-known"]

Important detail: do not end with an empty line! Just add that single line to the file to expose the .well-known folder.

The last step in GitHub is to set up the custom domain for this repository. It's pretty easy to set up a GitHub pages domain, just be sure to include the subdomain before your domain.

Don't worry if GitHub displays an error, I have not set up the subdomain DNS yet, so it can't find the setup for the domain just yet.

I'll fix that right now. I let Cloudflare handle my DNS settings. In the DNS settings of the dashboard, I add 4 A records with the name of mta-sts, one for each IP-address that GitHub pages can handle. For more information about the specific setup of GitHub pages, I refer to their good documentation. Now that the IP redirects are set up, the subdomain should be ready and available.

Two more steps and I'm done. Luckily for me, they are both in my DNS setup. I add a TXT record with the name _mta-sts and the value found in my GSuite Dashboard after "MTA-STS TXT Record Diagnostic". I add another TXT record with the name _smtp._tls and the value found in my GSuite Dashboard after "Reporting Policy Diagnostic".

Do not forget to change the rua=mailto: value of the "Reporting Policy Diagnostic" text to an email address which you can receive. That is where reports will be sent to. In the near future, Report URI should get support to process the values.

Now I enjoy more secure email communication. If anybody wants to learn more about SMTP MTA Strict Transport Security, I recommend reading Scott Helme's very good blog post or URI Ports expanded blog post. That's where I learned about it.

Edit: Thanks Faisal from for pointing out a typo. Cheers mate!

No Comments Yet