Skip to content
Cloudflare API
Start here
API Reference
Pages
Projects
Deployments

Create deployment

pages.projects.deployments.create(strproject_name, DeploymentCreateParams**kwargs) -> Deployment
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
account_id: str

Identifier.

maxLength32
project_name: str

Name of the project.

_headers: Optional[FileTypes]

Headers configuration file for the deployment.

_redirects: Optional[FileTypes]

Redirects configuration file for the deployment.

_routes_json: Optional[FileTypes]

Routes configuration file defining routing rules.

_worker_bundle: Optional[FileTypes]

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.

_worker_js: Optional[FileTypes]

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

branch: Optional[str]

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: Optional[Literal["true", "false"]]

Boolean string indicating if the working directory has uncommitted changes.

One of the following:
"true"
"false"
commit_hash: Optional[str]

Git commit SHA associated with this deployment.

commit_message: Optional[str]

Git commit message associated with this deployment.

functions_filepath_routing_config_json: Optional[FileTypes]

Functions routing configuration file.

manifest: Optional[str]

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: Optional[str]

The build output directory path.

wrangler_config_hash: Optional[str]

Hash of the Wrangler configuration file used for this deployment.

ReturnsExpand Collapse
class Deployment: …
id: str

Id of the deployment.

aliases: Optional[List[str]]

A list of alias URLs pointing to this deployment.

build_config: BuildConfig

Configs for the project build process.

web_analytics_tag: Optional[str]

The classifying tag for analytics.

web_analytics_token: Optional[str]

The auth token for analytics.

build_caching: Optional[bool]

Enable build caching for the project.

build_command: Optional[str]

Command used to build project.

destination_dir: Optional[str]

Assets output directory of the build.

root_dir: Optional[str]

Directory to run the command.

created_on: datetime

When the deployment was created.

formatdate-time
deployment_trigger: DeploymentTrigger

Info about what caused the deployment.

metadata: DeploymentTriggerMetadata

Additional info about the trigger.

branch: str

Where the trigger happened.

commit_dirty: bool

Whether the deployment trigger commit was dirty.

commit_hash: str

Hash of the deployment trigger commit.

commit_message: str

Message of the deployment trigger commit.

type: Literal["github:push", "ad_hoc", "deploy_hook"]

What caused the deployment.

One of the following:
"github:push"
"ad_hoc"
"deploy_hook"
env_vars: Optional[Dict[str, Optional[EnvVars]]]

Environment variables used for builds and Pages Functions.

One of the following:
class EnvVarsPagesPlainTextEnvVar: …

A plaintext environment variable.

type: Literal["plain_text"]
value: str

Environment variable value.

class EnvVarsPagesSecretTextEnvVar: …

An encrypted environment variable.

type: Literal["secret_text"]
value: str

Secret value.

environment: Literal["preview", "production"]

Type of deploy.

One of the following:
"preview"
"production"
is_skipped: bool

If the deployment has been skipped.

latest_stage: Stage

The status of the deployment.

ended_on: Optional[datetime]

When the stage ended.

formatdate-time
name: Literal["queued", "initialize", "clone_repo", 2 more]

The current build stage.

One of the following:
"queued"
"initialize"
"clone_repo"
"build"
"deploy"
started_on: Optional[datetime]

When the stage started.

formatdate-time
status: Literal["success", "idle", "active", 2 more]

State of the current stage.

One of the following:
"success"
"idle"
"active"
"failure"
"canceled"
modified_on: datetime

When the deployment was last modified.

formatdate-time
project_id: str

Id of the project.

project_name: str

Name of the project.

short_id: str

Short Id (8 character) of the deployment.

source: Source

Configs for the project source control.

config: SourceConfig
Deprecateddeployments_enabled: bool
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: str

The owner of the repository.

owner_id: str

The owner ID of the repository.

path_excludes: List[str]

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

path_includes: List[str]

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

pr_comments_enabled: bool

Whether to enable PR comments.

preview_branch_excludes: List[str]

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: List[str]

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: Literal["all", "none", "custom"]

Controls whether commits to preview branches trigger a preview deployment.

One of the following:
"all"
"none"
"custom"
production_branch: str

The production branch of the repository.

production_deployments_enabled: bool

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

repo_id: str

The ID of the repository.

repo_name: str

The name of the repository.

type: Literal["github", "gitlab"]

The source control management provider.

One of the following:
"github"
"gitlab"
stages: List[Stage]

List of past stages.

ended_on: Optional[datetime]

When the stage ended.

formatdate-time
name: Literal["queued", "initialize", "clone_repo", 2 more]

The current build stage.

One of the following:
"queued"
"initialize"
"clone_repo"
"build"
"deploy"
started_on: Optional[datetime]

When the stage started.

formatdate-time
status: Literal["success", "idle", "active", 2 more]

State of the current stage.

One of the following:
"success"
"idle"
"active"
"failure"
"canceled"
url: str

The live URL to view this deployment.

uses_functions: Optional[bool]

Whether the deployment uses functions.

Create deployment

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
deployment = client.pages.projects.deployments.create(
    project_name="this-is-my-project-01",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(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
}