Vercel's Ignored Build Step lets a shell command decide whether a deployment gets built. The common example compares the current commit with HEAD^. That works until someone pushes two commits at once. Vercel only builds the last commit of a push, so a content commit with a docs-only commit on top gets skipped, and the content never goes live.

This happened in the repository behind straffesites.com, a static Astro site deployed on Vercel. The repo also holds an Obsidian vault under wiki/. It's synced with its own commits and isn't part of the site, so there's no reason to rebuild for it. This article shows the script that skips those builds, the deployment history that shows why HEAD^ is the wrong base, a fallback bug I found in our own version while writing this, and a test that pins the behavior.

Versions used: git 2.43, Node 26, POSIX sh.

The setup: ignoreCommand in vercel.json

You can set the command in the project settings or in vercel.json. The file version lives in the repo, so it gets reviewed like any other change. The relevant part of this project's vercel.json:

{ "framework": "astro", "buildCommand": "npm run build", "outputDirectory": "dist", "ignoreCommand": "sh scripts/vercel-ignore-build.sh" } 

The exit codes are the reverse of what most people expect. According to Vercel's guide, exit code 0 skips the build, and 1 or greater builds. That has a useful side effect: if the script crashes or sh hits a syntax error, the exit code is nonzero and Vercel builds. A broken script fails toward building, which is what you want.

The same guide says Vercel clones with git clone --depth=10, and the command runs in the project's Root Directory. Both details matter below.

The script

The comments and messages in the repository are in Dutch. This is the same logic in English:

#!/bin/sh # Vercel Ignored Build Step: exit 0 = skip the build, exit 1 = build. # Skip only when nothing outside wiki/ changed since the last successful # deployment of this branch. When in doubt, build. base="${VERCEL_GIT_PREVIOUS_SHA:-}" if [ -z "$base" ]; then echo "No previous successful deployment for this branch: building." exit 1 fi if ! git cat-file -e "${base}^{commit}" 2>/dev/null; then echo "Base commit ${base} is not in the clone: building." exit 1 fi if git diff --quiet "$base" HEAD -- . ':(exclude)wiki'; then echo "Only wiki/ changed since ${base}: skipping the build." exit 0 fi echo "Site changes since ${base}: building." exit 1 

Three choices in there:

  • The base is VERCEL_GIT_PREVIOUS_SHA. The system environment variables docs describe it as "the git SHA of the last successful deployment for the project and branch." It's empty on a branch's first deployment, and it's only exposed when an Ignored Build Step is configured.
  • The diff uses an exclude pathspec. -- . ':(exclude)wiki' compares everything except wiki/. git diff --quiet exits 0 when there are no differences, so it maps directly onto Vercel's "skip" code. If you'd rather list what does count (for example src public package.json), that works too, but every new top-level folder then needs an update. Excluding the one folder you know is safe is harder to get wrong.
  • Every uncertain case builds. No base, a base outside the clone, or a git error all end in exit 1.

Why HEAD^ is the wrong base

A lot of examples online use git diff --quiet HEAD^ HEAD -- <path>. That answers "did the last commit touch this path?", but Vercel isn't asking about the last commit. It's asking whether anything changed since the last deployment.

The repository's own history shows the difference. Between October 22, 2026 (when the script landed) and November 15, 2026, six first-parent commits on main touched only wiki/. For each of them, I read the commit statuses that Vercel writes to GitHub:

gh api repos/OWNER/REPO/commits/SHA/statuses \ --jq '.[] | [.context, .state, .description] | @tsv' 
  • Three had the status description Canceled by Ignored Build Step. Nothing outside wiki/ had changed since the previous deployment, so skipping was right.
  • Three were built and got Deployment has completed. Each of those wiki commits was the last commit of a push with a content commit underneath. One example: a blog edit at 15:02:45 UTC, a change-log commit and the wiki sync at 15:02:55 UTC. Only the wiki sync got a deployment.

With HEAD^ as the base, the diff for those three pushes would have shown only wiki/ and the builds would have been skipped. The content commits would have sat in main without reaching production until some later push happened to trigger a build. Nothing would have failed, and the GitHub status would still have been green.

The fallback bug in our first version

The first version of the script used this line:

base="${VERCEL_GIT_PREVIOUS_SHA:-HEAD^}" 

On main that fallback never ran, because there's always a previous successful deployment. But the variable is empty on the first deployment of any new branch. A preview branch whose last commit is a wiki sync would compare only that commit and skip the build, even with real site changes underneath. That also contradicted the script's own comment ("when in doubt, build"). The fix is the -z check above: no previous deployment means no safe base, so build.

The shallow clone limit

Vercel clones ten commits deep. If the last successful deployment is further back than that, the base commit isn't in the clone and git diff can't compare against it. You could try git fetch --deepen, but the build environment may not have credentials for a private repository. The script checks for the base with git cat-file -e and builds when it's missing. In practice, that means the script can only skip a build when the last deployed commit is one of the ten commits in the clone. That's a fair trade: one extra build after a long run of wiki commits is cheap, and a skipped deployment is not.

Reproducing it locally

The guide suggests debugging with a fresh --depth=10 clone and echo $?. This script builds a throwaway repository and runs every case. Save the script above as ignore-build.sh and run this from an empty directory with sh demo.sh "$PWD/ignore-build.sh":

