---
title: How do I use the "Ignored Build Step" field on Vercel?
description: Instructions on how to use the "Ignored Build Step" field to programmatically prevent a new deployment from being built.
url: /kb/guide/how-do-i-use-the-ignored-build-step-field-on-vercel
canonical_url: "https://vercel.com/kb/guide/how-do-i-use-the-ignored-build-step-field-on-vercel"
published: 2025-11-03
last_updated: 2026-07-16
authors: Justin Vitale
related:
  - /docs/projects/overview
  - /docs/projects/environment-variables/system-environment-variables
  - /docs/monorepos
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Troubleshoot Build Errors](https://vercel.com/docs/deployments/troubleshoot-a-build?from=related) — Learn how to resolve common scenarios you may encounter during the Build step, including build errors that cancel a depl
- [Project Settings](https://vercel.com/docs/project-configuration/project-settings?from=related) — Use the project settings, to configure custom domains, environment variables, Git, integrations, deployment protection,
- [Build Features](https://vercel.com/docs/builds/build-features?from=related) — Learn how to customize your deployments using Vercel's build features.
- [Builds](https://vercel.com/docs/builds?from=related) — Understand how the build step works when creating a Vercel Deployment.
- [vercel build](https://vercel.com/docs/cli/build?from=related) — Learn how to build a Vercel Project locally or in your own CI environment using the vercel build CLI command.
- [Per-environment and per-branch Build Commands on Vercel](https://vercel.com/kb/guide/per-environment-and-per-branch-build-commands?from=related) — Customize your commands for specific behaviors based on branch, environment, and more.
- [Dynamically run build commands](https://vercel.com/kb/guide/dynamic-build-commands?from=related) — Learn how to run different scripts based on the environment or branch.
- [Why aren't commits triggering deployments on Vercel?](https://vercel.com/kb/guide/why-aren-t-commits-triggering-deployments-on-vercel?from=related) — Commits not triggering deployments on Vercel? Walk the diagnostic checklist covering authentication, commit author acces
- [How can I add a custom build step to my project? ](https://vercel.com/kb/guide/how-can-i-add-a-custom-build-step-to-my-project?from=related) — Learn how to add a custom build step for your project.
- [How can I use the Vercel CLI for custom workflows?](https://vercel.com/kb/guide/using-vercel-cli-for-custom-workflows?from=related) — You can use the Vercel CLI to deploy any application, including custom git providers and restricted source code.

Full cross-link map for this page: [/kb/guide/how-do-i-use-the-ignored-build-step-field-on-vercel.graph.md](/kb/guide/how-do-i-use-the-ignored-build-step-field-on-vercel.graph.md)
<!-- /docsgraph:related -->


You can enable the "Ignored Build Step" field by referring to the [documentation](https://vercel.com/docs/projects/overview#ignored-build-step) 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:

**Note:** You can also use Node scripts (e.g. `node ignore-step.js`).

```bash
#!/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
```

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](https://vercel.com/docs/projects/environment-variables/system-environment-variables) which makes it available for the project.

## With Environment Variables

You can create a command referencing [System Environment Variables](https://vercel.com/docs/projects/environment-variables/system-environment-variables#system-environment-variables) directly in the Ignored Build Step field:

```bash
if [ "$VERCEL_ENV" == "production" ]; then exit 1; else exit 0; fi
```

Below is an example script that will conditionally build certain branches:

```bash
#!/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
```

## 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:

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

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:

```bash
git diff HEAD^ HEAD --quiet -- .
```

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:

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

## Automatically skip unnecessary deployments in monorepos

Vercel can now automatically skip builds for unchanged code in certain monorepo projects. If you don't require as much granularity, such as skipping based on branch names for example, then you may be able to make use of this option to optimize your deployment queue.

When this option is enabled, projects without changes in their source code (or the source code of internal dependencies) will be skipped, reducing build queuing and improving the time to deployment for affected projects. This feature is powered by [Turborepo](https://turbo.build/repo/docs/core-concepts/package-and-task-graph#package-graph), and works with any [monorepo using workspaces](https://vercel.com/docs/monorepos#requirements).

Learn more about [skipping unaffected projects](https://vercel.com/docs/monorepos#skipping-unaffected-projects).

## Why is the command not working?

### Using Environment Variables

The first thing to check is if your command uses Vercel related variables such as \`VERCEL\_ENV\`. You can check this either in your custom script or if you use a preset option then it will show what command is run in the \`Ignored Build Step\` settings once this is selected.

If you are using these variables, make sure you have checked the option to \`[Automatically Expose System Environment Variables](https://vercel.com/docs/projects/environment-variables/system-environment-variables)\` so that these are available to the command.

### 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=10 (...)`.
   
2. Run the command or script in your terminal.
   
3. You can check the exit code returned by the last command with `echo $?`.