🛡️ Credit Shield

The Netlify Build Plugin that protects your credits by canceling every cloud build. Plus a CLI companion, credit savings tracker, GitHub Action, and Netlify usage dashboard.

Netlify gives you 15 free credits per month. Cloud builds eat those credits. Credit Shield cancels cloud builds at onPreBuild and tells you to deploy from your terminal instead — free, forever.

Landing page: Deploy with npx wrangler pages deploy site/ --project-name=credit-shield

Quick Start

npm install netlify-plugin-credit-shield --save-dev

Add to netlify.toml:

[[plugins]]
package = "netlify-plugin-credit-shield"

Push. The shield fires. You deploy locally. Credits stay at 15.

Configuration

The plugin accepts optional inputs in netlify.toml:

[[plugins]]
package = "netlify-plugin-credit-shield"

  [plugins.inputs]
    mode = "production"         # "production" | "all" | "warn" | "off"
    blockBranches = ""         # comma-separated, overrides mode
    allowBranches = ""         # comma-separated, overrides everything
    trackUrl = ""              # opt-in: URL for the credit tracker API

mode

| Value | Behavior | |-------|----------| | production (default) | Block production builds only. Deploy previews and branch deploys run normally. | | all | Block every cloud build — deploy previews, branch deploys, production. | | warn | Print the warning message but let the build proceed. Good for testing. | | off | Do nothing. The complete opposite of what this plugin is for. |

Branch filters

# Block only specific branches
blockBranches = "main,master,production"

# Always allow specific branches (overrides everything)
allowBranches = "dependabot/*,renovate/*"

CLI Companion

After installing the plugin, you also get npx credit-shield:

# Build + deploy to production (auto-detects dist folder + build command)
npx credit-shield deploy

# Build + deploy as preview (no --prod)
npx credit-shield preview

# Check credit usage from Netlify API + local tracker
npx credit-shield status

# Show cancelled build stats from the credit tracker API
npx credit-shield track --url=https://credit-shield.pages.dev

Options

--dir=folder     Dist folder (auto-detected: dist, build, out, .next, public, _site)
--build="cmd"    Build command (auto-detected from package.json scripts.build)
--token=xxx      Netlify personal access token (or NETLIFY_AUTH_TOKEN env)
--site=xxx       Netlify site ID (or NETLIFY_SITE_ID env)
--url=xxx        Credit tracker API URL (or CREDIT_SHIELD_TRACKER_URL env)
--message="msg"  Custom deploy message

Credit Savings Tracker

Track how many builds the shield has blocked across everyone using it.

Setup the API (one-time)

cd site/

# Create the D1 database
npx wrangler d1 create credit-shield-db

# Copy the returned database_id into wrangler.toml
# Replace "REPLACE_WITH_YOUR_D1_DATABASE_ID"

# Apply migrations
npx wrangler d1 migrations apply credit-shield-db --remote

Enable tracking in your project

Add the tracker URL to your plugin config:

[plugins.inputs]
trackUrl = "https://credit-shield.pages.dev"

Every blocked build will fire-and-forget a POST to the tracker. No secrets, no auth, just stats.

Badge

Show off your savings:

![Credit Shield](https://credit-shield.pages.dev/api/badge)

GitHub Action

Skip Netlify's build pipeline entirely. Build on a GitHub runner (free) and deploy via netlify-cli.

Option A: Use the composite action

name: Deploy via Credit Shield
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jovylle/netlify-plugin-credit-shield/.github/actions/credit-shield-deploy@main
        with:
          deploy-dir: dist
          netlify-auth-token: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          netlify-site-id: ${{ secrets.NETLIFY_SITE_ID }}

Option B: DIY with the CLI

- run: npm ci
- run: npm run build
- run: npx netlify-cli deploy --prod --dir=dist --auth=${{ secrets.NETLIFY_AUTH_TOKEN }} --site=${{ secrets.NETLIFY_SITE_ID }}

Required GitHub Secrets

| Secret | Value | |--------|-------| | NETLIFY_AUTH_TOKEN | Personal access token from Netlify Applications | | NETLIFY_SITE_ID | Site ID from Netlify dashboard (Site configuration > General > Site ID) |

Netlify Dashboard (credit-shield status)

# Without auth — shows local tracker data only
npx credit-shield status

# With auth — full Netlify API breakdown
NETLIFY_AUTH_TOKEN=nfp_your_token npx credit-shield status

Shows: account type, plan, build minutes consumed/available, site count, recent builds. All data stays local — no tokens sent anywhere.

How it works

1. You push to GitHub (or whatever triggers Netlify builds)
2. Netlify starts a cloud build
3. onPreBuild fires → checks mode, blockBranches, allowBranches, context, and branch
4. If conditions match → utils.build.cancelBuild() is called
5. Build stops. Credits saved. You get instructions in your build log.
6. If trackUrl is set → fire-and-forget POST to the credit tracker API
7. You build locally and deploy with netlify-cli or npx credit-shield deploy — free

FAQ

Does this actually work? Yes. utils.build.cancelBuild() is part of the Netlify Build Plugin API.

Why is the landing page on Cloudflare Pages? Because Cloudflare doesn't charge for build minutes. Irony is a dish best served on the edge.

Will Netlify be mad? No. You're using their documented plugin API. You're just choosing not to use their cloud build runners.

Can I block only production and keep deploy previews? Yes — that's the default (mode = "production").

Can I use this without the CLI? Yes. The plugin and CLI are independent. npm install netlify-plugin-credit-shield --save-dev gives you the plugin only.

Can I use the CLI without the plugin? Yes. npx credit-shield deploy works in any project regardless of whether the plugin is installed.

Where does the credit tracker send data? Nowhere by default. It's opt-in — you set trackUrl to point at your own Cloudflare Pages Functions endpoint. The site/functions/api/track.js handler is a reference implementation.

Deploy the landing page

# 1. Create D1 database
npx wrangler d1 create credit-shield-db

# 2. Edit site/wrangler.toml — paste the database_id

# 3. Apply migrations
npx wrangler d1 migrations apply credit-shield-db --remote

# 4. Deploy
npx wrangler pages deploy site/ --project-name=credit-shield

License

MIT — Jovylle Bermudez