Netlify’s deploy contexts are how you tell it which part of your code to deploy for which trigger, and the real magic is how granular you can get with them.
Let’s see this in action with a typical workflow. Imagine you’ve got a site deployed on Netlify.
# This is a simplified representation of a Netlify build command
netlify deploy --dir=dist --prod
Your netlify.toml file is the control center for this. It looks something like this:
[build]
command = "npm run build"
publish = "dist"
[context.production]
command = "npm run build:prod"
environment = { NODE_ENV = "production", API_URL = "https://api.example.com" }
[context.deploy-preview]
command = "npm run build:preview"
environment = { NODE_ENV = "production", API_ENV = "preview" }
[context.branch-deploy]
command = "npm run build:staging"
environment = { NODE_ENV = "staging", API_URL = "https://staging-api.example.com" }
Here’s what’s happening under the hood. When you push to your main or master branch, Netlify sees the [context.production] section. It runs the npm run build:prod command, sets NODE_ENV to production, and crucially, uses https://api.example.com for your API calls. This is your live, production environment.
When you open a Pull Request (PR) against main, Netlify creates a "deploy preview." It drops into the [context.deploy-preview] block. Notice the command is different: npm run build:preview. The environment variables are also tailored, with API_ENV set to preview. This lets you test changes in an environment that mirrors production but doesn’t affect your live site.
Now, let’s say you have a develop branch. You can configure a specific deploy context for it using [context.branch-deploy]. In the netlify.toml above, we’ve set branch = "develop" implicitly by naming the context branch-deploy and assuming that’s what you’d want for a non-production branch. It runs npm run build:staging, and your API endpoint is pointed to https://staging-api.example.com. This is perfect for staging your development work before merging it into main.
The mental model is about mapping triggers (branch pushes, PRs) to specific build configurations. Netlify uses the context name to match these triggers. The default context is production. If you push to a branch that isn’t explicitly configured, it falls back to production. For PRs, it always uses deploy-preview unless you specify otherwise. For specific branches, you can use [context.branch-deploy.HEAD] where HEAD is the branch name, like [context.branch-deploy.develop].
The command and publish directives within a context override the top-level [build] settings. This means you can have a generic build command for all contexts, but then specialized commands for production, staging, or previews. The environment key is where you inject secrets, API keys, or configuration flags that change based on the deploy context. These are exposed as environment variables to your build process.
Here’s the crucial part most people miss: context names are highly flexible. While production, deploy-preview, and branch-deploy are common, you can create custom context names. For instance, you might have [context.feature-branch-xyz] for a specific experimental branch. Netlify will automatically apply this context if a deploy is triggered by a branch named feature-branch-xyz. You can also explicitly define contexts for specific branches like this:
[context.develop]
command = "npm run build:dev"
environment = { NODE_ENV = "development" }
[context.staging]
command = "npm run build:staging"
environment = { NODE_ENV = "staging", API_URL = "https://staging-api.example.com" }
[[redirects]]
from = "/api/*"
to = "/.netlify/functions/:splat"
status = 200
[[redirects]]
from = "/staging-api/*"
to = "/.netlify/functions/:splat"
status = 200
conditions = ["GATSBY_ENV=staging"] # Example of context-specific redirects
In this extended example, [context.develop] and [context.staging] are now explicitly named contexts that Netlify will use when deploying from branches named develop and staging, respectively. The conditions array in redirects is another powerful, albeit less commonly used, feature that allows you to conditionally apply redirects based on environment variables set by a deploy context.
Understanding deploy contexts is key to managing complex sites with multiple environments and testing workflows. The next step is integrating serverless functions with these contexts.