Branch deploys let you preview changes for specific branches before merging them into your main production branch.
Here’s a Netlify site configured for branch deploys, showing how different branches can have their own settings:
# netlify.toml
[build]
command = "npm run build"
publish = "build"
[branch]
# Default settings for all branches not explicitly configured
environment = { MY_GLOBAL_VAR = "default_value" }
[branch.production]
# Settings specific to the 'main' branch (or whatever your production branch is)
# This branch will deploy to your primary Netlify site URL.
environment = { MY_BRANCH_VAR = "production_value", MY_GLOBAL_VAR = "production_override" }
[branch.staging]
# Settings specific to the 'staging' branch
# This branch might deploy to a subdomain like staging.your-site.netlify.app
environment = { MY_BRANCH_VAR = "staging_value", NODE_ENV = "staging" }
[branch.develop]
# Settings specific to the 'develop' branch
environment = { MY_BRANCH_VAR = "develop_value", DEBUG = "true" }
# You can even override build settings per branch
[branch.develop.build]
command = "npm run build:develop"
publish = "dist/develop"
This netlify.toml file defines build settings for a Netlify project. The [build] section specifies the general build command and publish directory. The [branch] section provides a way to configure settings that vary depending on the Git branch being deployed.
The [branch.production] block targets your main production branch (commonly main or master). Here, we’re setting branch-specific environment variables MY_BRANCH_VAR to "production_value" and overriding MY_GLOBAL_VAR to "production_override". These settings are applied only when deploying the production branch.
The [branch.staging] block is for a staging branch. It sets MY_BRANCH_VAR to "staging_value" and NODE_ENV to "staging". This allows you to test features in a production-like environment before merging to main.
The [branch.develop] block customizes settings for a develop branch. It sets MY_BRANCH_VAR to "develop_value" and enables DEBUG mode. Crucially, it also overrides the build command and publish directory specifically for this branch, demonstrating how deeply you can customize.
When Netlify builds your site, it checks for a netlify.toml file in your repository. If it finds one, it uses the configuration defined there. For branch deploys, Netlify intelligently applies the settings for the specific branch being deployed. If a branch has a dedicated [branch.<branch-name>] section, those settings take precedence. If not, it falls back to the general [branch] settings. If a specific setting (like command or publish) is defined within a branch’s section, it overrides the global [build] setting for that branch.
The most surprising thing about Netlify’s branch deploys is that they aren’t just for previewing; they can fundamentally alter the output of your build based on the branch. You can have different build commands, publish directories, and environment variables, effectively creating distinct versions of your site for each branch without needing separate Netlify sites. This means your develop branch could build to a dist/develop folder and run a different command, while your main branch builds to a build folder and runs the standard command, all within the same Netlify project.
The real power comes from combining these branch-specific settings with Netlify’s feature flags or environment-specific configurations within your application code. For instance, your staging branch might have API_URL="https://api.staging.example.com" while your production branch has API_URL="https://api.example.com". Your frontend code can then read process.env.API_URL and automatically connect to the correct backend.
You’ll soon want to explore how to manage these branch-specific configurations for secrets and sensitive environment variables.