[Support Guide] How to use Netlify’s branch deploy feature without Netlify DNS

Last checked by Netlify Support Team on Oct 20, 2022

So - you’ve discovered the concept of branch subdomains and want to use them! But you can’t use Netlify’s DNS Hosting? Never fear, there is a way to do this and this post will explain how in detail!

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!

1. Successfully Deploy the Branch to Netlify.

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.

2. Create the DNS record with your current DNS provider.

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:

  1. the subdomain must match the branch name (“slugified” as needed)
  2. 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 branch-name.example.com.

Here is an example scenario:

  • the custom domain is www.example.com
  • the branch name is branch-name
  • the branch should be served at https://branch-name.www.example.com/
  • 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 https://happy-scientist-123456.netlify.app/)

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 branch-name and happy-scientist-123456.
  • The record should be the type CNAME.
  • The branch name must match the sub-domain you want exactly. If your branch is called staging your sub-domain cannot be stage.www.example.com. It must be staging.www.example.com.

3. Confirm the new URL is working and, if so, contact support for SSL provisioning.

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

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

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.

4. Contact Netlify Technical Support to get the SSL certificate extended to the new sub-domain.

If the 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.

5. But wait, I use a custom SSL certificate!

This is both good and bad. The good news is, you can provision your own certificate to include whatever names you need! The bad news is, you will have to - we cannot add a second certificate to a site. So the workflow we describe about having us extend the certificate only works for customers who use Netlify’s automatically provisioned certificates, unfortunately. But on the upside, you already have an SSL provider who can probably sell you a certificate to include whatever names you want (perhaps *.yourdomain.com and *.*.yourdomain.com, to cover any branches you use in the future?)

If there are questions about this, please let us know.

Creating a subdomain using Netlify DNS
Adding new custom branch domain to SSL Certificate
How to set up a staging site
Subdomain SSL Extension for Branch Deploy
Certificate request
Branch Deploy SSL certificate extension
Branch Deploys & Branch Subdomains on Custom Domain - nslookup fails "server can't find..."
Could you activate the https on my staging domain?
Issue with staging subdomain propogating SSL
We need to enable *.sta91ng.freshping.io for https://app-freshping-staging.netlify.com
Using one domain per branch
Wildcard SSL certificate for subdomains (branch subdomains)
Set up SSL for my branch deploy please!
Official doc is wrong? I got a certificate working for a sub-domain automatically
Let's Encrypt certificate doesn't include branch subdomains after changing the primary domain
Is there a way to change the URL of deploy-preview?
Deploying site on branch without build command
Let's Encrypt certificate doesn't include branch subdomains after changing the primary domain
SSL on <branch>.<subdomain>.domain.dev
Extend SSL certificate to branch subdomain
Extend SSL certificate to branch subdomain - new
SSL Certs for custom subdomain
Preview Builds on Custom Domains
SSL certificate for branch deploy
Enabling branch deploys for a site that doesn't use netlify DNS
NetlifyDNS - branch subdomain cert error
Branch deploys not working when _not_ using Netlify DNS
Branch Deploy Periodically Failing [Likely Due to SSL Errors]
Custom subdomain not resolving on branch deploy
SSL Cert for branch deployment
Branch Subdomains not working correctly
Enable branch subdomains
SSL certificate for Branch subdomain - 2473e964.netlify.app
Provision SSL certification in anticipation of Netlify Transition
Can you deploy existing build to another site?
SSL Let's Encrypt subdomain issue
Branch Domain SSL for Akita Software Staging
Branch Domain SSL for Akita Software Staging
SSL certificate to include the new branch sub-domain for develop
SSL not deploying for branch subdomain
Certificate extension request
Request for SSL certificate for non-Netlify DNS branch deploy
Add subdomain to SSL Cert
How to generate my website
Multi tenant url sub domain
[Support Guide] How to detect and fix inactive Netlify DNS zones
SSL certificate for new branch subdomain
Branch Subdomain SSL/TLS certificate extension
[Support Guide] Compiled resources for custom domains on Netlify and DNS settings -- start here!
Request - Enabling SSL on Subdomains
Apply SSL to Branch deploy without Netlify DNS
Extend SSL to branch subdomains
Extend certificates to subdomains
[Support Guide] Tips & Tricks for browsing different deploys of the same site
Need SSL for branch deploy subdomain after changing the primary custom domain
Requesting SSL for branch deploy (non netlify DNS)
Branch deploy ssl / custom subdomain
Add SSL to the branch deploy
Add SSL to my branch deploy (mlbuddy.io)
Extend certificate for subdomains
Branch deploy custom domain SSL certificate
Include Subdomain in SSL Certificate
Can I have multiple domains pointing to different folders of my repo on netlify?
Include new branch sub-domain into SSL certificate
Adding ssl to branches subdomains
Provisioning SSL certificate for branch subdomain
Configuring branch subdomain names
Requesting SSL certificate for subdomain
Possile add same 404 error page for every subdomains?
Extend certificate for subdomain
Additional staging domain for certificate
Is it possible to use SSL certificates with branch deploys, without Netlify DNS, while on the free plan?
Branch feature SSL
Subdomain SSL Extension for Branch Deploy
SSL certificate extension to the new sub-domain
Branch subdomain configured via external DNS doesn't work
Netlify, Branches & Bitbucket
Subdomain SSL for branch deploy
Request to extend SSL to new sub-domain
404 Not Found error when accessing branch via CNAME
SSL certificate for branch deployment
SSL certificate change for branch deploy
Enable branch subdomains
I'm having issues deploying a branch to a subdomain
Let's Encrypt certificate doesn't include branch subdomains after changing the primary domain