自定义工作流

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

基本概念

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

新建

新建空白工作流

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

自定义工作流 - 图1 自定义工作流 - 图2

使用模板新建

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

自定义工作流 - 图3 自定义工作流 - 图4

界面化配置

基本信息

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

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

common_workflow_config

阶段

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

common_workflow_config

参数说明：

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

任务

点击阶段下方的 +任务 为阶段增加任务配置，系统支持的任务类型及具体配置可参考文档 工作流任务。

人工审批

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

YAML 方式配置

配置说明

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

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

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

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

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

  1. enabled: true
  2. type: 「审批类型」                     // lark : 飞书审批 native：ZadigX 审批
  3. description: 「审批描述信息」
  4.   native_approval:
  5.     approve_users:                   // ZadigX 审批人信息
  6.       - user_id: 「审批人 ID」
  7.         user_name: 「审批人昵称」
  8.     needed_approvers: 「需要审批的人数」 // 整数类型
  9.     timeout: 10                       // 整数类型，单位：分钟
  10.   lark_approval:
  11.     timeout: 10
  12.     approval_id: 「审批应用 ID」
  13.     approve_users:
  14.       - id: 「审批人 ID」
  15.         name: 「审批人昵称」
  16.         avatar:  「审批人头像」

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

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

  1. name:「任务的名称」                    // 必填项
  2. type: zadig-build                    // 必填项，指定为 zadig-build
  3. spec:                                // 必填项
  4.   docker_registry_id: 「镜像仓库 ID」
  5.   service_and_builds:                // 服务组件的构建信息，可配置多个服务组件
  6.     - service_module: 「服务组件名称」
  7.       service_name: 「服务名称」
  8.       build_name: 「构建名称」
  9.       key_vals:                      // 构建变量信息，支持配置字符串和枚举类型的变量，分别见如下 string 和 choice 类型的变量示例
  10.         - key: username              // 构建变量名称
  11.           value: ZadigX               // 构建变量值
  12.           is_credential: false       // 是否加密，默认为 false
  13.           type: string
  14.         - key: password
  15.           value: v1
  16.           is_credential: false
  17.           type: choice
  18.           choice_option:             // 枚举类型变量的可选值
  19.             - v1
  20.             - v2
  21.     - service_module: 「服务组件名称」  // 更多服务组件的构建信息
  22.       service_name: 「服务名称」
  23.       build_name: 「构建名称」
  24.       ...

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

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

YAML 样例

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

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

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

  1. name: pre-release-deploy
  2. display_name: pre-release-deploy
  3. stages:
  4.   - name: 构建
  5.     parallel: true
  6.     jobs:
  7.       - name: build-myapps
  8.         type: zadig-build
  9.         spec:
  10.           docker_registry_id: 6247eb0832a15f910118318c
  11.           service_and_builds:
  12.             - build_name: simple-service-build-nginx-1
  13.               key_vals:
  14.                 - is_credential: false
  15.                   key: username
  16.                   type: string
  17.                   value: admin
  18.                 - is_credential: false
  19.                   choice_option:
  20.                     - v1
  21.                     - v2
  22.                   key: password
  23.                   type: choice
  24.                   value: v1
  25.               service_module: myapp-1
  26.               service_name: a
  27.             - build_name: simple-service-build-myapp-2
  28.               service_module: myapp-2
  29.               service_name: b
  30.   - name: 部署
  31.     approval:
  32.       enabled: true
  33.       type: native
  34.       description: '预发布环境部署，需审批通过方可执行'
  35.       native_approval:
  36.         approve_users:
  37.           - user_id: af14dfd2-b57d-11ec-9511-9e1ccf83f7b3
  38.             user_name: admin
  39.           - user_id: 2d59d2f4-c6a5-11ec-a89e-2e173601a9ce
  40.             user_name: ZadigX
  41.         timeout: 120
  42.         needed_approvers: 1
  43.     jobs:
  44.       - name: deploy
  45.         type: zadig-deploy
  46.         spec:
  47.           env: pre-release
  48.           job_name: build-myapps
  49.           source: fromjob
  50. project: simple-service
  51. description: 预发布环境部署
  52. 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.<任务名称>.IMAGES}}执行构建任务所选的服务组件对应的镜像集合
