自定义工作流

自定义工作流

自定义工作流中提供了充分的开放性，支持自由编排工作流流程，自定义执行步骤，下面展开介绍相关概念和具体使用。

基本概念

自定义工作流：对工作流流程自由编排，由一系列阶段组成
阶段：对工作流执行阶段进行逻辑分组，比如构建阶段、部署阶段…多个阶段串行运行，一个阶段可包括多个任务
任务：一个完整的任务，比如构建、部署、测试、自定义任务…多个任务可串行执行或并发执行

新建

新建空白工作流

进入项目中点击新建工作流，选择自定义工作流，系统提供界面化和 YAML 两种方式来配置自定义工作流。

使用模板新建企业版

新建工作流 -> 选择使用自定义工作流，可以选择自定义模板或者系统内置的工作流模板来新建工作流，如下图所示。

界面化配置

基本信息

包括工作流名称、标识和描述信息：

工作流名称：支持中文、大小写字母、数字及特殊字符，在所属项目中唯一，可修改。
工作流标识：支持大小写字母、数字及中划线，全局唯一，不支持修改。
描述：描述该工作流的详细信息，在工作留详情页展示。

阶段

点击 +阶段 增加新的阶段配置。

参数说明：

阶段名称：在同一个自定义工作流中，阶段名称唯一
并发执行：开启后，在该阶段下配置的多个任务将会并发执行
前置步骤：可按需开启人工审批。开启后，需要审批通过，该阶段下的任务才会被执行

任务

点击阶段下方的 +任务 为阶段增加任务配置，系统目前支持构建、部署、通用任务、Kubernetes 部署、测试、自定义任务 等任务类型。

构建任务

参数说明：

任务名称：支持 32 位以内的小写英文字母、数字或者中划线，且以小写英文字母开头；在同一个自定义工作流中，任务名称需唯一
镜像仓库：选择镜像仓库，当构建任务执行完成功后，构建出的镜像（即内置 $IMAGE 变量）会被推送到所选仓库中
服务组件：选择服务组件以及该服务组件使用的构建名称，点击展开构建配置的 设置 可配置所选中的变量值以及代码库默认分支
- 变量：参考构建任务变量
- 分支配置：选择代码库并指定默认分支，执行工作流时会默认使用指定的分支

提示

内置构建任务执行结束后会输出 $IMAGE 变量（页面中不可见，系统隐式逻辑），可用于内置部署任务中。
内置构建任务中不再支持 $ENV_NAME 构建变量，需要确保构建脚本中未使用该变量。
暂不支持使用 Jenkins 构建。

部署任务

参数说明：

任务名称：支持 32 位以内的小写英文字母、数字或者中划线，且以小写英文字母开头；在同一个自定义工作流中，任务名称需唯一
环境：选择要部署的环境，支持三种配置方式，具体请参考部署任务变量中关于环境信息的描述
服务：配置要部署的服务，支持两种配置方式，具体请参考部署任务变量中关于服务信息的描述
服务状态检测：若开启，部署任务会轮询服务运行状态，在部署超时之前该服务正常运行，任务状态才为成功

部署超时设置可参考服务策略配置

通用任务

支持拉取代码、执行 Shell 脚本、文件存储等功能。

执行环境：参考构建环境配置
代码信息：参考代码信息配置
变量：参考通用任务变量
添加步骤：包括添加 Shell 脚本执行以及文件存储，可参考更多构建配置
高级配置：参考高级配置

Kubernetes 部署任务

部署指定集群指定命名空间中的容器。

参数说明：

任务名称：在同一个自定义工作流中，任务名称需唯一
镜像仓库：执行 Kubernetes 部署任务时，从哪个镜像仓库获取镜像来部署目标容器
集群：待部署容器所在的集群
命名空间：待部署容器所在的命名空间
容器：指定命名空间中的容器应用（目前支持 Deployment 资源及 Statefulset 资源）
容器状态检测：若开启，部署任务会轮询容器运行状态，在部署超时之前该容器正常运行，任务状态才为成功
超时时间：容器部署超时时间

测试任务

支持在自定义工作流中引用项目下的测试配置。

选择具体的测试配置后，可对测试配置中的变量以及代码库默认分支进行设置。

镜像分发

可将镜像 Retag 后推送到指定镜像仓库。

参数说明：

任务名称：在同一个自定义工作流中，任务名称需唯一
服务组件：需要做镜像分发的服务组件
源镜像仓库：待分发的镜像来源
目标镜像仓库：镜像分发的目标仓库

自定义任务

自己定义任务的实现，在工作流中配置自定义任务，详细使用方法请参考自定义任务。

人工审批

开启阶段配置中的人工审批，在该阶段执行之前会触发审批。支持 Zadig 审批和飞书审批。

Zadig 审批

参数说明：

