[Support Guide] Conditional build/deploy behavior for context / branch on Netlify

Support Support Guides
,
1

Last reviewed by Netlify Support Staff: August 2023

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:

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 from your source code; our advice about builds does not apply to manual deploys via API, CLI, or drag and drop.

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?)

Contexts 1 and 2 exist for each build regardless of whether you manually set them. This document 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 doc for details) with the following settings:

[context.production.environment]
API_ENDPOINT = "https://production.yourservice.net"

[context.staging.environment]
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"
[context.branch-deploy.environment]
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 this 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 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!

But I don’t deploy via git

No problem! As long as we build your site - perhaps via a build hook - you can still use a conditional workflow. Build Hooks are always assigned to a branch, so you CAN still key off of context if you’d like. Or, you can key off of which hook filed, or what it sent! We expose the webhook’s title, URL, and body that is HTTP POSTed to our service via environment variables during build, as described in more detail in this documentation.

If you build your site locally, you can of course build something similar for your local use, but we’ll leave that workflow to you to create :wink:

1 Like