How do I use the "Ignored Build Step" field on Vercel?

You can enable the "Ignored Build Step" field by referring to the documentation of this feature. If the command returns "0", the build will be skipped. If, however, a code "1" or greater is returned, then a new deployment will be built.

One of the most important aspects of this feature is to understand how Vercel clones your code. The platform performs a "shallow clone" with the command git clone --depth=10 (...), to fetch ten levels of git commit history.

With a Script

To run a bash script in the "Ignored Build Step", you need to set the following in the field: bash script.sh. Do notice the file should exist in your repository. An example of a bash script:

#!/bin/bash

echo "VERCEL_ENV: $VERCEL_ENV"

if [[ "$VERCEL_ENV" == "production" ]] ; then
  # Proceed with the build
  echo "✅ - Build can proceed"
  exit 1;

else
  # Don't build
  echo "🛑 - Build cancelled"
  exit 0;
fi

An example Ignored Build Step command where only commits made to the production environment are allowed to be deployed. The environment variable "VERCEL_ENV" should be added to your project.

By using this command, Vercel will only build deployments when the value of "VERCEL_ENV" is "production". That variables was added to the Environment Variables UI which makes it available for the project.

With Environment Variables

You can use this command with System Environment Variables. Do notice a script is required since calling environment variables in the field directly is not supported. An example can be a script that only builds certain branches:

#!/bin/bash

echo "VERCEL_GIT_COMMIT_REF: $VERCEL_GIT_COMMIT_REF"

if [[ "$VERCEL_GIT_COMMIT_REF" == "staging" || "$VERCEL_GIT_COMMIT_REF" == "main"  ]] ; then
  # Proceed with the build
    echo "✅ - Build can proceed"
  exit 1;

else
  # Don't build
  echo "🛑 - Build cancelled"
  exit 0;
fi

An example Ignored Build Step command where only commits made from the branches "main" and "staging" are allowed to be deployed.

With Folders and Workspaces

Before you proceed, keep in mind the Ignored Build Step runs in the same folder your selected "Root Directory". Therefore, you may need to adjust it slightly so it can fit your needs. To build a new deployment considering only a certain folder, you can use the following command:

git diff HEAD^ HEAD --quiet ./packages/frontend/

An example of "Ignored Build Step" command. If changes were commited to "./packages/frontend/", the command will yield a non-empty response, allowing the build to proceed.

By using this command, Vercel will only build deployments when changes are made inside of the packages/frontend/ directory. If the folder ./packages/frontend/ is your selected "Root Directory", then you can use:

git diff HEAD^ HEAD --quiet .

An example of "Ignored Build Step" command. If changes were commited to ".", the command will yield a non-empty response, allowing the build to proceed.

You can also access other folders in your deployment to check for changes. If you are building your frontend with packages/web selected as your "Root Directory", and your app must be deployed only when changes to ../../packages/docs are made, you can use:

git diff HEAD^ HEAD --quiet ../../packages/docs

An example of "Ignored Build Step" command. If changes were commited to "../../packages/docs", the command will yield a non-empty response, allowing the build to proceed.

Debugging Commands Locally

To debug the Ignored Build Step commands locally, it is important to first use a folder that can replicate the setup available on Vercel. To do this, you can apply the following steps:

  1. Clone the repository to another folder using git clone --depth=2 (...).
  2. Run the command or script in your terminal.
  3. You can check the exit code returned by the last command with echo $?.
Updated April 6th 2021