Repository navigation
Description
On this page
Vercel CI Configuration Reference
Creating task dependencies
Tasks that are tagged to run in CI will have their dependencies run in CI, too.
turbo.json
{
"tasks": {
"build": {
"dependsOn": ["^build"]
},
"test": {
"dependsOn": ["^build"],
"tags": ["ci"]
}
}
}
Using Turborepo's task composition rules, Vercel CI will run the build tasks that a test task depends on before executing the test task.
You can also set the ci tag in a Package Configuration.
packages/web/turbo.json
{
"extends": ["//"],
"tasks": {
"test": {
"tags": ["ci"]
}
}
}
This runs that task for the package even when the root turbo.json does not enable it, giving you the power to compose your CI declarations.
Excluding tasks
Add the !ci tag to keep a task from being selected to run in Vercel CI. The !ci tag takes precedence over the ci tag, so a task with both tags doesn't run.
Use !ci in a Package Configuration to opt one package out of a task that the root turbo.json runs in CI. In the example below, the root turbo.json runs test for every package:
turbo.json
{
"tasks": {
"test": {
"tags": ["ci"]
}
}
}
The package's turbo.json excludes its own test task:
packages/legacy/turbo.json
{
"extends": ["//"],
"tasks": {
"test": {
"tags": ["!ci"]
}
}
}
Vercel CI runs test for every package except packages/legacy.
!ci doesn't remove a task from the dependencies of other tasks. If a task that runs in Vercel CI depends on a task tagged !ci, Vercel CI still runs the dependency first.
Resource sizing
Vercel CI assigns 2 CPUs and 4 GB of memory to each task by default.
Add a ci:cpus:<count> tag to assign up to 32 CPUs to a task:
turbo.json
{
"tasks": {
"test": {
"tags": ["ci", "ci:cpus:8"]
}
}
}
Memory resources are assigned at 2 GB per CPU:
| CPUs | Memory |
|---|---|
| 1 | 2 GB |
| 2 | 4 GB |
| 4 | 8 GB |
| 8 | 16 GB |
| 16 | 32 GB |
| 32 | 64 GB |
To change the CPU allocation for one package, add the tag in that package's Package Configuration. Start the tags array with $TURBO_EXTENDS$ so the task keeps the ci tag from the root turbo.json:
packages/web/turbo.json
{
"extends": ["//"],
"tasks": {
"test": {
"tags": ["$TURBO_EXTENDS$", "ci:cpus:16"]
}
}
}
Bootstrapping resources
Before your tasks run, Vercel CI bootstraps each run by cloning your repository and installing its dependencies. The install step uses 4 CPUs and 8 GB of memory by default.
If dependency installation is slow or runs out of memory, set ci.bootstrapping.resources.vcpus in the vercel.json file at the root of your repository:
vercel.json
{
"ci": {
"bootstrapping": {
"installEnv": {},
"resources": {
"vcpus": 16
}
}
}
}
vcpusmust be a whole number from 1 to 32.- Memory is assigned at 2 GB per CPU, so this example requests 16 CPUs and 32 GB of memory.
- This setting only applies to dependency installation. It doesn't change the resources assigned to your tasks.
- An invalid
resourcesvalue makes yourciconfiguration invalid. Vercel CI will ignore your configuration.
Installing additional tools
To install a tool that your package manager doesn't provide, set ci.bootstrapping.installCommand in vercel.json. Before you install a tool, check whether the image already includes it. See Pre-installed software for the full list.
Your install command doesn't run on the same instance as your tasks. Vercel CI handles each run in these steps:
- During bootstrapping, Vercel CI clones your repository and runs the install command on a separate instance that always uses the Amazon Linux image.
- Vercel CI saves a copy of your repository directory, including everything the install command added to it.
- Each task runs on its own instance, starting from that copy.
A tool reaches your tasks only if the install command puts it inside your repository directory. The tool must also work on the image your task uses, so if your task uses the Ubuntu image, install a build that runs on both images.
The install command replaces the default dependency install, so it must also install your dependencies. In this example, the install command installs dependencies with pnpm, then runs a script that downloads ShellCheck:
vercel.json
{
"ci": {
"bootstrapping": {
"installCommand": "pnpm install --frozen-lockfile && sh scripts/install-ci-tools.sh",
"installEnv": {}
}
}
}
The script downloads ShellCheck into a .bin directory in your repository:
scripts/install-ci-tools.sh
set -eu
mkdir -p .bin
curl -fsSL https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz \
| tar -xJ --strip-components=1 -C .bin shellcheck-v0.11.0/shellcheck
Your tasks can then run the tool from that directory:
package.json
{
"scripts": {
"lint:shell": "./.bin/shellcheck scripts/*.sh"
}
}
- The install command runs from the root of your repository, or from your project's root directory if you've set one.
- Your tasks only receive files inside your repository. Files the install command writes anywhere else, like your home directory, aren't available to your tasks. This includes system packages that you install with
dnforapt-get. - When you set
ci.bootstrapping, you must also setci.bootstrapping.installEnv, even if it's empty. - Add
.binto your.gitignorefile so you don't commit the downloaded tool.
Testing against your deployments
A task can wait for the Vercel deployment of your commit, then send requests to it, for example to run end-to-end tests. Vercel CI authenticates those requests with an OpenID Connect (OIDC) token, so they work even when the deployment uses Deployment Protection.
For a complete Playwright example, see Running end-to-end tests.
Depend on a deployment
Add <package>#deployment to the task's dependsOn, and add the ci:oidc:deployments tag. In the example below, the test:e2e task in apps/web waits for the web package's deployment:
apps/web/turbo.json
{
"extends": ["//"],
"tasks": {
"test:e2e": {
"dependsOn": ["web#deployment"],
"tags": ["ci", "ci:oidc:deployments"],
"passThroughEnv": ["VERCEL_DEPLOYMENT_URLS"]
}
}
}
- Vercel CI resolves
web#deploymentto the Vercel project connected to your repository whose root directory is thewebpackage's directory. Exactly one project must match. - The task starts after that deployment succeeds. You don't need to define a
deploymenttask inturbo.json. - A task with
ci:oidc:deploymentsmust depend on its own package's deployment.
Vercel CI only treats <package>#deployment as a Vercel deployment when the package has no deployment script in its package.json. If the package has one, Vercel CI runs that script like any other task instead of waiting for the Vercel deployment. Tasks that depend on it don't receive VERCEL_DEPLOYMENT_URLS, and tasks with ci:oidc:deployments fail. To use deployment dependencies, rename the script.
Send requests to the deployment
Vercel CI gives the task these environment variables:
| Variable | Value |
|---|---|
VERCEL_DEPLOYMENT_URLS |
A JSON object that maps each package name to its deployment's hostname |
VERCEL_DEPLOYMENT_TARGETS |
A JSON object that maps each package name to production or preview |
Turborepo filters environment variables, so add the variables your task reads to its passThroughEnv, as shown in the example above.
When the task sends a request to its own package's deployment hostname, Vercel CI adds the OIDC token in the x-vercel-trusted-oidc-idp-token header. You don't need to handle the token yourself. The token isn't available in an environment variable, and Vercel CI doesn't send it to other hosts, including the deployment's aliases and custom domains.
The task also receives the environment variables of its deployment's project, limited to the variables its env and passThroughEnv allow.
Deployments built from the same repository and Vercel team trust Vercel CI automatically. For deployments from another repository, add a Trusted Sources rule for Vercel CI.
Call other projects
To send the token to production deployments of other projects on your team, add up to five ci:oidc:project:<project-id> tags alongside ci:oidc:deployments:
apps/web/turbo.json
{
"extends": ["//"],
"tasks": {
"test:e2e": {
"dependsOn": ["web#deployment"],
"tags": [
"ci",
"ci:oidc:deployments",
"ci:oidc:project:prj_123456789"
],
"passThroughEnv": ["VERCEL_DEPLOYMENT_URLS", "VERCEL_OIDC_PROJECT_URLS"]
}
}
}
VERCEL_OIDC_PROJECT_URLSmaps each project ID to the hostname of its current production deployment. Vercel CI only sends the token to that hostname.- Each project's production deployment must be ready. If it isn't, the task fails with a configuration error.
- A project built from another repository needs a Trusted Sources rule that trusts Vercel CI for production.
Turn OIDC off
Add ci:oidc:none to a task to turn OIDC off for that task. A task's ci:oidc tags take precedence over the ci:oidc tags in its package's top-level tags.
Activity