Flow-CLI step subcommand

Download and install

For example, on macOS, run the following command to download Flow-CLI and make it executable.

curl https://rdc-plugin-storage.oss-cn-beijing.aliyuncs.com/flow-cli/1.0/darwin_arm64_flow_cli -o /usr/local/bin/flow && chmod +x /usr/local/bin/flow

Running flow -v outputs version information, indicating a successful installation.

root@test-01:~# flow -v
Flow version 1.0

Log in to Flow

1. Run the following command to log in to Flow.

   flow login

2. A browser window opens the Alibaba Cloud DevOps Flow login page. If you are already logged in, a success message appears. After a successful login, the command line prompts you to select an organization. Enter the number for your organization to continue.

   → step step login
   Hi [Username]! You've successfully authenticated.
   Please select an organization to continue:
   [0] xxx
   [1] xxx
   [2] xxx
   [3] [Username]'s enterprise
   [4] xxx's enterprise
   [5] xxx
   [6] xxx
   [7] xxx test enterprise
   [8] xxx enterprise
   [9] xxx enterprise
   [10] xxx
   [11] xxx enterprise
   [12] [Organization Name]
   3
   Yor're now at organization: [Username]'s enterprise

Create a step

In Alibaba Cloud DevOps Flow, an image that runs in a pipeline is called a "step." A step is the smallest runnable unit, consisting of a descriptive YAML file and a Docker image. The YAML file defines the step's input parameters, while the Docker image provides its runtime environment.

1. Run the following command to create a new step. Replace <your-step-sign> with your own step sign.

   The step sign must be unique across Alibaba Cloud DevOps. If the sign is already in use by another step, the creation will fail.

   flow step init <your-step-sign>

2. This command creates the following file structure in your local directory:

   .step
     |- ..
     |- entry.sh               # The base script required for the step
   <your-step-sign>
     |- Dockerfile             # Used to build the step image
     |- step.sh                # The script to be executed by the step
     |- step.yaml              # The YAML file that describes all information about the step

   • entry.sh: The base entrypoint script for step execution. You do not need to modify this file in most cases.

   • step.yaml: Defines the input parameters for the step, including the image repository URL for the step's runtime environment and the configuration parameters required when adding the step to a pipeline.

   • step.sh: The script that runs when the step is executed. In this script, you can access environment variables from the pipeline context, retrieve parameters defined in step.yaml, and implement your custom logic.

   • Dockerfile: The Dockerfile used to build the step's image. When you publish the step, this file is used to build the environment image, which is then pushed to the image repository URL specified in step.yaml.

3. Modify the initialized files.

   After you configure and publish a custom step, when a pipeline executes that step, the system first pulls the image from your specified image repository URL and then runs your defined script within that environment.

   The following sections describe the purpose of these three key files.

   • The step.yaml file defines the step descriptions:

     ---
     name: Custom step              # Step name
     sign: <your-step-sign>      # Unique step identifier
     description: My first step   # Step description
     image: <docker-image-url>   # Runtime environment image for the step
     items:                      # Input parameter form
       - label: Command
         name: command
         type: shell
         value: |
           # input your command here
           echo hello,world!
       - label: Parameter abc
         name: abc
         type: input

     The image field specifies the URL of the step's environment image. You must provide your own image repository URL. When you publish the step, an image is built from the Dockerfile and pushed to this URL.

     Important

     Ensure that the image repository URL is publicly accessible without authentication so that the build agent can pull the image.

     items defines the input form that appears on the pipeline configuration page. It supports various UI components, such as input (text box), dropdown (drop-down list), and checkbox. In this example, the shell type creates a script input box. For more syntax details, see Step YAML Description Language. The example defines two items: a command of type shell and abc of type input.

   • The step.sh file is the command executed in a step. When step.sh runs in a pipeline, it can access system variables from the pipeline context and input parameters that you enter on the edit page or pass at runtime as environment variables. The script lists some of the available environment variables:

     #!/bin/sh
     set -e                                     # Exit immediately if a command exits with a non-zero status
     # System-provided parameters from the pipeline context
     echo [INFO] PIPELINE_ID=$PIPELINE_ID       # Pipeline ID
     echo [INFO] PIPELINE_NAME=$PIPELINE_NAME   # Pipeline name
     echo [INFO] BUILD_NUMBER=$BUILD_NUMBER     # Build number of the pipeline run
     echo [INFO] EMPLOYEE_ID=$EMPLOYEE_ID       # ID of the user who triggered the pipeline
     echo [INFO] WORK_SPACE=$WORK_SPACE         # /root/workspace directory in the container
     echo [INFO] PROJECT_DIR=$PROJECT_DIR       # Root path of the code repository, defaults to /root/workspace/code
     echo [INFO] PLUGIN_DIR=$PLUGIN_DIR         # Plugin path, defaults to /root/workspace/plugins
     echo [INFO] BUILD_JOB_ID=$BUILD_JOB_ID     # build-service job ID
     cd $PROJECT_DIR                            # Change to the code repository directory
     sh -ex $WORK_SPACE/user_command.sh         # Execute the command script
     echo ${abc}                                # Output the value of 'abc'

     In this example, the sh -ex $WORK_SPACE/user_command.sh command directly executes the instructions that you configured in the step. It also outputs the abc parameter that you configured in step.yaml.

     Note

     user_command.sh is a default rule in Flow that converts the Shell script with the name command in step.yaml into user_command.sh. You can also define other Shell scripts and use environment variables to obtain script commands.

   • The Dockerfile contains the environment required for the step runtime. Currently, the base image required for the step must be pullable from a public network without authentication.

     FROM registry.cn-beijing.aliyuncs.com/rdc-builds/base:1.0
     MAINTAINER xxx <xxx@alibaba-inc.com>
     COPY .step/*.sh /root/
     COPY <your-step-sign>/step.sh /root/step.sh
     RUN chmod +x /root/*.sh
     ENTRYPOINT [ "/root/entry.sh"]

     A Dockerfile essentially provides the image environment to run step.sh. You can:

     • Install required dependencies directly in the Dockerfile.

     • Or, change the base image. If you do, ensure that jq is installed in the new base image.

Publish the step

1. Run the following command to publish the step:

   flow step publish <your-step-sign>

   This command performs two actions:

   • Build the local Dockerfile into the Docker image defined in step.yaml and push it to a remote repository. Please ensure that Docker is installed locally.

   • Publishes the step's metadata from step.yaml to the Alibaba Cloud DevOps server.

2. Run the flow step ls command to view the published steps.

   → flow step ls
   SIGN          NAME          CREATE TIME               MODIFIED TIME             DESCRIPTION
   test-step     Custom Step   2019-12-30 19:56:52       2019-12-30 19:56:52       My first step

Use the step

1. Go to the Alibaba Cloud DevOps Flow page and create a new pipeline from a blank template. In a stage, click Add Step, select Custom Step, and find the step you just created.

   In the step category list, select Enterprise Steps to find custom steps provided within your organization.

2. After adding the step, configure its settings and click Save and Run.

   In the configuration panel on the right, set the Step Name (for example, "My Custom Step"), the Command (for example, echo hello,world!), and any custom Parameters (for example, a parameter named abc with the value 123). You can also add plugins in the Task Plugins area.

3. You can see the step run in the pipeline and print hello world! and 123.

Update a step

To update a step, modify the step.yaml, step.sh, and Dockerfile files, and then run flow step publish <your-step-sign> again. Flow CLI will rebuild the image and upload the step.

If you do not see the updated parameter configuration on the pipeline editing page, try refreshing the page to clear the browser cache.