使用Flow-CLI自定义开发步骤

背景信息

• Flow-CLI 是云效流水线 Flow 推出的一款命令行工具，用以管理 Flow 中各种资源，子命令 step 可以让用户在流水线中运行自定义步骤逻辑，以达到扩展流水线能力的效果。

• Flow 中一个流水线的任务运行由多个“步骤”组成，步骤是由一段描述 YAML 和一个 TypeScript 代码包组成的一个最小运行单元，YAML描述决定步骤运行时的入参，TypeScript 代码决定步骤运行的逻辑；这篇文档将引导用户在 Flow 上创建一个自定义步骤。

操作步骤

npm i -g @flow-step/flow-cli --registry=https://registry.npmmirror.com
flow-cli -h  # 输出帮助信息说明安装成功

flow-cli login    # 登录

新建步骤

flow-cli step init

按引导输入步骤基本信息，注意：Step Sign 标识为整个云效唯一，若被其他步骤占用则无法创建成功。(Step Sign 应匹配以大写字母开头，后跟零个或多个大写字母、小写字母或数字，例如HelloV2Step)

这个命令会在本地创建Step Sign名称的文件夹，本例中为HelloV2StepWorld，文件夹下有如下文件：

.
├── README.md     # 步骤说明
├── package.json  # typescript 工程包声明
├── src           # 步骤执行逻辑
│   ├── index.ts
│   ├── params.ts
│   └── util.ts
├── step.yaml     # 用于描述步骤所有信息的 yaml
├── test          # 步骤单元测试
│   └── index.spec.ts
├── tsconfig.eslint.json
└── tsconfig.json

• step.yaml：用于定义 step 执行所需的输入参数，包括 step 在流水线配置时该步骤所需的配置参数。

• src/index.ts：步骤运行时执行的入口源代码文件，您可以在该文件内获取流水线的环境变量、step.yaml 中配置的参数，并定义您想要的执行逻辑。

下面通过一个示例详细讲解这两个关键文件的具体作用。

1. step.yaml 里定义了步骤有关的描述：

   ---
   id: HelloV2StepWorld                      # 步骤唯一标识
   name: HelloV2StepWorld                    # 步骤名称
   description: My awesome flow step :-)     # 步骤描述
   helpUrl: https://atomgit.com/flow-step-custom/HelloV2StepWorld  # 步骤帮助链接
   execution:
     executor: node
     main: dist/index.js
   items:                                    # 入参表单
     - label: input 参数
       name: abc
       type: input
       description: input 类型参数 abc
       value: hello world
     - label: password 参数
       name: your_password
       type: password
       description: password 类型参数 your_password
     - label: textarea 参数
       name: exclusion
       type: textarea
       value: |
         test/
         build/
       description: textarea 类型参数 exclusion
     - label: select 参数
       name: select_version
       type: select
       value: v1.0.0
       datasource:
         - label: "v1.0.0"
           value: v1.0.0
         - label: "v1.0.1"
           value: v1.0.1
         - label: "v1.0.2"
           value: v1.0.2
       description: select 类型参数 select_version
     - label: 参数 edf
       name: edf
       type: input
       showCondition: ${select_version} == "v1.0.0"
       description: 配置 showCondition，只有当 select_version == v1.0.0 才展示
     - label: 开关
       name: toggle
       type: checkbox
       value: false

   items 定义了流水线编辑页面中供用户配置的输入表单，支持多种前端组件，如输入框 input, 复选框 checkbox 等；示例中提供常见的组件配置。更多语法见步骤yaml描述语言。

