Automate ESA deployments with Yunxiao Flow CI/CD-Edge Security Acceleration(ESA)-阿里云帮助中心

Overview

Yunxiao Flow is a CI/CD service that automates builds, tests, and deployments. ESA CLI is a command-line tool from ESA for creating Pages projects, uploading files, and managing versions.

Integrating ESA CLI into Yunxiao Flow automates the following:

A code push triggers the pipeline build and deployment.
The pipeline uploads build artifacts to ESA via ESA CLI, generating a new site version.
The new version is automatically deployed and published.

Prerequisites

Prepare an AccessKey

Creating Pages with the CLI requires an AccessKey to authorize site operations on your ESA account. Because an Alibaba Cloud account AccessKey grants full access to all resources, we recommend creating a RAM user with only the minimum required permissions to reduce security risk.

Log on to the RAM console with a RAM administrator account.
In the left-side navigation pane, choose Identities > Users. On the Users page, click Create User.
Enter a logon name for the RAM user, such as esa-cli. Select Use permanent AccessKey to access to automatically create an AccessKey. Click OK.
Click Copy to save the AccessKey ID and AccessKey Secret of the RAM user.
On the Users page, find the new RAM user and click Add Permissions in the Actions column to grant the RAM user permissions for ESA.
On the Grant Permissions panel, search for ESA in the policy list. Select AliyunESAFullAccess from the results and click Grant permissions.

Enable Yunxiao Flow

Go to the Flow console .
On first use, follow the prompts to enable the service.

Configure ESA CLI in Yunxiao Flow

Create a Node.js pipeline

Go to the Flow console .
Click Create Pipeline, select the Node.js template, and then click Create with the default Visual Editor option (Node.js · Test and Build) in the right panel.

Add a pipeline source

On the Process Configuration page, click Add Pipeline Source under the Build sub-step.
Select GitHub as the code source in the right-side panel, and then click Add Service Connection.
On the Create Service Connection page, click Create. You are redirected to the GitHub login page. Sign in and click Authorize Alicloud-DevOps.
After authorization, select your code repository and click Add.

Configure the Node.js environment

On the Process Configuration page, click Node.js Build under the Build sub-step.
In the right panel, click Edit > Task Steps > Install Node Environment and set the Node.js version for your project.
In the right panel, click Edit > Task Steps > Upload Build Artifact, and then click the button on the right to remove this step.

Configure build commands

In the right panel, click Edit > Task Steps > Run Commands and enter the following commands in the Run Commands field:

npm install && npm run build
npm i esa-cli@latest -g
esa-cli login
esa-cli deploy --name project_name --assets ./dist  # ./dist is an example. Replace it with the actual static artifact directory for your framework

In the right panel, click Edit > Task Steps > Run Commands, click Add next to Environment Variables, and then select Custom Parameter.
Add the following two environment variables:
- ESA_ACCESS_KEY_ID: The AccessKey ID from Prepare an AccessKey.
- ESA_ACCESS_KEY_SECRET: The AccessKey Secret from Prepare an AccessKey.
Click Run and Save.

Complete CI/CD workflow

Once configured, the workflow runs as follows:

Push code: Push code changes to the target branch in your Yunxiao repository.
Trigger pipeline: Yunxiao Flow detects the push and runs the pipeline.
Build stage: The pipeline runs the build commands and generates artifacts in the output directory.
Deploy stage: The pipeline installs and logs in to ESA CLI and deploys the artifacts to your ESA site.

Verify the deployment

After deployment, verify the result:

On the Yunxiao Flow pipeline homepage, check the latest run. A green build icon indicates success.
Click the pipeline name to open the pipeline details, and then click Logs on the build component.
In the log details, select Run Commands from the dropdown to find the temporary access URL generated by a successful build. Open it to verify the deployed content.

Note
This link expires after one hour. Bind a custom domain for production use.

Troubleshooting

ESA CLI login fails with an authentication error

Possible causes:

The AccessKey ID or AccessKey Secret is incorrect. Verify the credentials.
The RAM user lacks the AliyunESAFullAccess policy. Verify permissions in the RAM console.
The AccessKey is disabled or deleted. Check its status in the RAM console.

Resolution: Reconfigure the AccessKey in Yunxiao credential management. Ensure the RAM user has the required ESA permissions.

Deployment fails because the site is not found or permissions are insufficient

Possible causes:

The RAM user has only read permissions and lacks deployment permissions. Grant the AliyunESAFullAccess policy or a custom policy with version management and deployment permissions.

Build stage fails

Troubleshooting steps:

Check the build logs in the pipeline run details to identify the specific step that failed.
Verify the nodeVersion matches your project's Node.js version requirement.
Verify the build artifact path (./dist) matches your project's output directory. Default directories vary by framework — Vue uses dist/, Angular uses dist/<project-name>/.