Ignore builds
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.
# Custom ignore command
The 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 ignore command:
- An exit code of
1indicates the contents have changed and the build process continues as usual. An exit code of0indicates 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
./. - The
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 (/).
# ignore examples
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 ignore command.
# 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 CI and 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
The following ignore command example adapts the default behavior so that the build proceeds only if there are changes within the blog-1 or common directories.
[build]
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF packages/blog-1 packages/common"
# Skip builds based on branch name
The 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 netlify.toml.
[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 ignore command.
- 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 theignorecommand.
# More build configuration resources
Did you find this doc useful?
Your feedback helps us improve our docs.