Create deployment

client.pages.projects.deployments.create(, , ?): Deployment { id, aliases, build_config, 14 more }

POST/accounts/{account_id}/pages/projects/{project_name}/deployments

Start a new deployment from production. The repository and account must have already been authorized on the Cloudflare Pages dashboard.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Pages Write

ParametersExpand Collapse

projectName: string

Name of the project.

params: DeploymentCreateParams { account_id, _headers, _redirects, 11 more }

account_id: string

Path param: Identifier.

maxLength32

_headers?: Uploadable

Body param: Headers configuration file for the deployment.

_redirects?: Uploadable

Body param: Redirects configuration file for the deployment.

_routesJson?: Uploadable

Body param: Routes configuration file defining routing rules.

_workerBundle?: Uploadable

Body param: Worker bundle file in multipart/form-data format. Mutually exclusive with _worker.js. Cannot specify both _worker.js and _worker.bundle in the same request. Maximum size: 25 MiB.

_workerJS?: Uploadable

Body param: Worker JavaScript file. Mutually exclusive with _worker.bundle. Cannot specify both _worker.js and _worker.bundle in the same request.

branch?: string

Body param: The branch to build the new deployment from. The HEAD of the branch will be used. If omitted, the production branch will be used by default.

commit_dirty?: "true" | "false"

Body param: Boolean string indicating if the working directory has uncommitted changes.

One of the following:

"true"

"false"

commit_hash?: string

Body param: Git commit SHA associated with this deployment.

commit_message?: string

Body param: Git commit message associated with this deployment.

functionsFilepathRoutingConfigJson?: Uploadable

Body param: Functions routing configuration file.

manifest?: string

Body param: JSON string containing a manifest of files to deploy. Maps file paths to their content hashes. Required for direct upload deployments. Maximum 20,000 entries.

pages_build_output_dir?: string

Body param: The build output directory path.

wrangler_config_hash?: string

Body param: Hash of the Wrangler configuration file used for this deployment.

ReturnsExpand Collapse

Deployment { id, aliases, build_config, 14 more }

id: string

Id of the deployment.

aliases: Array<string> | null

A list of alias URLs pointing to this deployment.

build_config: BuildConfig { web_analytics_tag, web_analytics_token, build_caching, 3 more }

Configs for the project build process.

web_analytics_tag: string | null

The classifying tag for analytics.

web_analytics_token: string | null

The auth token for analytics.

build_caching?: boolean | null

Enable build caching for the project.

build_command?: string | null

Command used to build project.

destination_dir?: string | null

Assets output directory of the build.

root_dir?: string | null

Directory to run the command.

created_on: string

When the deployment was created.

formatdate-time

deployment_trigger: DeploymentTrigger { metadata, type }

Info about what caused the deployment.

metadata: Metadata { branch, commit_dirty, commit_hash, commit_message }

Additional info about the trigger.

branch: string

Where the trigger happened.

commit_dirty: boolean

Whether the deployment trigger commit was dirty.

commit_hash: string

Hash of the deployment trigger commit.

commit_message: string

Message of the deployment trigger commit.

type: "github:push" | "ad_hoc" | "deploy_hook"

What caused the deployment.

One of the following:

"github:push"

"ad_hoc"

"deploy_hook"

env_vars: Record<string, PagesPlainTextEnvVar { type, value } | null | PagesSecretTextEnvVar { type, value } | null> | null

Environment variables used for builds and Pages Functions.

One of the following:

PagesPlainTextEnvVar { type, value }

A plaintext environment variable.

type: "plain_text"

value: string

Environment variable value.

PagesSecretTextEnvVar { type, value }

An encrypted environment variable.

type: "secret_text"

value: string

Secret value.

environment: "preview" | "production"

Type of deploy.

One of the following:

"preview"

"production"

is_skipped: boolean

If the deployment has been skipped.

latest_stage: Stage { ended_on, name, started_on, status }

The status of the deployment.

ended_on: string | null

When the stage ended.

formatdate-time

