Endtest Vercel Integration

This repository contains a PHP 8.5 reference implementation for connecting Endtest to Vercel Deployment Checks.

When a configured Vercel deployment becomes ready, the integration starts the project's Endtest API Request, waits for one or more Endtest execution hashes, and updates the Vercel check to succeeded or failed.

Features

• Vercel OAuth installation flow
• Per-project Endtest API Requests
• Preview and production deployment controls
• Blocking or non-blocking Deployment Checks
• One or multiple Endtest execution hashes
• Check reruns from the Vercel deployment page
• Vercel installation tokens and per-project Endtest API Requests
• Signed webhook verification
• Duplicate webhook protection
• Worker-based polling outside the webhook request
• Vercel check heartbeats for long Endtest runs
• PHP 8.5 with strict types enabled

How it works

1. Vercel sends deployment.created.
2. The integration creates an Endtest Deployment Check in the registered state.
3. Vercel sends deployment.ready.
4. The integration marks the check as running and queues an Endtest job.
5. The CLI worker starts the stored Endtest API Request.
6. Endtest returns one hash or comma-separated hashes.
7. The worker polls action=getResults until all results are available.
8. The worker completes the Vercel check as succeeded or failed and links it to the Endtest result.

deployment.check-rerequested creates another Endtest attempt for the same Vercel check.

Repository layout

config.example.php
 database/schema.sql
 public/configure.php
 public/oauth-callback.php
 public/webhook.php
 src/
 tests/run.php
 worker/process.php

1. Create the Vercel integration

In Vercel, open:

Dashboard
Integrations
Integrations Console
Create

Create a Connectable Account Integration with these suggested values:

Name: Endtest
URL Slug: endtest
Short Description: Run Endtest automated tests against every Vercel deployment.
Category: Testing
Website: https://endtest.io

Use URLs matching the location where the public files are deployed:

Redirect URL:
https://app.endtest.io/integrations/vercel/oauth-callback.php

Configuration URL:
https://app.endtest.io/integrations/vercel/configure.php

Webhook URL:
https://app.endtest.io/integrations/vercel/webhook.php

Enable the Checks API and subscribe to:

deployment.created
deployment.ready
deployment.check-rerequested
integration-configuration.removed

Grant the minimum scopes needed to read projects and manage deployment checks.

2. Install the files

Copy the repository into the Endtest application, preferably outside the public web root except for the three files in public.

Copy the configuration:

cp config.example.php config.php

Set:

• MySQL connection values
• Vercel Client ID
• Vercel Client Secret
• OAuth Redirect URL
• Public integration URL
• Endtest team session key

Do not commit config.php.

3. Create the database tables

Run:

mysql -u USER -p DATABASE < database/schema.sql

The database stores Vercel OAuth access tokens and full Endtest API Requests, including appId and appCode. Restrict database and application access using the same controls as the rest of the Endtest platform.

4. Connect the Endtest login session

src/EndtestSession.php expects the signed-in Endtest team ID in:

$_SESSION['team_id']

Change endtest_team_session_key in config.php if the existing Endtest application uses another key.

The OAuth callback refuses to save an installation unless the user is signed into Endtest.

5. Configure a project

After installation, the user selects a Vercel project and pastes their full Endtest API Request.

The request may contain the customer's own appId and appCode, exactly like other Endtest integrations.

Available placeholders:

{{VERCEL_DEPLOYMENT_URL}}
{{VERCEL_DEPLOYMENT_URL_ENCODED}}
{{VERCEL_DEPLOYMENT_HOST}}

Example:

https://app.endtest.io/api.php?action=runWeb&appId=123&appCode=456&suite=789&notes={{VERCEL_DEPLOYMENT_URL_ENCODED}}

The placeholder can be placed in any Endtest API parameter used by the selected test suite. The integration does not force a new Endtest parameter name.

A suite that already discovers its target URL by another method may use an API Request without a placeholder.

6. Run the worker

The webhook does not wait for the tests. Run the worker from cron or an existing Endtest job runner:

php /path/to/endtest-vercel-integration/worker/process.php

Example cron entry, once per minute:

* * * * * /usr/bin/php /path/to/endtest-vercel-integration/worker/process.php >> /var/log/endtest-vercel-worker.log 2>&1

Only one worker is required initially. Job claiming is optimistic, so multiple workers can also be used.

The default worker settings are:

Poll Endtest every 30 seconds
Refresh the Vercel check every 240 seconds
Fail after 30 minutes
Process up to 10 queued jobs per invocation

The heartbeat is important because Vercel can mark a running check stale after five minutes without an update.

7. Test the package

php tests/run.php

Lint all PHP files:

find . -name '*.php' -print0 | xargs -0 -n1 php -l

Deployment Protection

A protected Vercel preview may reject requests from the Endtest browser unless the project grants automation access. Configure Vercel's Deployment Protection bypass for the Endtest run or disable protection for the relevant preview environment.

This is separate from the Deployment Check itself.

Production notes

Before enabling the integration for customers:

• Map EndtestSession to the real Endtest authentication/session model.
• Keep config.php outside source control and restrict filesystem permissions.
• Run the worker under a process supervisor or the existing Endtest queue system.
• Add structured logging and alerting for failed OAuth exchanges, webhooks, and workers.
• Confirm the exact project scopes selected in the Vercel Integrations Console.
• Test both personal-account and team-account installations.
• Test a label-based Endtest request that returns multiple hashes.
• Add a cleanup policy for old webhook events, jobs, and deployment runs.

License

MIT