Vercel’s Checks API lets you inject the results of your CI tests directly into the deployment process, turning a "Deploying…" status into a rich, actionable report.
Let’s see it in action. Imagine you’ve got a standard Next.js project deployed to Vercel. You’ve added some Cypress end-to-end tests. Normally, Vercel deploys, and then you’d have to go to Cypress Cloud or your CI dashboard to see if the tests passed. With the Checks API, Vercel knows about your Cypress run during the deployment.
Here’s a simplified vercel.json that might trigger a hypothetical CI check (we’ll flesh out the actual integration later):
{
"githubToken": "YOUR_GITHUB_TOKEN",
"checks": [
{
"name": "E2E Tests",
"service": "cypress",
"url": "https://api.cypress.io/your/project/status/endpoint"
}
]
}
When Vercel builds and deploys your project, it’ll also ping that url to get the status of your E2E tests. If they pass, the deployment bar in Vercel stays green. If they fail, it turns red, and you get a clear indication right in the Vercel UI that your deployment is blocked by failing tests.
The problem this solves is the disconnect between code deployment and code quality. You can deploy code that looks fine but breaks functionality. Vercel’s core deployment is about getting your code live; the Checks API is about ensuring that live code is correct. It brings your testing framework directly into the deployment lifecycle, making test results a first-class citizen of your deployment process.
Internally, Vercel acts as a status reporter. When your CI pipeline (like GitHub Actions, GitLab CI, or CircleCI) runs your tests, it needs to communicate the results back to Vercel. The Checks API provides a standardized way for Vercel to query and display these results. You configure Vercel to know where to look for the status of a particular check (like your E2E tests, linting, or a security scan). Vercel then polls this endpoint or receives webhooks, updating the deployment status accordingly.
The key levers you control are the name of the check (which appears in the Vercel UI), the service (a hint for Vercel, often used for integrations), and crucially, the url or integration mechanism. For many CI providers, Vercel has direct integrations, meaning you don’t always need to provide a raw URL. Instead, you might configure environment variables or connect your CI provider account.
For instance, with GitHub Actions, you’d typically use Vercel’s own action. A snippet from a .github/workflows/deploy.yml might look like this:
name: Vercel Deployment
on:
push:
branches:
- main
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Dependencies
run: npm install
- name: Run E2E Tests
uses: cypress-io/github-action@v6
with:
build: npm run build
start: npm start
wait-on: 'http://localhost:3000' # Or your app's URL
- name: Deploy to Vercel
uses: Vercel/vercel-action@v11
with:
projectId: ${{ secrets.VERCEL_PROJECT_ID }}
token: ${{ secrets.VERCEL_TOKEN }}
# This is where the magic happens: Vercel automatically detects
# the Cypress run from the previous step if configured correctly
# in Vercel project settings or via environment variables.
The vercel-action itself, when run in a context where other steps have performed checks (like the Cypress action above), will often automatically associate those results with the deployment it triggers. Vercel’s backend is designed to correlate these events based on commit SHAs and project configurations.
The most surprising thing about the Checks API is its ability to block deployments based on external states without requiring complex custom scripting within your deployment pipeline itself. Vercel polls or listens for status updates from your configured checks, and if a check fails, Vercel will present the deployment as failed or pending, preventing a bad release from going live. It’s not just reporting; it’s gatekeeping.
You’ll next want to explore how to define custom checks for proprietary testing frameworks or internal tools that don’t have direct Vercel integrations.