Vercel Pro CI/CD for AI apps with previews and spend caps
Design AI CI/CD on Vercel with previews, rollbacks and AI Gateway budgets to control LLM costs and blast radius.
What you will build: cost-safe AI CI/CD on Vercel
This guide walks through a concrete CI/CD architecture for an AI-powered Next.js app on Vercel that:
- uses Git-connected preview deployments on every pull request,
- protects preview URLs with Deployment Protection,
- routes all inference through Vercel AI Gateway with per-environment API keys and budgets, and
- rolls out AI features behind feature flags so they can be disabled or rolled back instantly.
The goal is simple: treat LLM usage as an environment-scoped resource so you can cap spend and blast radius at the URL and API key level, instead of relying only on token discipline in application code.
On the Pro plan, Vercel charges $20/month per team member in USD for the first deploying seat, and each Pro seat includes $20/month of usage credit that is applied to metered infrastructure usage, as described on Vercel’s current pricing and plans documentation. AI Gateway charges at each provider’s list price with no token markup, and usage draws down prepaid AI Gateway credits (with a free tier of $5/month in credits for teams that have never purchased credits), as described in Vercel’s AI Gateway pricing documentation. That means most of the cost control work is in how environments, keys and budgets are designed.
The target architecture in one picture
At a high level, the architecture for an AI-powered web app on Vercel looks like this:
Vercel’s Project Overview surfaces Web Analytics and Firewall status together so you can spot traffic spikes or suspicious patterns around AI endpoints across preview and production deployments.
- Plans: Vercel Pro for the core app; AI Gateway usage on the same Vercel account, starting with the free $5/month credit tier and then prepaid credits for additional inference.
- Environments: dev (local), preview (per-PR), staging, production.
- Routing: all AI calls use Vercel AI SDK → Vercel AI Gateway → providers (e.g. OpenAI GPT-4.1/Mini).
- Keys: separate AI Gateway API key per environment.
- Budgets: AI Gateway Budgets at team, project and per-key level.
- Protection: preview URLs gated via Deployment Protection; AI endpoints hidden behind feature flags.
- Rollouts: feature flags control which routes/users see AI features; rollbacks use either flag flips or Vercel deployment rollback.
When this architecture is the right choice
This stack is a good fit when:
- Your core app is on Next.js or a similar front-end on Vercel.
- You plan to use Vercel AI SDK and AI Gateway as the main entry point to GPT-4.1 / GPT-4.1 Mini (or other models).
- You want every AI change to go through preview deployments before production.
- You care more about capping worst-case cost than shaving a few percent off average token usage.
This guide assumes Pro as the default. Vercel’s pricing page states the Hobby plan is $0/month and includes CI/CD and preview deployments for personal, non‑commercial projects. Pro adds metered usage credit, higher limits, team collaboration features, and options like Flat Rate CDN that start to matter once you ship anything user‑facing at scale. If you are still deciding whether to put your AI app on Vercel at all, the deployment patterns in this hybrid GitHub Actions + Vercel + Cloudflare workflow in this CI/CD guide for AI agents are a useful complement to this article.
Plan choices and CI/CD foundation on Vercel
Choosing between Hobby, Pro and Enterprise for AI CI/CD
From Vercel’s pricing and plans documentation:
| Plan |
Best for |
Platform fee |
Key strengths for AI CI/CD |
Main limitation |
| Hobby |
Non-commercial experiments, solo prototypes |
$0/month |
CI/CD & preview deployments; 100 GB/month data transfer |
Personal/non-commercial use; stricter limits; fewer spend controls |
| Pro |
Startups & SaaS teams shipping to production |
$20/month per team for first deploying seat |
Usage credit, higher limits, and team collaboration features |
Region and compliance controls are more limited than Enterprise |
| Enterprise |
Large regulated organisations |
Custom |
Advanced security, multi-region compute, 99.99% SLA |
Sales process and higher minimums |
As of the current Vercel limits documentation, Pro teams can create up to 6,000 deployments per day and run up to 12 concurrent builds by default. That is plenty for branch-based workflows with AI-heavy previews.
Decision rule:
- Use Hobby if you are experimenting with low-traffic prototypes and can tolerate the occasional cost surprise from provider-side billing.
- Use Pro for any commercial app with user-facing AI. The $20 platform fee is small compared with the risk reduction you get from better usage management. The side-project guidance in this Vercel setup guide also applies here: treat previews and budgets as guardrails from day one.
- Use Enterprise if compliance, region locking or org-wide CI policies are hard requirements.
Git-connected previews as the backbone of AI releases
Vercel’s Git integration and Preview Deployments docs explain that when a Git repository is connected, every push and pull request automatically creates a preview deployment with its own URL and environment variables scoped to that deployment.
For AI features this is critical:
- Every AI-related change (prompt, model, routing logic) goes through a distinct URL.
- Separate AI Gateway keys and budgets can be wired to preview vs production via environment variables.
- Rollbacks are just a matter of promoting a known-good deployment or turning a feature flag off.
If your AI features are being built by AI coding agents instead of humans, you can pair this pattern with the proof-gated workflows in this GitHub + Vercel hardening guide so agents never deploy directly to production.
Step 1: define environments and boundaries
First define four clear execution contexts for AI:
Vercel’s Environment Variables settings show how a single variable can be scoped separately for Development, Preview, and Production, which is how the architecture maps distinct AI Gateway keys and models to each environment.
- Local dev: using a personal or team AI Gateway key with a tight budget.
- Preview (per PR): each preview deployment uses the team’s
AI_GATEWAY_PREVIEW_KEY.
- Staging: optional shared environment mirroring production flags but lower budgets.
- Production: stable URLs, higher budgets, only exposed to real users.
On Vercel this maps to Environment Variables scoped per environment. For example:
| Variable |
Development |
Preview |
Production |
| AI_GATEWAY_KEY |
dev key |
preview key |
prod key |
| AI_MODEL |
gpt-4.1-mini |
gpt-4.1-mini |
gpt-4.1 or gpt-4.1-mini depending on feature flag |
| AI_FEATURE_FLAGS |
all on |
all on + test variations |
subset enabled by rollout system |
This separation is what lets you attach different AI Gateway budgets and protections per environment.
Step 2: route all inference through Vercel AI Gateway
Vercel AI Gateway provides a single endpoint that forwards requests to many AI providers. The AI Gateway pricing documentation states that usage is charged at provider list price with no markup. Every team that has not yet purchased AI Gateway credits receives $5/month in free credits; after you purchase credits, you switch to the paid tier where you pay as you go without the recurring $5 allowance.
The Vercel AI Gateway models catalog lists GPT-4.1 Mini pricing per 1M tokens, anchoring the guide’s cost modelling examples in concrete, provider-linked numbers.
The AI SDK documentation shows that you install the SDK via npm i ai from the Vercel AI SDK package. A typical Next.js handler using the SDK and AI Gateway could look like (pseudo-code, not a full example):
import { streamText } from 'ai';
export async function POST(req: Request) {
const { input } = await req.json();
const result = await streamText({
model: process.env.AI_MODEL!,
provider: 'openai-gateway', // configured in AI Gateway
apiKey: process.env.AI_GATEWAY_KEY!,
prompt: input,
});
return result.toAIStreamResponse();
}
The key architectural rule is: no direct calls from Vercel serverless functions to OpenAI or other providers. Everything should pass through AI Gateway to make budgets and observability effective.
Why Gateway routing is central to cost control
- Single choke point: all traffic is metered in one place, regardless of route or model.
- Budgets and alerts: a dollar limit can be attached to a key, project or team.
- Model switching: routes can be shifted to GPT-4.1 Mini or other models without touching every caller.
- Future multi-provider: Anthropic, Google, and other providers can be added via Gateway’s provider catalog without rewriting the app.
Step 3: create environment-scoped AI Gateway keys
AI Gateway lets teams create API keys and associate them with projects. To keep CI/CD and previews safe, it is useful to have at least three keys:
- Team dev key (local and internal tooling)
- Preview key (all preview deployments)
- Production key
In practice, staging, background jobs, and admin tooling are often separated as well.
Wiring keys into Vercel environments
- In Vercel, open the project’s Settings → Environment Variables.
- Create
AI_GATEWAY_KEY for Development, Preview, and Production, pasting the corresponding AI Gateway key values.
- Optionally add a
AI_ENVIRONMENT variable (dev, preview, prod) to log and tag requests for analysis.
Every preview deployment created on a pull request automatically uses the preview key, because Vercel attaches the preview-scoped environment variables to that deployment. This behaviour is documented in Vercel’s guide on deploying from Git, which notes that each preview deployment has its own URL and scoped environment variables.
Step 4: attach AI Gateway budgets per team, project and key
Vercel’s AI Gateway budgets documentation explains that you can set hard spend limits per team, project or API key using the CLI for a given refresh period, for example:
# Team-wide monthly hard cap of $500
vercel ai-gateway budgets set team \
--limit 500 \
--refresh-period monthly
# Project-level monthly cap of $100 for your app
vercel ai-gateway budgets set project <project-id> \
--limit 100 \
--refresh-period monthly
# Preview key cap of $5/month to limit blast radius
vercel ai-gateway budgets set api-key <preview-key-id> \
--limit 5 \
--refresh-period monthly
# Production key cap of $30/month for early-stage app
vercel ai-gateway budgets set api-key <prod-key-id> \
--limit 30 \
--refresh-period monthly
When the configured budget limit is reached, AI Gateway stops serving requests for that scope until the refresh period resets or you raise the budget, as described in the AI Gateway Budgets and Spend Limits documentation. This makes AI spend behave more like a prepaid phone plan than an unbounded postpaid bill.
Original cost analysis: budgets vs worst-case incident
Using the decision brief’s scenario of a misconfigured preview environment that leaks a GPT-4.1 endpoint:
- Assume a script drives 5M tokens of GPT-4.1 usage in a day: 3.5M input, 1.5M output.
- OpenAI’s GPT-4.1 pricing is $2.00 per 1M input and $8.00 per 1M output.
Cost without budgets:
- Input:
3.5M * $2.00 / 1M = $7.00
- Output:
1.5M * $8.00 / 1M = $12.00
- Total day cost ≈ $19.00
If the issue goes undetected for 10 days, that is ≈ $190.
With a $5/month preview API key budget in AI Gateway:
- The gateway cuts off when spend hits $5.
- Proportion of the incident cost experienced:
$5 / $19 ≈ 0.26 (≈ 26%).
- Worst-case cost that month from this incident becomes about $5, not $190.
Adding Deployment Protection to require Vercel-authenticated users on preview URLs further reduces the chance of the script reaching the endpoint at all, because non-authenticated traffic never reaches the protected preview deployment.
Step 5: protect preview deployments and AI endpoints
Preview environments are the easiest place for AI misconfigurations to leak. Vercel’s Deployment Protection docs describe protection levels that can require Vercel Authentication or passwords on preview deployments.
Deployment Protection settings in Vercel, with Vercel Authentication required on preview deployments, demonstrate how preview URLs can be locked down so AI endpoints are only reachable by authenticated team members.
Turn on Deployment Protection for previews
- In Vercel, go to Project → Settings → Deployment Protection.
- Choose a protection level that requires authentication on preview deployments. Vercel documentation notes that you can require Vercel-authenticated users for preview URLs.
- Optionally require passwords on especially sensitive branches (e.g.
ai-refactor/*).
This means:
- Only logged-in members of the relevant Vercel team can hit preview URLs.
- Public discovery of preview URLs via logs or analytics is no longer a direct cost risk.
Hide AI endpoints behind feature flags
Vercel’s platform page notes that deployments get secure preview URLs and that feature flags can be used to handle rollouts with instant rollback. For AI, feature flags can be applied to both routes and models:
- Route flags:
enable_chat_assistant, enable_autocomplete.
- Model flags:
ai_model=tier1 / tier2, mapping to GPT-4.1 Mini vs GPT-4.1.
A simple pattern is to store flags as environment variables consumed by a lightweight flag library, or to use a flagging service that integrates with Vercel’s edge and serverless functions.
This design gives two levers in an incident:
- Turn off the AI feature flag while keeping the deployment live.
- If necessary, roll back to a previous deployment via Vercel’s deployment history.
Step 6: choose cost-safe models for each environment
OpenAI’s model pricing is public. As of the current OpenAI API docs, GPT‑4.1 is priced at $2.00 per 1M input tokens and $8.00 per 1M output tokens, and GPT‑4.1 Mini at approximately $0.40 per 1M input tokens and $1.60 per 1M output tokens.
| Model |
Input price |
Output price |
Unit |
| GPT-4.1 |
$2.00 |
$8.00 |
per 1M tokens |
| GPT-4.1 Mini |
$0.40 |
$1.60 |
per 1M tokens |
Original cost analysis: GPT-4.1 vs GPT-4.1 Mini
At different token volumes, approximate monthly cost for a single environment:
| Total tokens (input+output) |
Assumed mix |
GPT-4.1 cost |
GPT-4.1 Mini cost |
| 1M |
70% input, 30% output |
Input: 0.7M × $2.00 = $1.40
Output: 0.3M × $8.00 = $2.40
Total ≈ $3.80
|
Input: 0.7M × $0.40 = $0.28
Output: 0.3M × $1.60 = $0.48
Total ≈ $0.76
|
| 10M |
70% input, 30% output |
Input: 7M × $2.00 / 1M = $14.00
Output: 3M × $8.00 / 1M = $24.00
Total ≈ $38.00
|
Input: 7M × $0.40 = $2.80
Output: 3M × $1.60 = $4.80
Total ≈ $7.60
|
| 50M |
70% input, 30% output |
Input: 35M × $2.00 / 1M = $70.00
Output: 15M × $8.00 / 1M = $120.00
Total ≈ $190.00
|
Input: 35M × $0.40 = $14.00
Output: 15M × $1.60 = $24.00
Total ≈ $38.00
|
Normalised analysis on these list prices shows GPT-4.1 Mini is about 5× cheaper than GPT-4.1 at the same traffic level under this 70/30 input-output assumption.
Environment-specific model policy
Given the pricing, a sensible rule set is:
- Local / preview: GPT-4.1 Mini by default; avoid running GPT-4.1 here except in tightly scoped test endpoints with extremely low budgets.
- Staging: GPT-4.1 Mini for most smoke tests; use feature flags to point a subset of traffic to GPT-4.1 for benchmarks.
- Production: GPT-4.1 Mini for always-on features; GPT-4.1 only for high-value flows (e.g. resume rewrites, legal notes) with explicit flags and dedicated budgets.
Step 7: CI/CD flow for AI changes with previews and rollbacks
With environments, Gateway routing, keys, budgets and models defined, this can be wired into a standard Git-based CI/CD flow.
1. Developer branch and local testing
- Work happens on a branch such as
feature/ai-chat locally, using AI_GATEWAY_KEY_DEV and GPT-4.1 Mini.
- All AI code paths are placed behind feature flags (e.g.
CHAT_ASSISTANT_ENABLED).
2. Push to Git and automatic preview deployment
- Pushing the branch causes Vercel to create a preview deployment with a unique URL and preview-scoped env vars.
- The preview deployment uses the
AI_GATEWAY_PREVIEW_KEY with a $5/month budget.
- Deployment Protection requires Vercel-authenticated users to view the preview.
3. Preview QA and AI behaviour checks
AI behaviour can be tested on the preview URL:
- Check model selection and prompts for obviously wasteful patterns (long system prompts, huge outputs).
- Use Vercel AI Gateway’s observability (available via its docs and dashboard) to inspect per-request tokens and cost metadata.
If costs spike even in preview, prompts or budgets can be adjusted before moving further.
4. Merge to main and staging rollout
- Merge PR → Vercel builds and deploys to staging (if used) and then production, depending on the workflow.
- Production deployment uses
AI_GATEWAY_PROD_KEY with a higher monthly budget (for example, $30/month for a small SaaS as in the decision brief scenario).
- Feature flag rollout starts at a small percentage of users or specific internal tenant IDs.
5. Production monitoring and fast rollback
Once live, monitoring typically includes:
- Vercel Usage page for infrastructure trends, as described in the manage-and-optimise-usage docs.
- AI Gateway dashboards for spend per key and per model.
- Web Analytics and Firewall status from the project overview. A Vercel changelog entry notes that both are surfaced at project level.
If behaviour or cost drifts:
- Disable the AI feature via a flag (instant rollback of user-visible behaviour).
- If spend is leaking from an unseen path, temporarily lower the AI Gateway budget for that API key.
- As a stronger move, use Vercel’s deployment history to roll back to the previous deployment that does not include the AI route.
Step 8: concrete cost scenarios on Pro
Using the decision brief’s scenarios and OpenAI/Vercel pricing, the following illustrates how the economics work out.
Scenario 1: solo builder, single AI feature
Assumptions from the brief:
- Production: 35k input + 15k output tokens per day of GPT-4.1 → 50k total/day.
- Preview: 10k tokens/day GPT-4.1.
Monthly totals:
- Prod input: 35,000 × 30 = 1,050,000 tokens.
- Prod output: 15,000 × 30 = 450,000 tokens.
Cost at GPT-4.1 list prices:
- Input: 1.05M × $2.00 / 1M ≈ $2.10.
- Output: 0.45M × $8.00 / 1M ≈ $3.60.
- Total GPT-4.1 cost ≈ $5.70/month.
Preview traffic of ~0.3M tokens/month adds under $1/month. AI Gateway passes these charges through at list price.
Platform cost:
- Vercel Pro platform fee: $20/month.
- $20 of infrastructure credit can offset serverless and bandwidth but not external OpenAI bills.
Budgets:
- Preview API key budget: $10/month (ample given actual usage < $1).
- Production API key budget: $30/month (5× headroom over baseline).
In this scenario, model cost is small compared to Pro’s platform fee. The main economic justification for AI Gateway budgets is protection against rare but expensive configuration mistakes. For a broader view of end-to-end MVP costs, the numbers in this AI MVP cost breakdown are a useful cross-check.
Scenario 2: small SaaS, GPT-4.1 Mini agent, heavier traffic
Assumptions from the brief:
- Production: 350k input + 150k output tokens per day GPT-4.1 Mini → 500k/day.
- Previews/staging: 50k tokens/day GPT-4.1 Mini.
Monthly production tokens:
- Input: 350,000 × 30 = 10,500,000 tokens.
- Output: 150,000 × 30 = 4,500,000 tokens.
Cost at GPT-4.1 Mini list prices:
- Input: 10.5M × $0.40 / 1M = $4.20.
- Output: 4.5M × $1.60 / 1M = $7.20.
- Total ≈ $11.40/month for production inference.
Previews add ≈ 1.5M tokens/month, well under $2/month at Mini prices.
AI Gateway budgets could be configured as:
- Team budget: $50/month.
- Project budget: $30/month.
- Preview API key budget: $5/month.
Even here, baseline AI cost is modest. The architecture’s job is to cap spikes and attribute spend cleanly, not to squeeze every token.
Observability: tying spend back to code and routes
Vercel’s platform and usage docs describe centralised logs, metrics and usage breakdowns across environments. Combined with AI Gateway observability, teams can:
- Log a
deploymentId and ai_environment tag with every AI call.
- Correlate increases in Gateway spend with specific deployments (e.g. a particular PR).
- Use Web Analytics and Firewall dashboards to see traffic anomalies around AI-heavy routes.
This makes rollback decisions more grounded: if a particular deployment’s preview shows a sudden jump in tokens for /api/chat, that deployment can be blocked from being promoted or its budgets can be lowered.
Integrating coding agents and CI with this pattern
For many teams, AI spend is dominated by coding agents and PR reviewers rather than runtime inference. Vercel Agent is an example: Vercel’s agent documentation describes it as an AI teammate that reviews pull requests, investigates anomalies and answers questions, with pricing based on tokens consumed.
To keep this in scope with AI budgets:
- Treat CI agents (Cursor, Claude Code, Vercel Agent, Codex-based tools) as another environment with its own cost centre.
- Set organisation-level budgets or usage alerts for these tools separate from runtime inference.
- Ensure AI CI/CD decisions are not overly focused on production inference if agents account for most tokens.
This aligns with the observation in the decision brief that when most AI tokens are consumed by coding agents, optimisation should start in CI and development tooling rather than at the Gateway. If you are designing that layer now, the repo-safe patterns in this HarnessAgent + AI Gateway cost-control guide are a good reference, alongside the broader stack choices in this AI development stack comparison.
What changes the decision
The architecture above assumes:
- Vercel is the main web runtime.
- AI traffic is user-facing and runs through AI Gateway.
- Vercel-native preview and rollback mechanics are desired.
Several conditions can flip the decision.
1. You are on Hobby and just experimenting
If the app is on Vercel Hobby with non-commercial prototypes and very low AI traffic, staying on Hobby with minimal AI Gateway configuration can be rational. Hobby includes CI/CD and previews at zero platform cost, per Vercel’s pricing page. Formal budgets and protection may be overkill if overspend incidents are limited to a few dollars.
2. Your AI usage is mostly batch jobs
If most tokens are consumed by long-running, back-office jobs (e.g. document ingestion, nightly summarisation), it can be cheaper and simpler to run those jobs on dedicated workers or another cloud, using Vercel only for the front-end. AI Gateway may still be useful for routing, but the critical cost controls will live where the jobs run.
3. You already have strict CI/CD elsewhere
If an organisation runs GitHub Actions, Kubernetes and a centralised CI/CD stack with mandatory approvals and security controls, using Vercel mainly as a thin deployment target or skipping its deployment features may be better. Duplicating governance in Vercel’s CI/CD may not add value.
4. Regulatory or data residency constraints
When AI model usage must stay within specific regions or providers, Vercel Enterprise or an alternative host might be necessary. Vercel’s Enterprise plan, described on the pricing page, adds advanced security and multi-region compute; some regulations may still require infrastructure not available on Hobby/Pro.
5. Most AI spend is in coding agents, not runtime
If token consumption is dominated by Vercel Agent, Cursor, Claude Code or similar tools, the highest-return step is to harden those agents and add CI usage controls. The architecture here still applies for runtime inference, but the biggest savings will come from throttling agents, using smaller models when safe, and tightening repository scope. For concrete patterns, see the post-incident CI hardening workflow in this HarnessAgent mirror-repo guide.
How to adapt this pattern to your context
To apply this architecture:
- Confirm the Vercel plan in use and whether Pro’s spend-related features or Enterprise’s compliance features are required.
- Decide which environments will be supported (preview, staging, production).
- Create AI Gateway keys and budgets per environment, with particularly low limits for preview and dev.
- Refactor all direct AI calls to go through Vercel AI Gateway via the
ai SDK.
- Enable Deployment Protection on preview deployments and hide AI routes behind feature flags.
- Set up basic observability: logs tagging deployment, environment and route for every AI call, and check AI Gateway dashboards regularly.
Once this is in place, adding new AI features becomes a repeatable pattern: branch → preview with protected AI endpoints and low-budget keys → review spend in Gateway → merge behind flags → slow rollout → monitor and adjust budgets. Combined with the safe deployment discipline from this Codex + Vercel preview-to-production workflow, the result is AI CI/CD on Vercel that fails cheap when something goes wrong, instead of failing expensively.