超时时间：从触发审批的时间点开始算起，当超过超时时间后视为审批超时失败，后续阶段中的任务将不会被执行
审批人：选择希望参与审批的人员
需要审批人数：当审批通过的人数满足此处指定的值时，即视为整个审批通过

飞书审批

参数说明：

审批应用：选择使用的飞书审批应用，审批应用集成方式参考审批系统集成
审批人：可选择多个审批人，只要一个人审批通过，即视为整个审批通过。

YAML 方式配置

配置说明

用 YAML 文件的方式定义工作流，YAML 内容的整体结构描述如下：

display_name:「工作流名称」        // 必填项，项目内唯一，支持中文、大小写字母、数字及特殊字符
name:「工作流标识」                // 必填项，项目内唯一，支持大小写字母、数字及中划线
stages:                          // 必填项，多个阶段将会按照先后顺序执行
  - 「阶段 1 的配置」
  - 「阶段 2 的配置」
  - 「更多阶段的配置...」
project: 「工作流所属项目名称」      // 必填项
description: 「工作流描述」
multi_run: 「可选值：true/false」  // 当同时触发多次工作流时，多条任务是否能并行执行，默认为 false

其中每一个阶段的具体配置如下：

name: 「阶段的名称」              // 必填项
parallel: 「可选值：true/false」  // 该阶段下的多个任务是否可以并发执行，默认为 false
approval: 「人工审批配置」         // 非必填，按需配置
jobs:                           // 必填项
  - 「任务 1 的配置」
  - 「任务 2 的配置」
  - 「更多任务的配置...」

人工审批的具体配置如下：

enabled: true
type: 「审批类型」                     // lark : 飞书审批 native：Zadig 审批
description: 「审批描述信息」
  native_approval:
    approve_users:                   // Zadig 审批人信息
      - user_id: 「审批人 ID」
        user_name: 「审批人昵称」
    needed_approvers: 「需要审批的人数」 // 整数类型
    timeout: 10                       // 整数类型，单位：分钟
  lark_approval:
    timeout: 10
    approval_id: 「审批应用 ID」
    approve_users:
      - id: 「审批人 ID」
        name: 「审批人昵称」
        avatar:  「审批人头像」

目前内置了构建和部署两种类型的任务，构建任务的具体配置如下：

在指定的构建中有相关构建变量配置时，在 YAML 中设置构建变量才有效。

name:「任务的名称」                    // 必填项
type: zadig-build                    // 必填项，指定为 zadig-build
spec:                                // 必填项
  docker_registry_id: 「镜像仓库 ID」
  service_and_builds:                // 服务组件的构建信息，可配置多个服务组件
    - service_module: 「服务组件名称」
      service_name: 「服务名称」
      build_name: 「构建名称」
      key_vals:                      // 构建变量信息，支持配置字符串和枚举类型的变量，分别见如下 string 和 choice 类型的变量示例
        - key: username              // 构建变量名称
          value: zadig               // 构建变量值
          is_credential: false       // 是否加密，默认为 false
          type: string
        - key: password
          value: v1
          is_credential: false
          type: choice
          choice_option:             // 枚举类型变量的可选值
            - v1
            - v2
    - service_module: 「服务组件名称」  // 更多服务组件的构建信息
      service_name: 「服务名称」
      build_name: 「构建名称」
      ...

内置部署任务的具体配置如下：

name: 「任务的名称」                    // 必填项
type: zadig-deploy                   // 指定为 zadig-deploy
spec:
  env: 「部署环境」                    // 必填项
  source: 「部署时使用的服务镜像的来源」  // 必填项，可选：runtime（运行时输入） / fromjob（其他任务输出）
  job_name: 「任务的名称」             // 当 source 为 fromjob 时需配置

YAML 样例

使用以下工作流配置为例：

第一个阶段：包含构建任务，并行构建 2 个服务（myapp-1 和 myapp-2）
第二个阶段：包含部署任务并开启人工审批，使用上述构建任务中的镜像产物来部署 pre-release 环境

对应的完整 YAML 配置示例如下，供参考：

name: pre-release-deploy
display_name: pre-release-deploy
stages:
  - name: 构建
    parallel: true
    jobs:
      - name: build-myapps
        type: zadig-build
        spec:
          docker_registry_id: 6247eb0832a15f910118318c
          service_and_builds:
            - build_name: simple-service-build-nginx-1
              key_vals:
                - is_credential: false
                  key: username
                  type: string
                  value: admin
                - is_credential: false
                  choice_option:
                    - v1
                    - v2
                  key: password
                  type: choice
                  value: v1
              service_module: myapp-1
              service_name: a
            - build_name: simple-service-build-myapp-2
              service_module: myapp-2
              service_name: b
  - name: 部署
    approval:
      enabled: true
      type: native
      description: '预发布环境部署，需审批通过方可执行'
      native_approval:
        approve_users:
          - user_id: af14dfd2-b57d-11ec-9511-9e1ccf83f7b3
            user_name: admin
          - user_id: 2d59d2f4-c6a5-11ec-a89e-2e173601a9ce
            user_name: zadig
        timeout: 120
        needed_approvers: 1
    jobs:
      - name: deploy
        type: zadig-deploy
        spec:
          env: pre-release
          job_name: build-myapps
          source: fromjob
