How To Password Protect Your Staging Site on Netlify

Disclaimer up front, the method described in this post only works with the paid Netlify plans

Short Version

You can password protect branch deploys on Netlify using a "branchdeploy" header file.

1. Create a file named _branchdeploy_headers with the following content:

   /* Basic-Auth: username:password123

   Obviously, uhh, you'd want to use a better username and password than that 🙃

2. Create/update your netlify.toml file to copy and rename the header file to _headers on branch-deploys only:

   [build]
   base    = "."
   command = "npm install && npm run build:prod"
   publish = "dist"
   
   [context.branch-deploy]
   command = "npm install && npm run build:prod && cp _branchdeploy_headers dist/_headers"
   

Now your staging site and any other branch deploys are password protected while prod is still open to the world! 🎉🎉🎉

Long Version

I'm a huge fan of hosting static websites and PWAs on Netlify. I love the simplicity of it... just link netlify to your github repo and every push to master automatically deploys your site.

One of my favorite features is custom subdomains per branch. On almost all of my sites I have a staging branch that gets deployed to a "staging" subdomain. For example, the staging branch of Background Noise points to staging.backgroundnoise.app.

The problems with a "staging" subdomain

There are 2 problems with having a staging site at a subdomain like that. First, you might not want just anybody perusing around your staging site - seeing what features you are working on and using features that aren't ready. Second, your main (production) site might get penalized in search results because you've got duplicate content on your staging site (unless your staging site is just completely different than your prod site, but that's probably not too often the case).

For the first problem you could choose a more obscure subdomain, but that's security through obscurity and that ain't it. For the second problem you could mess around with robot.txt files... but that doesn't sound fun to me.

No, the ideal fix for both problems is to throw a simple password on your staging site. Lookie-lou's can't see what cool stuff you've got coming and search engines won't crawl your non-prod site.

Netlify authentication to the rescue

Currently Netlify authentication is only part of the Pro plan

Netlify's Pro plan has a site-wide password feature... but that's not exactly what we want since it applies a password to all domains (even the prod/main deploy). The feature we will use is Netlify's basic auth headers. We'll make a header file to password protect all files of a given deploy, but we'll only use it on non-prod deploys ("branch deploys").

1. Create a file named _branchdeploy_headers with the following content:

   /* Basic-Auth: username:password123

   Obviously, uhh, you'd want to use a better username and password than that 🙃

2. Create/update your netlify.toml file to copy and rename the header file to _headers on branch-deploys only:

   [build]
   base    = "."
   command = "npm install && npm run build:prod"
   publish = "dist"
   
   [context.branch-deploy]
   command = "npm install && npm run build:prod && cp _branchdeploy_headers dist/_headers"
   

Now your staging site and any other branch deploys are password protected while prod is still open to the world! 🎉🎉🎉