Last checked by Netlify Support Team on September 19, 2021
Please note, however, that going this route means missing out on single click setup and all the goodness it includes - for example, getting an SSL certificate configured automatically. If you are okay with this downside, or simply cannot use Nelify DNS for some reason, here’s how to do it!
First, please make certain the branch has deployed successfully - meaning both the build and deploy must happen successfully, on Netlify.
If branch deploys are disabled or if the build/deploy processes are failing, then please resolve those issues before proceeding. If you run into any issues the following documentation may be helpful:
You might ask: Why do I need to deploy before configuring DNS in step two?
The answer is that the branch DNS record needs to exist with us here at Netlify first. This is simply because it will need to be entered with the third-party DNS provider in step two.
Next, you’ll need to create a DNS record at your DNS provider pointing to the branch DNS record at Netlify.
There are two important considerations:
- the subdomain must match the branch name (“slugified” as needed)
- the subdomain will be under the primary custom domain
This second point means that if your primary custom domain is
www.example.com then the subdomain will be
branch-name.www.example.com and not
Here is an example scenario:
- the custom domain is
- the branch name is
- the branch should be served at
- the TTL value (time to live value - more below) will be 3600 seconds which is one hour
- the sub-domain at Netlify is
happy-scientist-123456(meaning the Netlify URL for the master branch is
With the values above defined for this example, the DNS record you create would look like so:
branch-name.www 3600 IN CNAME branch-name--happy-scientist-123456.netlify.app.
The format above is required and no other naming conventions will work. The key points for the DNS record are:
- There should be two dashes between
- The record should be the type
- The branch name must match the sub-domain you want exactly. If your branch is called
stagingyour sub-domain cannot be
stage.www.example.com. It must be
Yay! We’re done. Well, almost.
I did mention something before about missing out on “getting an SSL certificate configured automatically”.
Not to worry. Our technical support will be able to assist with that, but, before support can provision an updated SSL certificate, we need to confirm the domain name is working. (If it isn’t working the provisioning will fail so this must be completed first.)
So, how do you test if the DNS record is working correctly?
Well, if you are comfortable working in a terminal (aka, command line, shell, etc) the
nslookup command (or
dig) can confirm the DNS record is working correctly. Using this imaginary example above (with the branch server at
branch-name.www.example.com), the output of
nslookup would look similar to this:
$ nslookup branch-name.www.example.com Server: 126.96.36.199 Address: 188.8.131.52#53 Non-authoritative answer: branch-name.www.example.com canonical name = branch-name--happy-scientist-123456.netlify.com. Name: branch-name--happy-scientist-123456.netlify.com Address: 184.108.40.206
Wonderful! We needed to confirm that
branch-name.www.example.com points to
branch-name--happy-scientist-123456.netlify.com and it does!
And remember that pesky TTL (time to live) value I mentioned previously? Here is why it matters.
DNS is recursive, meaning that if one DNS server doesn’t know an answer it asks others in a hierarchy. To prevent heavy traffic on the DNS servers at the top of the hierarchy caching is used. Instead of asking for the same DNS record over and over each time you visit the same domain name, both web browsers and intermediary DNS servers will cache the value for a certain time - the TTL value. The TTL value is the time (in seconds) that the record can/should be cached.
This matters because, if you are changing an existing record for domain (or, like me, you sometimes make a mistake when configuring your DNS records), we must wait for the old/incorrect DNS record to timeout before the new one will take effect.
On the other hand, if this is a new DNS record (meaning it is a newly added sub-domain which didn’t already exist) the TTL value won’t affect anything. This is because a new record, by definition, isn’t cached anywhere.
nslookup test above succeeded, then the last step is to please contact our Technical Support team asking for the the SSL certificate to include the new branch sub-domain. You can do this by making a new topic in the forums #Netlify-support category (or if you have a Pro plan or above, using our support form.)
This is the reason we ask you to confirm the new DNS record is pointing to the branch in step three. We cannot extend an SSL certificate to cover the new sub-domain until there is a DNS record pointing to Netlify.
Once the DNS record is configured, we will be happy to extend the SSL certificate to include the newly added branch sub-domain.
If there are questions about this, please let us know.