[Support Guide] How to use the ignore command

The ignore command is a powerful way for you to control whether or not builds run based on variables of your choosing. Here’s how it works: you can set ignore in your netlify.toml to any Bash command or Bash script. If your ignore command or script exits 0, the build is canceled. If the command or script exits with 1 or any other exit code, the build continues.

We created this feature for monorepo support, but it is useful in other contexts too, like choosing whether to deploy based on the branch name. Below are a handful of examples that cover some of the use cases we see most frequently. They make use of some of our built-in environment variables like:

  • $CACHED_COMMIT_REF
  • $COMMIT_REF
  • $REVIEW_ID

They also use custom environment variables you might create like $GITHUB_PAT.


Example 1: Simple way to ignore all builds

[build]
  ignore = "exit 0"

Example 2: Ignore builds of PRs from tools-netlify bot on netlify/build-image repo

[build]
   ignore = "curl https://api.github.com/repos/netlify/build-image/pulls/$REVIEW_ID | grep '\"login\": \"tools-netlify\"'"

Example 3: Ignore builds of PRs on a private repo by calling the GitHub API with a token

[build]
   ignore = "curl -H \"Authorization: token $GITHUB_PAT\" --request GET curl https://api.github.com/repos/:owner/:repo/commits/:sha/status | grep '...'"

Example 4: Use a bash script to ignore all builds on branch never-build

[build]
 ...

[context.branch-deploy]
  ignore = "bash ./build-ignore.sh"

where build-ignore.sh is:

#!/bin/bash

if [[ $BRANCH == "never-build" ]]
then
  exit 0
else
  exit 1
fi

Example 5: Same result as above, but using our branch context and no Bash script

[build]
 ...

[context.never-build]
  ignore = "exit 0"

Our default ignore command for monorepo projects

[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF ."

Example 6: Customize our default ignore command to check for changes in dirA/ and dirB/ instead of just current root directory

[build]
  ignore = "git diff --quiet $COMMIT_REF $CACHED_COMMIT_REF -- dirA/ dirB/"

If you have questions about your ignore command or have a successful example to share, please create a thread and we’ll take a look!

3 Likes