vis ci ignore

Decide whether a deployment should proceed, based on whether a given project is affected by the current commit. Drops directly into Vercel's "Ignored Build Step" and Netlify's ignore field using inverted exit codes.

Inspired by nx-ignore but reuses vis's own affected detection — no parallel Nx install required on the deploy runner.

Usage

vis ci ignore <project> [options]

Exit codes

vis ci ignore uses inverted exit codes so it matches the contract Vercel and Netlify expect from an ignore hook:

Pass --exit-zero-on-build to invert this back to normal semantics (useful for local testing and for gating downstream CI jobs where 0 = success).

Examples

# Vercel / Netlify default — uses CI env vars automatically
vis ci ignore my-app

# Explicit base ref
vis ci ignore my-app --base "$VERCEL_GIT_PREVIOUS_SHA"

# Emit the decision as JSON (pipe into jq in GitHub Actions)
vis ci ignore my-app --json

# Normal exit semantics for local testing
vis ci ignore my-app --exit-zero-on-build

# Debug the decision path
vis ci ignore my-app --verbose

Options

How it works

1. Commit-message gating — reads the latest commit message and short-circuits on skip or force-deploy keywords before touching git diff.
2. Workspace discovery — resolves the workspace root and verifies that the requested project actually exists. Unknown projects exit with build (defensive default).
3. Base ref resolution — walks --base flag → CI env var chain → HEAD~1. If the resolved ref isn't reachable (e.g. Vercel's shallow clone), silently falls back to HEAD~1.
4. Affected detection — runs the same getAffectedProjects pipeline as vis affected, respecting --downstream and --upstream scope.
5. Decision emit — prints the outcome (human text or JSON) and calls process.exit with the inverted exit code.

Commit-message keywords

Keywords take precedence over git-diff detection — useful for emergency bypasses and forced deploys.

Skip build

Force build

Legacy [nx …] tokens are accepted so teams migrating from nx-ignore don't have to rewrite their commit automation on day one.

Base SHA resolution order

vis ci ignore probes these env vars in order. The first non-empty match wins, unless --base is passed explicitly.

Cloudflare Pages, Cloudflare Workers Builds, Render, and AWS Amplify are not detected here — their platforms don't invoke custom ignore scripts at all, so env detection would only create the illusion of support. See the supported platforms matrix.

JSON output

--json writes a structured decision record to stdout and suppresses the human text. Useful for pipelines that gate downstream jobs on the decision.

{
    "project": "my-app",
    "action": "skip",
    "reason": "project-not-affected",
    "message": "Skip my-app: not affected by changes between HEAD~1...HEAD",
    "base": "HEAD~1",
    "head": "HEAD",
    "affectedProjects": ["other-app"]
}

Reason codes

Decisions with reasons project-unknown, missing-project-argument, and workspace-error always map to action: "build" — we never cancel a build because of a tooling problem.

Supported platforms

For platforms without a native hook, use their built-in path filtering alongside vis, or move CI gating into GitHub Actions / GitLab CI and wrap vis ci ignore --json there.

See the CI/CD guide for complete deployment integration examples.

See also

• vis affected — run a target only on affected projects (what vis ci ignore is built on)
• CI/CD guide — full deployment integration patterns