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 Deploy contexts 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. This ignore builds behavior is available for sites linked to a Git repo after October 3rd, 2019.

Sites created before October 3rd, 2019

If you would like to use the ignore builds feature for a site created before October 3rd, 2019, you’ll need to re-link your repository to make this feature available. For your selected site, go to Site settings > Build & deploy > Build settings, select Link to a different repository, and then select the same repository to re-link your site to it.

# Custom ignore command

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 Bash command that runs from the base directory and determines whether or not the site needs rebuilding.

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 1 indicates the contents have changed, so if your command returns 1 the build process continues as usual. An exit code of 0 indicates that the build should return early.
  • The command is run with Bash.
  • If the command references a separate file, the path must start with ./.
  • Regardless of exit code, the ignore command won’t cancel a build if the build is triggered by a build hook.
  • Netlify can run an ignore command even if a base directory isn’t set.

# ignore examples

Here’s an example of an ignore command that’s a rough approximation of the default ignore builds behavior. You can add to or adjust it to update the default check. The command uses read-only environment variables for Git metadata.

  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF"

For a custom ignore command example, consider a monorepo project setup like this, where blog-1 is the base directory.

├─ package.json
└─ workspaces/
   ├─ blog-1/
   │  ├─ package.json
   │  └─ netlify.toml
   ├─ common/
   │  └─ package.json
   └─ blog-2/
      ├─ package.json
      └─ netlify.toml   

The following ignore command adapts the default behavior so that the build proceeds if there are changes within blog-1 or within the common directory.

  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../common/"

For additional ignore examples, check out our verified Support Guide for guidance on using the ignore command.