2. src/index.ts 即步骤执行的逻辑，在流水线中运行时可以通过环境变量的方式获取到来自流水线上下文的系统变量，以及用户通过编辑页面、运行传入的方式写入的入参，脚本中列举了一部分可供使用的环境变量：

   async function runStep(): Promise<void> {
     const params = getParams()
     step.info(`PIPELINE_ID=${params.pipelineID}`)
     step.info(`PIPELINE_NAME=${params.pipelineName}`)
     step.info(`BUILD_NUMBER=${params.buildNumber}`)
     step.info(`WORK_SPACE=${params.workSpace}`)
     step.info(`PROJECT_DIR=${params.projectDir}`)
     step.info(`BUILD_JOB_ID=${params.buildJobID}`)
   
     const abc = process.env.abc ? process.env.abc as string : ''
     step.info(`Hello from flow-step HelloV2StepWorld, custom param abc=${abc}, upper value=${convertToUpperCase(abc)}`)
   
     # ...
   }

接着执行新建步骤的安装与构建命令，可按照初始化完成后命令提示符中提示命令执行，本例中为 cd HelloV2StepWorld && npm install && npm run build该命令有三步操作：

1. cd HelloV2StepWorld代表切换到新建步骤的文件目录下。

2. npm install 代表进行步骤的依赖安装。

3. npm run build代表步骤的本机构建。

执行完成后可以看到工程构建出 dist 目录，dist/index.js文件是Flow 步骤真正执行的文件。

当你完成自定义步骤配置推送后，流水线执行你的自定义步骤时，会先从步骤包的存储服务上下载该步骤，并在默认 alinux3 容器环境（可在 yaml pipeline 中自定义为用户的镜像）中执行你所定义的脚本文件。

上线步骤

根据当前所在目录情况选择下列命令执行：

flow-cli step publish # 发布步骤

flow-cli step publish ${your-step-folder} # 发布步骤

该命令会执行两个动作：

1. 将本地的 typescript 工程进行构建并打包， push 到远端仓库。

2. 将 step.yaml 描述的步骤源信息发布到云效的服务器。

发布成功后输入步骤版本，本例中为 v1.0.0 版本。

使用flow-cli step list可以查看已经发布的步骤。

使用步骤

进入 Flow 流水线页面，从空模板创建流水线，点击阶段并添加任务->添加步骤->组织步骤，找到刚才创建的步骤。注意：环境需要选择指定容器环境，否则无法使用V2自定义步骤。

步骤添加完成之后，可以对步骤的内容进行配置，点击保存并运行，可以看到步骤在流水线中运行起来，查看日志发现执行了 TypeScript 的逻辑。

更新步骤

若需要更新步骤，可以修改 step.yaml与TypeScript 代码逻辑，重新执行 flow-cli step publish ，Flow-CLI 会重新进行代码打包和步骤上传。

若您进入流水线编辑页后，发现步骤参数配置内容未发生变化，可以尝试刷新缓存。

删除步骤

若需要删除发布的步骤，可以执行 flow-cli step remove "your_step_sign"，将命令中your_step_sign替换为需要删除的步骤的Step Sign 标识。

其他操作

你可以通过执行下述命令，查看Flow-CLI 支持的其他操作命令。

FAQ

如果本地没有浏览器如何登录？

登录后本地会自动生成 ~/.flow.json 文件，目前Flow-CLI 是依赖~/.flow.json 文件来进行鉴权，用户也可以自己生成该文件，实现登录。文件内容如下：

{"userToken":{"access_token":"ACCESS_TOKEN","token_type":"Bearer","user_id":"USER_ID"},"organization":{"error":"","message":"","id":"","createdAt":"","updatedAt":"","creatorId":"","name":"","logo":"","location":"","category":"","description":"","website":"","background":"","contactPhone":"","desiredMemberCount":"","isDeleted":"","py":"","pinyin":"","isPublic":false,"defaultRoleId":"","defaultOrgRoleId":"","okrProgressMode":"","defaultTeamId":"","openId":"","source":""}}

请将ACCESS_TOKEN 以及USER_ID替换成用户自己的值，这两个值的获取方式如下：

访问云效流水线，登录之后，右键查看网页源代码，搜索源代码中的tbUserId即为USER_ID，accessToken即为需要的ACCESS_TOKEN。将内容替换后，写入到~/.flow.json即可。