变量的值形如 image1:tag1,image2:tag2
{{.job.<任务名称>.GITURLS}}执行构建任务所选的服务组件对应的第一个代码库信息集合，变量的值形如 https://gitlab.com/group1/repo1,https://gitlab.com/group2/repo2（代码源 URL/组织名或用户名/代码库名称）
{{.job.<任务名称>.<服务>.<服务组件>.COMMITID}}指定服务组件的第一个仓库的 commit 信息
{{.job.<任务名称>.<服务>.<服务组件>.BRANCH}}指定服务组件时的第一个仓库的分支信息
部署任务{{.job.<任务名称>.envName}}部署环境
{{.job.<任务名称>.IMAGES}}被部署的服务组件的镜像集合
变量的值形如 image1:tag1,image2:tag2
镜像分发任务{{.job.<任务名称>.IMAGES}}被分发的服务组件的目标镜像集合
变量的值形如 image1:tag1,image2:tag2

common_workflow_config

自定义变量

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

自定义工作流 - 图8 自定义工作流 - 图9

参数说明：

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

变量赋值方式

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

  • 运行时输入：执行工作流时再指定该变量的值
  • 固定值：设置变量值为固定值，工作流执行时页面中该变量不可见，无需再为该变量赋值
  • 全局变量/其他任务输出：使用全局变量或其他任务输出的变量来赋值，工作流执行时会自动对全局变量进行渲染，实现不同任务之间的变量传递

common_workflow_config

变量传递

支持在不同的任务之间传递变量，传递流程：

  1. 在前置任务的高级配置中声明要输出的变量
  2. 在后置任务中通过全局变量/其他任务输出的方式使用该变量

配置输出变量

构建/测试/代码扫描/通用任务中支持配置输出变量，不同任务输出变量的形式如下：

  • 构建任务：{{.job.<任务名称>.<服务名称>.<服务组件名称>.output.<变量名>}}
  • 测试任务：{{.job.<任务名称>.<测试名称>.output.<变量名>}}
  • 代码扫描任务：{{.job.<任务名称>.<代码扫描名称>.output.<变量名>}}
  • 通用任务：{{.job.<任务名称>.output.<变量名>}}

以构建任务进行示例，在高级配置中添加输出变量，填写变量名。

提示

  1. 添加的变量可来自于构建配置中的自定义变量，或者在构建脚本中设置的变量，比如 export key=value
  2. 系统默认会输出构建中的 IMAGE 和 PKG_FILE 变量，分别表示服务的镜像名称和交付物文件名称

common_workflow_config

使用输出变量

支持全局变量/其他任务输出配置方式的任务可参考文档：不同任务中支持的配置方式。
以通用任务自定义变量进行示例：在通用任务中为变量赋值时指定为全局变量/其他任务输出，并选择在前置任务中配置的输出变量，即可实现不同任务之间的变量传递。

自定义工作流 - 图12 自定义工作流 - 图13

触发器配置

为工作流配置触发器，当满足触发条件的事件发生时会自动触发工作流执行，支持 Git 触发器、定时器、JIRA 触发器、飞书项目触发器和通用触发器，具体如何使用可参考文档：工作流触发器。

common_workflow_config common_workflow_config

通知配置

编辑工作流，点击右侧的 通知 进入通知配置页面。

common_workflow_config

目前支持配置工作流通知到飞书/企业微信/钉钉中，详细的配置参数说明可参考：IM 状态通知。

common_workflow_config

通知消息中会包含工作流所有任务的执行情况，对于构建任务、部署任务和测试任务，在通知内容中的名称规则如下：

  • 构建任务：服务名称-服务组件名称-构建任务名称
  • 部署任务：服务名称-部署任务名称
  • 测试任务：测试名称-测试任务名称-随机字符串