name: "queued" | "initialize" | "clone_repo" | 2 more

The current build stage.

One of the following:

"queued"

"initialize"

"clone_repo"

"build"

"deploy"

started_on: string | null

When the stage started.

formatdate-time

status: "success" | "idle" | "active" | 2 more

State of the current stage.

One of the following:

"success"

"idle"

"active"

"failure"

"canceled"

modified_on: string

When the deployment was last modified.

formatdate-time

project_id: string

Id of the project.

project_name: string

Name of the project.

short_id: string

Short Id (8 character) of the deployment.

source: Source { config, type }

Configs for the project source control.

config: Config { deployments_enabled, owner, owner_id, 10 more }

Deprecateddeployments_enabled: boolean

Use `production_deployments_enabled` and `preview_deployment_setting` for more granular control.

Whether to enable automatic deployments when pushing to the source repository. When disabled, no deployments (production or preview) will be triggered automatically.

owner: string

The owner of the repository.

owner_id: string

The owner ID of the repository.

path_excludes: Array<string>

A list of paths that should be excluded from triggering a preview deployment. Wildcard syntax (*) is supported.

path_includes: Array<string>

A list of paths that should be watched to trigger a preview deployment. Wildcard syntax (*) is supported.

pr_comments_enabled: boolean

Whether to enable PR comments.

preview_branch_excludes: Array<string>

A list of branches that should not trigger a preview deployment. Wildcard syntax (*) is supported. Must be used with preview_deployment_setting set to custom.

preview_branch_includes: Array<string>

A list of branches that should trigger a preview deployment. Wildcard syntax (*) is supported. Must be used with preview_deployment_setting set to custom.

preview_deployment_setting: "all" | "none" | "custom"

Controls whether commits to preview branches trigger a preview deployment.

One of the following:

"all"

"none"

"custom"

production_branch: string

The production branch of the repository.

production_deployments_enabled: boolean

Whether to trigger a production deployment on commits to the production branch.

repo_id: string

The ID of the repository.

repo_name: string

The name of the repository.

type: "github" | "gitlab"

The source control management provider.

One of the following:

"github"

"gitlab"

stages: Array<Stage { ended_on, name, started_on, status } >

List of past stages.

ended_on: string | null

When the stage ended.

formatdate-time

name: "queued" | "initialize" | "clone_repo" | 2 more

The current build stage.

One of the following:

"queued"

"initialize"

"clone_repo"

"build"

"deploy"

started_on: string | null

When the stage started.

formatdate-time

status: "success" | "idle" | "active" | 2 more

State of the current stage.

One of the following:

"success"

"idle"

"active"

"failure"

"canceled"

url: string

The live URL to view this deployment.

uses_functions?: boolean | null

Whether the deployment uses functions.

Create deployment

