[Common Issue] Conditional build/deploy behavior


Ever wondered if there is a way to use conditional build settings based on context or branch name for deploys from git? How about deploys NOT from git?

TL;DR: Yes, for git based builds you have a lot of control! There are several ways to accomplish this on Netlify’s build network.

To start with let’s talk about how we differentiate build types and define some terminology:


All Netlify sites are deployed to our CDN and you can see a list of a site’s deployments on the Deploys page which is linked in the header of all the pages in the admin UI for your site. However, the advice I’ll give around changing build behavior applies only to builds. Builds by this definition are only created by Netlify’s build network and our based on your source code, rather than manual deploys via API, CLI, or drag and drop. For manual deploys, you need to configure things externally (generally, in our UI or in config files such as _headers and _redirects) as there is no configuration done at build time as described below.

Next it is important to understand that each build has a context . That context is intended to describe “what kind of build it is”. Typical values would be:

  1. production (for commits to, or builds from, your “main” branch that is published at the site URL such as yoursite.com or happy-scientist-12345.netlify.com)
  2. deploy-preview (for Pull Requests)
  3. branch-deploy (default for all non-production branches)
  4. some-specific-branch (you can set as many of these as you’d like. Perhaps staging?)

These contexts exist for each build - it will always fall in some bucket, even if you don’t create any special configuration. This article explains the situation in more detail.

Branch-specific behavior

So now that we’ve got our terms defined, let’s talk about how to accomplish the goal of “special builds for special circumstances”. You’d like your build for staging to use a staging API endpoint, and your build for production to use the production API endpoint. This is what deploy contexts were made for :slight_smile: . You set up a netlify.toml file (see this article in our documentation for details) with the following settings:

API_ENDPOINT = "https://production.yourservice.net"

API_ENDPOINT = "https://staging.yourservice.net"`

# no API server exists for other branches, but code will still want a URL here so need to set a "default"
API_ENDPOINT = "https://invalid"

You can also set a bunch of other things per context - build command, directory to start the build from, etc - check out the netlify.toml reference doc for all the possibilities.

Password protecting subsets of your content on a site

One frequently requested workflow is “password protect my non-production deploys”. You can learn how to create functional protection for their deploy previews in this article. Please be aware that this will apply to only future deploy previews based on your configuration. The only way to retroactively password protect deploys that didn't have this set is to password protect your entire site from the Access Control section of your Settings, but watch out - this affects the production branch too!

1 Like