以飞书示例通知效果：

common_workflow_config

高级配置

在高级配置 > 运行策略中设置并发数，多次触发工作流执行产生的多条工作流任务将会并发执行，提升工作流运行效率。

common_workflow_config

自定义工作流样例

可在自定义工作流中自由编排流程，下面简单举例几种场景。

场景一：构建镜像到不同的仓库

配置多个构建任务，每个任务中指定不同的镜像仓库。

common_workflow_demo

场景二：同时部署多个环境

配置多个部署任务，每个任务中指定不同的环境。

common_workflow_demo

场景三：使用不同的镜像仓库来部署不同的环境

配置多个构建任务，每个构建任务中指定不同的镜像仓库；为每个环境配置部署任务，服务来源选择其他任务输出并指定对应任务。

common_workflow_demo

场景四：审批通过后再部署环境

部署阶段配置中增加人工审批。

自定义工作流 - 图23 自定义工作流 - 图24

在部署步骤执行之前会触发审批，审批通过后工作流才会继续执行。

common_workflow_demo

执行

点击执行工作流，可修改工作流变量的值，按需选择被执行的任务：

若工作流变量的值被设置为固定值，则执行工作流时该变量在页面中不可见。

run_common_workflow

点击具体的构建任务可查看构建日志：

任务名称规则为：服务名-服务组件名-任务名

run_common_workflow

工作流执行失败后可操作重试再次执行，再次触发后将会从失败的任务开始执行，前置成功的任务（包括审批）将不会再被执行。

run_common_workflow

任务执行策略配置

run_job

  • 默认执行：配置默认执行的任务在 执行任务 和 配置触发器 时默认执行，用户可以选择不执行。
  • 默认不执行：配置默认不执行的任务在 执行任务 和 配置触发器 时默认不执行，用户可选择执行。
  • 强制执行：配置强制执行的任务在 执行任务 和 配置触发器 时必须执行，用户不可选择不执行。

调试

支持对构建任务、测试任务以及通用任务进行调试。

点击调试启动工作流进入调试模式，可在工作流中的构建/测试/通用任务中的 Shell 脚本执行前增加断点操作，便于调试工作流配置。

debug_workflow

也支持在执行工作流后，对指定的任务增加断点调试，点击右上角的调试图标后配置断点位置即可。

自定义工作流 - 图31 自定义工作流 - 图32

点击调试控制台即可登录到当前任务的容器中，待调试完毕后，点击继续，工作流才会继续执行。

debug_workflow

自定义历史任务列字段

可自定义历史任务列表中的列字段，将构建、部署、测试任务中的相关信息添加到列表中。自定义列字段的格式如下：

  • 服务组件(构建任务名称)
  • 代码信息(构建任务名称)
  • 服务组件(部署任务名称)
  • 环境(部署任务名称)
  • 测试结果(测试任务名称)

debug_wordefine_workflow_task_columnkflow

可针对自定义字段对工作流任务进行快速过滤。

debug_wordefine_workflow_task_columnkflow

共享存储

ZadigX 现已支持在工作流任务中实现共享存储，具体操作步骤如下：

  1. 对集群资源进行配置，定义共享的存储资源。
  2. 对工作流进行配置，添加共享目录。
  3. 在工作流的任务中开启共享并应用，实现任务间的共享存储。

集群资源配置

参考文档：集群共享存储资源配置。

工作流配置

编辑自定义工作流，点击 高级配置，添加共享目录后保存。

自定义工作流 - 图36 自定义工作流 - 图37

工作流任务配置

对于构建/测试/代码扫描任务，在对应任务中点击共享存储小图标开启共享存储并配置共享目录即可。以构建任务示例如下：

工作流任务共享存储

在支持高级配置的任务中，在高级配置中开启共享存储，选择共享目录并配置共享目录即可。以通用任务示例如下：

支持高级配置的任务请参考文档：高级配置。

工作流任务共享存储