project: simple-service
description: 预发布环境部署
multi_run: false

变量

自定义工作流中提供丰富的变量能力，以支持参数化配置工作流，并且在阶段和任务之间传递信息。以下分不同的使用范围分别介绍。

项目

项目级别的变量，可用于当前项目的所有自定义工作流中。

支持的变量见下表：

变量	说明
`{{.project}}`	项目的名称，下图例中即为 `simple-service-demo`

工作流

工作流级别的变量，可用于当前工作流的构建任务/部署任务/测试任务/通用任务/自定义任务中。

包括内置变量和自定义变量。

内置变量

支持的内置变量见下表：

变量	说明
`{{.workflow.name}}`	工作流的名称，下图例中即为 `pre-release-deploy`
`{{.workflow.task.id}}`	工作流任务的 ID 序号，下图例中即为 `1`
`{{.workflow.task.creator}}`	工作流任务的执行人，下图例中即为 `admin`
`{{.workflow.task.timestamp}}`	工作流任务创建时的 Unix 时间戳，下图例中即为 `1660555623`

自定义变量

编辑工作流，点击页面右侧的 变量 进入自定义变量配置页面。

说明如下：

类型：支持字符串/多行文本/枚举类型，其中字符串为单行文本
键：自定义变量的 key，可以使用 {{.workflow.params.key}} 的形式为构建/部署/通用/自定义任务中的变量赋值
值：自定义变量的值，支持以下两种配置方式：
- 运行时输入：执行工作流时，在工作流变量设置中指定该变量的值
- 固定值：指定变量的值，工作流执行时即使用该固定值，页面中该变量不可见

上图例中 LOG_LEVEL 和 MYSQL_USER_DB 的值为运行时输入，ISSUER_URL 的值为固定值，执行工作流时效果如下：

构建任务

内置构建任务中的变量。

变量的键和类型在此处不可更改，变量定义请阅读构建配置中的自定义构建变量部分。支持以下三种方式设置变量的值：

运行时输入：执行工作流时再指定该变量的值
固定值：指定变量的值，工作流执行时即使用该固定值，页面中该变量不可见
全局变量：使用全局变量为构建任务中的变量赋值，工作流执行时会自动对全局变量进行渲染。全局变量包括项目变量和工作流变量

部署任务

部署任务中的环境信息和服务信息。

环境信息支持以下三种配置方式：

运行时输入：执行工作流时再指定部署环境
固定值：设置部署环境为固定值，执行工作流时不可再更改
全局变量：使用全局变量为环境赋值，工作流执行时会自动对全局变量进行渲染替换。全局变量包括项目变量和工作流变量

服务信息支持以下两种配置方式：

其他任务输出：可选择前置构建任务，使用任务中的 $IMAGE 变量来部署服务（如果前置构建任务中构建了多个服务，则部署任务中也会部署多个服务）
运行时输入：执行工作流时手动指定服务的镜像

Kubernetes 部署任务

内置 Kubernetes 部署任务中的容器信息。

容器信息支持以下两种配置方式：

运行时输入：执行工作流时再指定要部署的容器
固定值：设置待部署容器为固定值，执行工作流时不可再更改

测试任务

测试任务中的变量信息。

支持以下三种配置方式：

运行时输入：执行工作流时再指定要测试配置中的变量值
固定值：设置测试配置中的变量为固定值，执行工作流时不可再更改
全局变量：使用全局变量为测试任务中的变量赋值，工作流执行时会自动对全局变量进行渲染。全局变量包括项目变量和工作流变量

镜像分发

镜像分发任务中的服务组件信息。

支持以下两种配置方式：

运行时输入：执行工作流时再指定需要做镜像分发的服务组件
其他任务输出：使用前置构建任务输出的服务组件及对应的镜像信息进行分发

通用任务

通用任务中的变量。

包括内置变量和自定义变量。

内置变量请参考构建变量中关于内置构建变量的描述，自定义变量说明如下：

类型：支持创建字符串类型和枚举类型的自定义变量
键：自定义变量的 key，可在 添加步骤 中通过 $key 的形式来使用
值：自定义变量的值，支持以下三种配置方式：
- 运行时输入：执行工作流时再指定该变量的值
- 固定值：指定变量的值，工作流执行时即使用该固定值，页面中该变量不可见
- 全局变量：使用全局变量为通用任务中的自定义变量赋值，工作流执行时会自动对全局变量进行渲染。全局变量包括项目变量和工作流变量