#!/bin/sh # Run from an empty directory: sh /path/to/demo.sh /path/to/ignore-build.sh SCRIPT="$1" c() { mkdir -p "$(dirname "$1")"; echo "$2" >> "$1"; git add -A; git -c user.name=demo -c user.email=demo@example.com commit -qm "$2"; } git init -q repo && cd repo c src/index.md "site v1" DEPLOYED=$(git rev-parse HEAD) c src/index.md "site v2" c wiki/notes.md "wiki sync" echo "--- naive check against HEAD^" git diff --quiet HEAD^ HEAD -- . ':(exclude)wiki' && echo "skip (exit 0)" || echo "build (exit 1)" echo "--- check against VERCEL_GIT_PREVIOUS_SHA" VERCEL_GIT_PREVIOUS_SHA=$DEPLOYED sh "$SCRIPT"; echo "exit $?" echo "--- first deploy of a branch (variable empty)" VERCEL_GIT_PREVIOUS_SHA= sh "$SCRIPT"; echo "exit $?" for i in $(seq 1 12); do c wiki/notes.md "wiki $i"; done DEPLOYED_WIKI=$(git rev-parse HEAD~1) c wiki/notes.md "wiki 13" echo "--- only wiki since the last deploy" VERCEL_GIT_PREVIOUS_SHA=$DEPLOYED_WIKI sh "$SCRIPT"; echo "exit $?" cd .. && git clone -q --depth=10 "file://$PWD/repo" shallow && cd shallow echo "--- shallow clone (--depth=10), last deploy 15 commits back" VERCEL_GIT_PREVIOUS_SHA=$DEPLOYED sh "$SCRIPT"; echo "exit $?" 

Output from a real run (your SHAs will differ):

--- naive check against HEAD^ skip (exit 0) --- check against VERCEL_GIT_PREVIOUS_SHA Site changes since e21e9d67165aeb8b434589e55b740f85a5d9d6fa: building. exit 1 --- first deploy of a branch (variable empty) No previous successful deployment for this branch: building. exit 1 --- only wiki since the last deploy Only wiki/ changed since 55a55e3d0b77046f0228e80b57fb7dd0cfb1a698: skipping the build. exit 0 --- shallow clone (--depth=10), last deploy 15 commits back Base commit e21e9d67165aeb8b434589e55b740f85a5d9d6fa is not in the clone: building. exit 1 

The first block is the bug: the naive check skips a push that contains a content change.

Pinning it with a test

A script that decides whether production gets updated deserves a test. The repository runs this with node --test as part of its regular checks. It creates a temporary git repository and runs the real script against it:

import { test } from 'node:test'; import assert from 'node:assert/strict'; import { execFileSync, spawnSync } from 'node:child_process'; import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join, resolve } from 'node:path'; const script = resolve('scripts/vercel-ignore-build.sh'); function git(cwd, ...args) { return execFileSync('git', args, { cwd, encoding: 'utf8' }).trim(); } function commit(cwd, file, message) { const path = join(cwd, file); mkdirSync(join(path, '..'), { recursive: true }); writeFileSync(path, `${message}\n`); git(cwd, 'add', '-A'); git(cwd, '-c', 'user.name=t', '-c', 'user.email=t@example.com', 'commit', '-qm', message); return git(cwd, 'rev-parse', 'HEAD'); } function run(cwd, previousSha) { const env = { ...process.env }; delete env.VERCEL_GIT_PREVIOUS_SHA; if (previousSha !== undefined) env.VERCEL_GIT_PREVIOUS_SHA = previousSha; return spawnSync('sh', [script], { cwd, env, encoding: 'utf8' }).status; } test('ignore-build: skips wiki-only changes, builds everything else', () => { const repo = mkdtempSync(join(tmpdir(), 'ignore-build-')); try { git(repo, 'init', '-q'); const deployed = commit(repo, 'src/page.md', 'site v1'); commit(repo, 'wiki/note.md', 'wiki only'); assert.equal(run(repo, deployed), 0, 'wiki-only since last deploy: skip'); commit(repo, 'src/page.md', 'site v2'); commit(repo, 'wiki/note.md', 'wiki sync on top'); assert.equal(run(repo, deployed), 1, 'buried site commit since last deploy: build'); assert.equal(run(repo, undefined), 1, 'no previous deploy (first branch deploy): build'); assert.equal(run(repo, ''), 1, 'empty previous SHA: build'); assert.equal(run(repo, 'f'.repeat(40)), 1, 'previous SHA outside the clone: build'); } finally { rmSync(repo, { recursive: true, force: true }); } }); 

Run against the old HEAD^ fallback, this test fails on the "no previous deploy" case: the script returned 0 (skip) where it should have built.

When you don't need a script

If your repository is a monorepo with workspaces, Vercel can skip unaffected projects on its own (the guide mentions this is powered by Turborepo). That's the simpler option when "changed" means "this package or its dependencies changed." A custom script makes sense when the rule is about something Vercel doesn't model, like a docs or notes folder that lives next to the site.

Summary

  • Exit 0 skips, 1 or greater builds. Let every unclear case fall through to 1.
  • Compare against VERCEL_GIT_PREVIOUS_SHA, not HEAD^. Vercel builds the last commit of a push, and HEAD^ misses everything below it.
  • VERCEL_GIT_PREVIOUS_SHA is empty on a branch's first deployment. Build in that case instead of falling back to HEAD^.
  • The clone is ten commits deep. Check that the base exists before you diff.
  • Skipped builds show up in GitHub as a green status with Canceled by Ignored Build Step. Check that description after setting this up to confirm the script skips what you expect, and only that.

In the site's repository, the script lives in scripts/vercel-ignore-build.sh and the test in tests/vercel-ignore-build.test.mjs. Both run on every push to main, and the script ran on the deployment that shipped this fix.