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=1 (...), this means that only the latest commit data is available.

With a Script

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

#!/bin/bash

# Retrieve branch name
branch=$(git branch --show-current)

if [ "$branch" == "main" ]; then
  # Proceed with build
    exit 1;
else
  # Don't build
  exit 0;
fi

An example Ignored Build Step command.

By using this command, Vercel will only build deployments when the branch is called "main".

With Folders and Workspaces

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 Ignored Build Step command.

By using this command, Vercel will only build deployments when changes are made inside of the packages/frontend/ directory.

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=1 (...).
  2. Run the command or script in your terminal.
  3. You can check the exit code returned by the last command with echo $?.
Updated October 14th 2020