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 | "Production" | "Preview" | Yes | Deployment environment, corresponding to the production environment and preview environment respectively. |
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 | string/str | No | Error code when deployment fails |
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. If env is set to "Preview" and the project has no production deployment, a ValidationError is thrown before the request is sent.By default, the method does not wait for the deployment to complete. It returns immediately after a successful call, and the returned result does not contain a preview link. To obtain a preview link, you can pass
wait as true, or call deployments.wait separately after the call returns. The waiting process is synchronous and blocking, and the method does not return until the deployment reaches a terminal state or the wait times out.Parameter
Parameter | Type | Required | Description |
projectId/project_id | string/str | Yes | Project ID |
artifact | Artifact/dict | Yes | Content to Deploy |
env | "Production" | "Preview" | No | Deployment environment. When set to "Preview", a production environment deployment is required for the project. 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, .env, .github, and .vscode 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
"./.edgeone" is packaged, the ignore rules are different: only .git is ignored, while node_modules and directories starting with a dot are retained. In this case, the packaging follows the EdgeOne CLI artifact layout, and the contents of other directories are placed in the root directory of the archive.The SDK does not read
.gitignore. Default ignore items cannot be disabled and can only be appended through excludePatterns/exclude_patterns. 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 archive contents before upload and rejects archives containing absolute paths, duplicate paths, or symbolic link entries. After validation passes, the archive is uploaded as-is without repackaging.Progress Callback
onUploadProgress/upload_progress is triggered once after the content to deploy is uploaded. onStatusChange/status_change is triggered when the deployment status is queried for the first time and each time the status changes thereafter. On the first trigger, previousStatus/previous_status 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/preview_url is the 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",timeoutMs: 900000,pollIntervalMs: 5000,});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.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
List all deployments of a specified project. The filtering and sorting parameters are the same as those of
deployments.list, but the page parameter is not accepted.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 |
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
AsyncIterable<Deployment>/Iterator[dict] is paginated automatically by the SDK.
Examples
for await (const deployment of makers.deployments.listAll({projectId: "your-project-id",})) {console.log(deployment.deploymentId, deployment.status);}
for deployment in makers.deployments.list_all(project_id="your-project-id"):print(deployment["deployment_id"], deployment["status"])
deployments.get
Query a single deployment by project ID and deployment ID. If the deployment does not exist, 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 — The previewUrl/preview_url field is not signed. To obtain an accessible site URL, use deployments.wait.
Examples
const deployment = await makers.deployments.get({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(deployment.status, deployment.env);
deployment = makers.deployments.get(project_id="your-project-id",deployment_id="your-deployment-id",)print(deployment["status"], deployment["env"])
deployments.getLog / deployments.get_log
Query the build log URL of a specified deployment.
Parameter
Parameter | Type | Required | Description |
projectId/project_id | string/str | Yes | Project ID |
deploymentId/deployment_id | string/str | Yes | Deployment ID |
Return Value
Promise<GetLogResult>/dict contains only logUrl/log_url.
Examples
const { logUrl } = await makers.deployments.getLog({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(logUrl);
result = makers.deployments.get_log(project_id="your-project-id",deployment_id="your-deployment-id",)print(result["log_url"])
