With continuous deployment, Netlify attempts to ignore builds when they’re not required, only building when your site requires it.
Depending on your Branches settings, any time there is a change in a linked repository, Netlify tries to determine whether there are changes in the site’s base directory by comparing the last known version of the files in that directory. If no change is detected, the build system cancels and essentially skips the build, returning early from the build process.
To override the default behavior described above, you can use the
ignore attribute in the Netlify configuration file. This setting allows you to specify a Node.js or Bash command that runs from the base directory and determines whether or not the site needs rebuilding.
ignore command provides custom, programmatic control over builds. It can prevent bot-triggered builds, for example, or limit production deploys to certain days of the week. It can also account for times when you may still want to run a build when there’s a change outside of a base directory, for example, if there’s a change to
package.json in the root directory.
Things to note when constructing an
- An exit code of
1indicates the contents have changed and the build process continues as usual. An exit code of
0indicates that there are no changes and the build should stop.
- The command is run with Bash. You can also use Node.js.
- If the command references a separate file, the file path must start with
ignorecommand won’t cancel a build triggered by a build hook, regardless of exit code.
- Netlify can run an
ignorecommand even if a base directory isn’t set.
- All paths in your
ignorecommand should be absolute paths relative to the base directory, which is the root by default (
Want to customize the default ignore behavior? Check out the examples of custom
ignore commands below. For more
ignore examples, head over to our verified Support Guide on using the
# Mimic default behavior
The Bash example below is an
ignore command that roughly approximates the default ignore builds behavior. You can add to or adjust it to update the default check. The commands use read-only environment variables for Git metadata as well as the
NETLIFY build environment variables.
[build] ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF"
For this next example, consider a monorepo project set up like this, where
packages/blog-1 is the package directory and the base directory is the repository root (
/), by default.
/ ├─ package.json └─ packages/ ├─ blog-1/ │ ├─ package.json │ └─ netlify.toml ├─ common/ │ └─ package.json └─ blog-2/ ├─ package.json └─ netlify.toml
ignore command example adapts the default behavior so that the build proceeds only if there are changes within the
[build] ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF packages/blog-1 packages/common"
# Skip builds based on branch name
ignore command has access to a Node.js environment. This means if you want to prevent builds based on logic that’s hard to handle in Bash, you can use Node.js.
This example skips builds for a specific branch by adding a Node.js script to the
ignore command in
[build] ignore = "node ignore_build.js"
ignore_build.js executes before any build logs run. If the branch name is
debug, the exit code is set to
0, which stops the build.
// ignore_build.js process.exitCode = process.env.BRANCH.includes("debug") ? 0 : 1
There are a few things you should keep in mind when using Node.js with an
- Node.js dependencies from the site’s
package.jsonare not available.
ignorecommands use Node.js 18. This Node.js version can’t be customized. This means if your site has a custom Node.js version, the custom version is not used in the
# More build configuration resources
Did you find this doc useful?
Your feedback helps us improve our docs.