News & Announcements

How to set a custom domain for Deploy Previews

News & Announcements

How to set a custom domain for Deploy Previews

Project domain customization just got more flexible on Netlify — you can now set a custom domain for Deploy Previews and/or branch deploys, and we’ll automatically create context-based subdomains for you!

Hovering over a Deploy Preview link on the Netlify UI shows a custom URL in place of the netlify.app URL

The Netlify UI now links to your customized Deploy Preview URLs

Teams on Pro plans and above can set up deploy subdomains under Site Settings > Domain Management > Automatic deploy subdomains. These settings are available to try as a Labs beta today, and will be generally available soon.

Why use custom domains for deploys?

By default, Netlify generates a Deploy Preview for each pull/merge request against your production branch and any deployed branches. Deploy Previews enable your cross-functional team to preview and collaborate on changes before they go live.

Third-party integration enablement

Some teams aren’t able to take full advantage of Deploy Previews because they have third-party integrations that can only run on allow-listed domains. By enabling Deploy Previews to use your custom domain, you'll be able to safely include it in the allowed-domain list of any third party scripts and services where necessary. This makes third-party services available in your branches and previews, just as they would be in production.

Brand safety and security

Custom subdomains for your deploys also help to ensure better brand safety—Deploy Previews or deployed branches will now appear to come from “inside the house”, putting both stakeholders and external customers at ease. This also makes it easier for security and IT teams to build policies around company-controlled domains, helping to remove the friction between productivity and security.

How to set up custom domains for deploys

At Site Settings > Domain Management > Automatic deploy subdomains:

Deploy Previews and branch deploys are set to use netlify.app URLs by default

  1. Select “Edit custom domains”.
  2. Check “Add custom domain” next to each deploy context you want to customize.
  3. Select any domain from the “Domain” field. This list includes any (sub)domains you have delegated to Netlify DNS; you can add more at Team Overview > Domains.
  4. Add an optional prefix in the “Additional subdomain” field. You can have deploys available at *.internal.yourcompany.com instead of *.yourcompany.com. There is no need to set up any additional DNS records for this.

Both Deploy Previews and branch deploys can take a domain (selected from a dropdown) and an optional, additional subdomain prefix
5. Press “Save”.

That’s it!

Deploy Previews and branch deploys are each set to use a custom subdomain

Netlify will automatically generate wildcard DNS records and SSL certificates for each Deploy Preview (deploy-preview–123.internal.yourcompany.com) and deployed branch (branch-name.internal.yourcompany.com). We will use these URLs on the Netlify UI, in the Netlify API, and in deploy notifications:

Hovering over a Deploy Preview link on the Netlify UI shows a custom URL in place of the netlify.app URL

Netlify DNS is required for this feature, but your deploys’ custom subdomains do not need to match production. Can’t delegate an apex domain to Netlify DNS? Try a subdomain!

Differences to branch subdomains

The branch subdomains feature is still available to all teams under Site Settings > Domain Management. Unlike automatic deploy subdomains, this feature requires manually configuring each custom subdomain before it is applied to a deployed branch. The only domain available here is your site’s primary domain:

Editing the branch subdomains card shows only an option to select a branch from a list. The subdomain is created from the primary domain for you.

Developers may find they prefer this approach for some projects! The branch subdomains feature is useful if you want to tightly control new branch subdomains, instead of letting Netlify create these automatically.

Interactions with branch subdomains

If you enable automatic deploy subdomains for branch deploys on your site, the “Branch subdomains” feature will be disabled on that site:

The branch subdomains card is disabled when you have automatic deploy subdomains on for branch deploys

We will continue to serve any branch subdomains you previously configured, in addition to the new automatic subdomains.

Try it out today!

We hope that automatic deploy subdomains enable your team to better control your preview environments. You can check out the docs to learn more.

Please try it out today under Site Settings > Domain Management and let us know what you think on this short survey or on the forums!

Not already a Netlify customer? Sign up for a free Pro trial to get access to automatic deploy subdomains and more features.

Keep reading

Recent posts

Book cover with the title Deliver web project 10 times faster with Jamstack enterprise

Deliver web projects 10× faster

Get the whitepaper