import fs from 'fs';
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const deployment = await client.pages.projects.deployments.create('this-is-my-project-01', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

console.log(deployment.id);

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
    "aliases": [
      "https://branchname.projectname.pages.dev"
    ],
    "build_config": {
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x",
      "build_caching": true,
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/"
    },
    "created_on": "2021-03-09T00:55:03.923456Z",
    "deployment_trigger": {
      "metadata": {
        "branch": "main",
        "commit_dirty": false,
        "commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
        "commit_message": "Update index.html"
      },
      "type": "ad_hoc"
    },
    "env_vars": {
      "foo": {
        "type": "plain_text",
        "value": "hello world"
      }
    },
    "environment": "preview",
    "is_skipped": true,
    "latest_stage": {
      "ended_on": "2021-03-09T00:58:59.045655Z",
      "name": "deploy",
      "started_on": "2021-03-09T00:55:03.923456Z",
      "status": "success"
    },
    "modified_on": "2021-03-09T00:58:59.045655Z",
    "project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "project_name": "this-is-my-project-01",
    "short_id": "f64788e9",
    "source": {
      "config": {
        "deployments_enabled": true,
        "owner": "my-org",
        "owner_id": "12345678",
        "path_excludes": [
          "string"
        ],
        "path_includes": [
          "string"
        ],
        "pr_comments_enabled": true,
        "preview_branch_excludes": [
          "string"
        ],
        "preview_branch_includes": [
          "string"
        ],
        "preview_deployment_setting": "all",
        "production_branch": "main",
        "production_deployments_enabled": true,
        "repo_id": "12345678",
        "repo_name": "my-repo"
      },
      "type": "github"
    },
    "stages": [
      {
        "ended_on": "2021-06-03T15:39:03.134378Z",
        "name": "queued",
        "started_on": "2021-06-03T15:38:15.608194Z",
        "status": "active"
      },
      {
        "ended_on": null,
        "name": "initialize",
        "started_on": null,
        "status": "idle"
      },
      {
        "ended_on": null,
        "name": "clone_repo",
        "started_on": null,
        "status": "idle"
      },
      {
        "ended_on": null,
        "name": "build",
        "started_on": null,
        "status": "idle"
      },
      {
        "ended_on": null,
        "name": "deploy",
        "started_on": null,
        "status": "idle"
      }
    ],
    "url": "https://f64788e9.ninjakittens.pages.dev",
    "uses_functions": true
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "id": "f64788e9-fccd-4d4a-a28a-cb84f88f6",
    "aliases": [
      "https://branchname.projectname.pages.dev"
    ],
    "build_config": {
      "web_analytics_tag": "cee1c73f6e4743d0b5e6bb1a0bcaabcc",
      "web_analytics_token": "021e1057c18547eca7b79f2516f06o7x",
      "build_caching": true,
      "build_command": "npm run build",
      "destination_dir": "build",
      "root_dir": "/"
    },
    "created_on": "2021-03-09T00:55:03.923456Z",
    "deployment_trigger": {
      "metadata": {
        "branch": "main",
        "commit_dirty": false,
        "commit_hash": "ad9ccd918a81025731e10e40267e11273a263421",
        "commit_message": "Update index.html"
      },
      "type": "ad_hoc"
    },
    "env_vars": {
      "foo": {
        "type": "plain_text",
        "value": "hello world"
      }
    },
    "environment": "preview",
    "is_skipped": true,
    "latest_stage": {
      "ended_on": "2021-03-09T00:58:59.045655Z",
      "name": "deploy",
      "started_on": "2021-03-09T00:55:03.923456Z",
      "status": "success"
    },
    "modified_on": "2021-03-09T00:58:59.045655Z",
    "project_id": "7b162ea7-7367-4d67-bcde-1160995d5",
    "project_name": "this-is-my-project-01",
    "short_id": "f64788e9",
    "source": {
      "config": {
        "deployments_enabled": true,
        "owner": "my-org",
        "owner_id": "12345678",
        "path_excludes": [
          "string"
        ],
        "path_includes": [
          "string"
        ],
        "pr_comments_enabled": true,
        "preview_branch_excludes": [
          "string"
        ],
        "preview_branch_includes": [
          "string"
        ],
        "preview_deployment_setting": "all",
        "production_branch": "main",
        "production_deployments_enabled": true,
        "repo_id": "12345678",
        "repo_name": "my-repo"
      },
      "type": "github"
    },
    "stages": [
      {
        "ended_on": "2021-06-03T15:39:03.134378Z",
        "name": "queued",
        "started_on": "2021-06-03T15:38:15.608194Z",
        "status": "active"
      },
      {
        "ended_on": null,
        "name": "initialize",
        "started_on": null,
        "status": "idle"
      },
      {
        "ended_on": null,
        "name": "clone_repo",
        "started_on": null,
        "status": "idle"
      },
      {
        "ended_on": null,
        "name": "build",
        "started_on": null,
        "status": "idle"
      },
      {
        "ended_on": null,
        "name": "deploy",
        "started_on": null,
        "status": "idle"
      }
    ],
    "url": "https://f64788e9.ninjakittens.pages.dev",
    "uses_functions": true
  },
  "success": true
}