Vercel Terraform Provider

The vercel_bulk_redirects resource manages the live, project-level bulk redirects for a Vercel project.

Important Behavior: Each Terraform apply stages the entire configured set of redirects and promotes that version to production. This means the redirects attribute represents the full, complete set of redirects you want active for the project; you cannot use this resource to incrementally add single redirects without defining the existing ones in your configuration.

resource "vercel_project" "example" {
  name = "example-project"
}

resource "vercel_bulk_redirects" "example" {
  project_id = vercel_project.example.id

  redirects = [
    {
      source                = "/old-path"
      destination           = "/new-path"
      status_code           = 307
      case_sensitive        = false
      query                 = false
    },
    {
      source                = "/blog"
      destination           = "https://example.com/blog"
      status_code           = 308
      case_sensitive        = true
      query                 = true
    },
  ]
}

The vercel_feature_flag_sdk_key resource allows you to create and manage project-scoped, environment-specific SDK keys for Vercel Feature Flags.

Important Security Note: Vercel only returns the cleartext sdk_key and the connection_string at the moment of creation. Because subsequent reads from the Vercel API omit these sensitive values, this Terraform resource is designed to preserve the existing sensitive values in your Terraform state during later refreshes/reads.

resource "vercel_project" "example" {
  name = "feature-flag-sdk-key-example"
}

resource "vercel_feature_flag_sdk_key" "example" {
  project_id  = vercel_project.example.id
  environment = "production"
  type        = "server"
  label       = "backend-sdk"
}

resource "vercel_project_environment_variable" "example" {
  project_id = vercel_project.example.id
  target     = ["production"]
  sensitive  = true
  key        = "FLAGS_CONNECTION_STRING"
  value      = vercel_feature_flag_sdk_key.example.connection_string
}

A vercel_project_protection_bypass resource creates an automation bypass token. This token allows automation services (like CI/CD pipelines) to bypass Deployment Protection on a vercel_project by providing the token in the x-vercel-protection-bypass HTTP header.

Key Behaviors

• Multiple Bypasses: You can create multiple bypasses per project.
• Environment Variable Exposure: Exactly one bypass per project can have is_env_var = true. This bypass is automatically exposed as the VERCEL_AUTOMATION_BYPASS_SECRET environment variable on deployments.
• Automatic Promotion/Demotion: If you set is_env_var = true on a new bypass, Vercel automatically demotes the previous default bypass.
• Default Requirement: Vercel requires exactly one default bypass per project. If a bypass is the only one on a project, it is automatically treated as the default. Setting is_env_var = false on a solo bypass is invalid.

resource "vercel_project" "example" {
  name = "example-project"
}

# A bypass for a CI pipeline. Because this is the first bypass on the project,
# Vercel automatically marks it as the env-var default (is_env_var = true),
# and the secret is exposed as VERCEL_AUTOMATION_BYPASS_SECRET on deployments.
resource "vercel_project_protection_bypass" "ci" {
  project_id = vercel_project.example.id
  note       = "ci pipeline"
}

# A second bypass for QA, with a caller-supplied secret.
resource "vercel_project_protection_bypass" "qa" {
  project_id = vercel_project.example.id
  note       = "preview QA"
  secret     = "abcdefghijklmnopqrstuvwxyz123456"
}

The vercel_deployment resource creates a Deployment for a Vercel Project. A Deployment is the result of building a Project and making it available via a live URL. Once the build step completes, a new, immutable deployment is available at a preview URL.

Deployment Strategies

Depending on your workflow, you can deploy in three ways:

1. File-based Deployment: Uploading specific files using vercel_file or vercel_project_directory data sources. This is required if git_source is not set.
2. Git-based Deployment: Deploying a specific branch or commit hash (ref) for projects connected to a Git repository.
3. Prebuilt Deployment: Uploading the output of a pre-existing build process.

Best Practices

• Layering: If you manage both preview and production deployments, consider 'layering' your Terraform by creating the vercel_project in one configuration and the vercel_deployment in another.
• Retention: Deployments are retained indefinitely by default. To hard delete a deployment when the Terraform resource is destroyed, set delete_on_destroy = true. Note that deleted deployments are not recoverable.

# Example: File-based deployment
data "vercel_project_directory" "files_example" {
  path = "../ui"
}

data "vercel_project" "files_example" {
  name = "my-awesome-project"
}

resource "vercel_deployment" "files_example" {
  project_id  = data.vercel_project.files_example.id
  files       = data.vercel_project_directory.files_example.files
  path_prefix = data.vercel_project_directory.files_example.path
  production  = true

  environment = {
    FOO = "bar"
  }
}

The vercel_project_route resource manages a single live project-level routing rule for a Vercel project.

Key Behaviors

• Immediate Promotion: Each mutation stages a new routing-rules version and promotes it immediately. This ensures Terraform state reflects actual production traffic behavior.
• Targeting: Reads and imports target the live version and ignore unpublished staged drafts created outside of Terraform.
• Ordering: Use the position block to control rule placement. For deterministic ordering across multiple rules, use before or after in conjunction with reference_route_id.
• Constraint: This resource will refuse to mutate a project if it currently has an unpublished staged routing-rules version. You must publish, restore, or discard the existing draft before using this resource.

Important Note on Position

The Vercel API does not return placement metadata for individual rules. While Terraform preserves the configured position during normal reads, imported routes will start with no position in the state.

resource "vercel_project_route" "example" {
	project_id = vercel_project.example.id
	name       = "redirect-legacy-docs"
	position = {
		placement = "start"
	}
	route = {
		src    = "/docs/:path*"
		dest   = "/guides/:path*"
		status = 308
	}
}