Deployment
This chapter describes how to deploy a project through the SDK, which is suitable for scenarios where the project is uploaded and published by the server. To preview and deploy directly in the sandbox, you can integrate the CLI into the sandbox. For details, see Deploy through the CLI.
Data Model
deployments.deploy, deployments.wait, and deployments.get return deployment objects. deployments.list and deployments.listAll return a collection of deployment objects. deployments.getLog returns only the build log URL.Field | Type | Required | Description |
deploymentId/deployment_id | string/str | Yes | Deployment ID |
projectId/project_id | string/str | Yes | Project ID |
env | string/str | Yes | Environment identifier string of the deployment environment. Built-in values are Production and Preview. It can also be a custom Slug created in the project, such as Staging. |
status | string/str | No | Deployment status. The final states are Success, Failed, Timeout, Cancelled, and Invalid. Before reaching a final state, the status is first Pending and then Process. |
previewUrl/preview_url | string/str | No | Preview URL. The address that can be opened in a browser is returned only by deployments.wait when the status is Success. |
code | number/int,float | No | Build exit code. 0 indicates success. |
createdOn/created_on | string/str | No | Creation time in ISO 8601 format |
modifiedOn/modified_on | string/str | No | Modification time in ISO 8601 format |
deployments.deploy
Start a deployment with the content to be deployed specified by
artifact. When env is exactly "Preview", the SDK first queries existing deployments to check whether a production environment deployment exists. If it does not exist, a ValidationError is thrown before artifacts are packaged, uploaded, or a deployment is created.By default, the SDK does not wait for deployment to complete. After uploading artifacts and successfully creating a deployment, the SDK returns the deployment ID, project ID, and environment identifier, but does not return an access URL. When
wait: true is passed (wait=True in Python), the SDK continues to wait until the deployment reaches a terminal state. Alternatively, you can call deployments.wait separately after obtaining the deployment ID. In TypeScript, a Promise is returned, and you can use await to wait for the result. In Python, the call returns after waiting completes or throws an exception if an error occurs.deployments.deploy supports only projects whose code source is direct upload (Provider is Upload). Projects created through projects.create belong to this type. Projects connected to Git repositories do not support uploading artifacts for deployment through this method.Parameter
Parameter | Type | Required | Description |
projectId/project_id | string/str | Yes | Project ID |
artifact | Artifact/dict | Yes | Content to Deploy |
env | string/str | No | Environment identifier string of the deployment environment. Defaults to "Production". |
wait | boolean/bool | No | Whether to wait for the deployment to reach a final state. Defaults to false. |
timeout | number/float | No | Maximum wait time, in seconds. Defaults to 900. |
pollInterval/poll_interval | number/float | No | Polling interval, in seconds. Defaults to 5. |
onUploadProgress/upload_progress | Callback | No | Triggered once after the content to deploy is uploaded. |
onStatusChange/status_change | Callback | No | Triggered when the deployment status changes. Takes effect only when wait is true. |
Return Value
Promise<Deployment>/dict contains only three fields when not waiting: deploymentId, projectId, and env. Other fields do not exist. The SDK does not make additional queries to populate these fields.
Examples
const deployment = await makers.deployments.deploy({projectId: "your-project-id",artifact: { files: { "index.html": "<h1>Hello</h1>" } },});console.log(deployment.deploymentId, deployment.env);
deployment = makers.deployments.deploy(project_id="your-project-id",artifact={"files": {"index.html": "<h1>Hello</h1>"}},)print(deployment["deployment_id"], deployment["env"])
Form of Content to Be Deployed
The three forms of
artifact are mutually exclusive. You can pass only one of them in each call.Form | Type | Description |
files | Record<string, string | Uint8Array>/dict[str, str | bytes] | Provide file content directly as key-value pairs, where the SDK packages it into a Zip file in memory or a temporary directory. Keys are relative POSIX paths, and values support text and binary content. |
directory | string/str | Local directory path, packaged into a Zip file by the SDK. |
archive | string/str | Local Zip file path, uploaded as-is after security validation is passed. |
There are three common types of values for
directory:1. The project root directory where the application source code resides, for example,
".".2. The directory of static build artifacts, for example,
"./dist". The root directory must contain index.html as the site entry point. Otherwise, a 404 error is returned when the site homepage is accessed. The SDK does not validate this. For more information, see Direct Upload.3. The artifact directory after
edgeone makers build is run locally, which is "./.edgeone".Examples
// The following four formats each correspond to one type of content to deploy. Use only one of them in an actual call.await makers.deployments.deploy({projectId: "your-project-id",artifact: { directory: "." },});// artifact: { directory: "./dist", excludePatterns: ["**/*.map"] }// artifact: { directory: "./.edgeone" }// artifact: { archive: "./site.zip" }
# The following four formats each correspond to one type of content to deploy. Use only one of them in an actual call.makers.deployments.deploy(project_id="your-project-id",artifact={"directory": "."},)# artifact={"directory": "./dist", "exclude_patterns": ["**/*.map"]}# artifact={"directory": "./.edgeone"}# artifact={"archive": "./site.zip"}
Packaging Rules
When
directory is passed in, the SDK packages it according to the following rules:By default, files and directories starting with a dot are ignored, except for
.well-known and .edgeone. Therefore, directories such as .git, .github, and .vscode, as well as the .env file, are also not included in the archive.By default, the following are also ignored:
node_modules at any level, .edgeone in the packaging root directory, files ending with .log, .tmp, .temp, .swp, or .swo, and .DS_Store, Thumbs.db, and desktop.ini.When packaging
"./.edgeone", the SDK retains node_modules and directories starting with a dot, but still excludes default ignore items such as .git, .env, log files, and temporary files. The archive is organized according to the EdgeOne CLI artifact layout. For other directories, the content is placed at the root of the archive.The SDK does not read
.gitignore. Default ignore items cannot be disabled and can only be extended through excludePatterns. This parameter uses POSIX glob semantics relative to the archive root directory and does not support negation rules starting with !.Symbolic links are rejected.
When
archive is passed in, the SDK validates the Zip content before uploading and rejects absolute paths, paths containing .. segments or backslashes, paths that are duplicated after normalization, and symbolic link entries. After validation passes, the archive is uploaded as is without repackaging.Progress Callback
onUploadProgress is triggered once after the content to be deployed is uploaded. onStatusChange is triggered when the deployment status is first queried and on every subsequent status change. On the first trigger, previousStatus is empty.The status change callback depends on the waiting process and is triggered only when
wait is passed as true. When wait is false, the SDK does not query the deployment status, so the callback is not invoked and no notification is provided. To receive status change events in this case, pass the callback to deployments.wait.Event | Field |
Upload progress event | uploadedBytes/uploaded_bytes,totalBytes/total_bytes,completedFiles/completed_files,totalFiles/total_files |
Status change event | deployment (current deployment object), previousStatus/previous_status (previous status, empty when the deployment is triggered for the first time) |
Note:
An exception thrown by a callback does not interrupt the deployment. If a
logger is passed in when Makers is initialized, the exception is reported by the logger. If no logger is passed in, the exception is ignored.Examples
const result = await makers.deployments.deploy({projectId: "your-project-id",artifact: { files: { "index.html": "<h1>Hello</h1>" } },wait: true,onUploadProgress: (event) => {console.log(event.uploadedBytes, event.totalBytes);},onStatusChange: (event) => {console.log(event.previousStatus, event.deployment.status);},});if (result.status === "Success") {console.log(result.previewUrl);}
result = makers.deployments.deploy(project_id="your-project-id",artifact={"files": {"index.html": "<h1>Hello</h1>"}},wait=True,upload_progress=lambda event: print(event["uploaded_bytes"], event["total_bytes"]),status_change=lambda event: print(event["previous_status"], event["deployment"]["status"]),)if result.get("status") == "Success":print(result.get("preview_url"))
deployments.wait
Polls the specified deployment until it reaches a terminal state. The terminal states are
Success, Failed, Timeout, Cancelled, and Invalid. By default, the maximum wait time is 15 minutes, with a poll every 5 seconds.A deployment failure is indicated by the returned
status, and no exception is thrown. An exception is thrown only when the local wait times out or the request itself fails.Parameter
Parameter | Type | Required | Description |
projectId/project_id | string/str | Yes | Project ID |
deploymentId/deployment_id | string/str | Yes | Deployment ID |
timeout | number/float | No | Maximum wait time, in seconds. Defaults to 900. |
pollInterval/poll_interval | number/float | No | Polling interval, in seconds. Defaults to 5. |
onStatusChange/status_change | Callback | No | Triggered when the deployment status changes. |
Return Value
Promise<Deployment>/dict — status is one of the terminal states. When status is Success, previewUrl is an accessible site URL.Note:
A
DeploymentTimeoutError is thrown when the wait times out. This exception only indicates that the local wait has stopped. The deployment on Makers continues, and the SDK does not cancel it.Examples
const result = await makers.deployments.wait({projectId: "your-project-id",deploymentId: "your-deployment-id",timeout: 900,pollInterval: 5,});if (result.status === "Success") {console.log(result.previewUrl);} else {console.error(result.status, result.code);}
result = makers.deployments.wait(project_id="your-project-id",deployment_id="your-deployment-id",timeout=900,poll_interval=5,)if result.get("status") == "Success":print(result.get("preview_url"))else:print(result.get("status"), result.get("code"))
deployments.get
Query the current information of a specified deployment without waiting for the deployment to complete. If no matching deployment is found, a
NotFoundError is thrown.Parameter
Parameter | Type | Required | Description |
projectId / project_id | string / str | Yes | Project ID |
deploymentId / deployment_id | string / str | Yes | Deployment ID |
Return Value
Promise<Deployment> / dict, containing information about the specified deployment.Examples
const deployment = await makers.deployments.get({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(deployment.deploymentId, deployment.status);
deployment = makers.deployments.get(project_id="your-project-id",deployment_id="your-deployment-id",)print(deployment["deployment_id"], deployment.get("status"))
deployments.list
List deployments of a specified project with pagination.
Parameter
Parameter | Type | Required | Description |
projectId/project_id | string/str | Yes | Project ID |
status | string[]/list[str] | No | Filter by deployment status |
timeRange/time_range | { start, end }/dict | No | Filter by creation time. The start and end times must be in ISO 8601 format. |
repoBranch/repo_branch | string[]/list[str] | No | Filter by code branch |
page | number/int | No | Page number, starting from 0, default 0 |
pageSize/page_size | number/int | No | Number of items per page, ranging from 1 to 100, default 20 |
order.field | string/str | No | Sorting field. Values differ between the two languages. For TypeScript, the value is "createdOn" or "modifiedOn"; for Python, the value is "created_on" or "modified_on". |
order.direction | "asc" | "desc" | No | Sort direction |
Return Value
Promise<Page<Deployment>>/dict contains five fields: items, page, pageSize / page_size, total, and hasNext / has_next. Page numbers start from 0.Examples
const page = await makers.deployments.list({projectId: "your-project-id",page: 0,pageSize: 20,order: { field: "createdOn", direction: "desc" },});console.log(page.total, page.hasNext);for (const deployment of page.items) {console.log(deployment.deploymentId, deployment.status);}
page = makers.deployments.list(project_id="your-project-id",page=0,page_size=20,order={"field": "created_on", "direction": "desc"},)print(page["total"], page["has_next"])for deployment in page["items"]:print(deployment["deployment_id"], deployment["status"])
deployments.listAll / deployments.list_all
Iterate over deployments of a specified project. The SDK automatically paginates from page 0 and returns deployment objects one by one.
Parameter
The parameters are the same as those of
deployments.list, except that page is not accepted. projectId / project_id is required. The meanings and default values of the filtering, sorting, and pageSize / page_size parameters are consistent with those of deployments.list.pageSize / page_size controls the number of results per query and does not limit the total number of results returned during iteration.Return Value
TypeScript returns
AsyncIterable<Deployment>, which can be iterated using for await...of. Python returns Iterator[dict[str, Any]], which can be iterated using for. Each iteration yields a deployment object.Examples
for await (const deployment of makers.deployments.listAll({projectId: "your-project-id",pageSize: 20,order: { field: "createdOn", direction: "desc" },})) {console.log(deployment.deploymentId, deployment.status);}
for deployment in makers.deployments.list_all(project_id="your-project-id",page_size=20,order={"field": "created_on", "direction": "desc"},):print(deployment["deployment_id"], deployment.get("status"))
deployments.getLog / deployments.get_log
Get the build log URL of a specified deployment. This method returns an object containing the log URL and does not download or return the log content.
Parameter
Parameter | Type | Required | Description |
projectId / project_id | string / str | Yes | Project ID |
deploymentId / deployment_id | string / str | Yes | Deployment ID |
Return Value
Promise<{ logUrl: string }> / dict. The log URL field is logUrl in TypeScript and log_url in Python. If the server does not return a log URL, this field is an empty string.Examples
const result = await makers.deployments.getLog({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(result.logUrl);
result = makers.deployments.get_log(project_id="your-project-id",deployment_id="your-deployment-id",)print(result["log_url"])