自定义工作流

自定义工作流

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

基本概念

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

新建

新建空白工作流

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

界面化配置

基本信息

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

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

阶段

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

参数说明：

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

任务

点击阶段下方的 +任务 为阶段增加任务配置，系统目前支持构建、部署、通用任务、Kubernetes 部署、测试、自定义任务 等任务类型。点击工作流任务可查看目前自定义工作流和发布工作流所支持的任务类型。

人工审批

开启阶段配置中的人工审批，在该阶段执行之前会触发审批。具体如何使用可参考文档：审批。

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}}`	项目名称
工作流	`{{.workflow.name}}`	工作流标识
	`{{.workflow.task.id}}`	工作流任务的 ID 序号，下图例中即为 `1`
	`{{.workflow.task.creator.id}}`	工作流任务执行者的用户名，下图例中即为 `admin`
	`{{.workflow.task.creator}}`	工作流任务执行者的昵称，下图例中即为 `admin-nickname`
	`{{.workflow.task.timestamp}}`	工作流任务创建时的 Unix 时间戳，下图例中即为 `1686642562`
构建任务	`{{.job.<任务名称>.SERVICES}}`	执行构建任务所选的服务组件名称集合变量的值形如 aslan/zadig,zadig-portal/zadig (服务组件名称/服务名称)
	`{{.job.<任务名称>.BRANCHES}}`	执行构建任务所选的服务组件对应的第一个代码库的分支信息集合变量的值形如 feature1,feature2,feature3
	`{{.job.<任务名称>.<服务>.<服务组件>.COMMITID}}`	指定服务组件的第一个仓库的 commit 信息
	`{{.job.<任务名称>.<服务>.<服务组件>.BRANCH}}`	指定服务组件时的第一个仓库的分支信息
部署任务	`{{.job.<任务名称>.envName}}`	部署环境

自定义变量

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

参数说明：

类型：支持字符串/多行文本/枚举/代码库类型
- 字符串类型的值为单行文本
- 在系统设置中集成代码源后，才能配置代码库类型变量的值，代码源集成请参考代码源集成
- 代码库类型的变量可用于通用任务的代码信息配置中
键：自定义变量的键
值：自定义变量的值，支持运行时输入和固定值两种配置方式，详细介绍可参考文档变量赋值方式

变量赋值方式

点击变量右侧的小图标为变量赋值，不同的赋值方式说明如下：

运行时输入：执行工作流时再指定该变量的值
固定值：设置变量值为固定值，工作流执行时页面中该变量不可见，无需再为该变量赋值
全局变量/其他任务输出：使用全局变量或其他任务输出的变量来赋值，工作流执行时会自动对全局变量进行渲染，实现不同任务之间的变量传递
- 支持的全局变量包括内置变量和自定义变量
- 若使用 其他任务输出，需要先为任务配置输出变量，参考文档：配置输出变量