工作流配置

工作流中提供了充分的开放性，支持自由编排工作流流程，自定义执行步骤，下面展开介绍相关配置。

# 新建方式

# 新建空白工作流

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

# 使用模板新建

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

移动鼠标到模板卡片上，可以看到「使用」和「强绑定」两个入口。

• 选择「使用」：基于模板复制出一个普通工作流。创建后，工作流可以自由调整 Stage、Job 和各类配置，后续模板变更不会继续管理该工作流。
• 选择「强绑定」：基于模板创建一个强绑定工作流。创建后，工作流会被模板持续管理，适合企业统一沉淀标准发布流程、测试流程或安全扫描流程。

# 强绑定

强绑定用于将工作流与工作流模板建立持续关联。使用强绑定创建工作流后，工作流结构由模板统一管理，项目成员只需要维护当前项目需要差异化配置的参数类内容。

强绑定工作流创建成功后，在工作流编辑页面标题旁会显示「强管理」标识。将鼠标移动到标识上，可以看到当前工作流绑定的模板名称。

强绑定工作流支持修改以下内容：

• 工作流名称、描述等基础信息。
• 工作流参数、共享存储、并发执行数等运行配置。
• 模板中已有阶段和任务的参数类配置，例如构建配置、部署服务、环境、变量、审批、通知等具体执行参数。

强绑定工作流不支持修改以下结构：

• 新增或删除阶段。
• 新增或删除任务。
• 替换已有任务的类型，或通过 YAML 修改导致阶段/任务结构与模板不一致。

# 修改并保存强绑定工作流

编辑强绑定工作流时，按正常方式进入工作流配置页面，修改需要覆盖的参数后点击保存即可。

系统会自动记录当前工作流相对于模板的差异配置。后续模板升级时，这些差异会用于判断该工作流是否可以自动继承模板变更，以及是否需要人工处理冲突。

如果通过 YAML 编辑工作流，请注意不要新增、删除或替换阶段/任务。

# 模板升级影响

当工作流模板被修改并保存后，如果该模板已经被强绑定工作流引用，系统会检查模板升级对这些工作流的影响，并展示「模板升级影响」弹窗。

弹窗中会展示以下信息：

• 工作流：受影响的强绑定工作流名称和所属项目。
• 版本：工作流当前绑定的模板版本，以及模板最新版本。
• 影响：是否存在冲突、失效差异，或者无冲突。
• 升级版本操作：处理该工作流与模板新版本之间的差异。

可选择的处理方式如下：

• 「保留工作流参数」：保留该工作流已经修改过的参数类配置，并将模板变更合并到工作流中。适合工作流参数需要按项目保留差异的场景。
• 「使用模板参数」：以模板最新配置为准，放弃冲突位置上工作流本地修改过的参数。适合需要完全跟随模板标准的场景。

如果存在失效差异，说明部分工作流本地差异已经无法应用到模板新版本上，需要使用模板参数或重新进入工作流调整配置。

# 删除被强绑定引用的模板

删除工作流模板时，如果该模板没有被强绑定工作流引用，系统会按普通模板删除流程处理。

如果模板已经被强绑定工作流引用，系统会提示该模板正在被哪些工作流引用，并要求确认是否「强制删除」。

确认强制删除后，模板会被删除，引用该模板的强绑定工作流会自动解绑为普通工作流。解绑后，这些工作流不再受模板管理，也不会继续接收模板升级影响。

# 适用场景

建议在以下场景使用强绑定：

• 企业需要统一管理标准发布流程、测试流程、安全扫描流程。
• 平台管理员希望模板升级后，项目工作流可以持续继承模板结构和默认配置。
• 项目成员只需要填写服务、环境、变量、审批人等执行参数，不希望随意改动流程结构。

如果某个项目需要长期自由调整流程结构，建议使用普通「使用」入口创建工作流，而不是强绑定。

# 界面化配置

# 基本信息

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

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

# 阶段

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

参数说明：

• 阶段名称：在同一个工作流中，阶段名称唯一
• 并发执行：开启后，在该阶段下配置的多个任务将会并发执行

阶段支持自动和手动执行两种方式，手动执行允许指定阶段执行人以及在执行时重新输入任务参数。

# 任务

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

# YAML 方式配置

# 配置说明

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

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

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

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

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

在指定的构建中有相关构建变量配置时，在 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 样例

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

1. 第一个阶段：包含构建任务，并行构建 2 个服务（myapp-1 和 myapp-2）
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: 部署
    jobs:
      - name: deploy
        type: zadig-deploy
        spec:
          env: pre-release
          job_name: build-myapps
          source: fromjob
project: simple-service
description: 预发布环境部署
multi_run: false

# 变量

工作流中提供丰富的变量能力，以支持参数化配置工作流，并且支持通过变量在任务、阶段、工作流、项目之间传递信息。

# 内置变量

# 自定义变量

工作流变量分为全局变量和任务变量，全局变量下图中配置，任务中的自定义变量在对应任务中配置。

变量说明：

• 类型：支持字符串、多行文本、单选、多选、文件、代码库、镜像、动态变量。
  • 其中 代码库 仅在工作流全局变量中可用。
  • 其中 镜像 仅在通用脚本执行中可用。
• 键：自定义变量的键
• 值：自定义变量的值，支持运行时输入和固定值两种配置方式，详细介绍可参考 变量赋值方式
• 必填：是否必填，如果必填，则工作流执行时必须输入该变量的值
• 敏感信息：是否为敏感信息，如果为敏感信息，则工作流执行时该变量的值会被隐藏显示为 ********

# 变量赋值方式

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

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

全局变量有两种使用方式：

1. 在构建、代码扫描、测试、通用脚本执行中通过 shell 环境变量方式使用
2. 任务中定义自定义变量，选择赋值方式选择全局变量/其他任务输出，选择对应的全局变量即可使用。

# 变量传递

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

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

配置输出变量

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

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

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

使用输出变量

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

# 任务调度策略

# 执行策略

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

# 执行条件

• 所有前置任务成功或跳过：前置任务全部成功或跳过时执行
• 满足条件执行：满足配置条件时执行
• 满足条件不执行：满足配置条件时不执行

条件配置：

• 支持满足所有条件或满足任一条件两种匹配模式
• 支持内置变量和自定义变量，操作符包括：等于、不等于、包含、不包含、开头是、开头不是、结尾是、结尾不是

# 失败策略

• 标记失败：该任务失败时，工作流停止执行，标记失败
• 忽略失败：该任务失败时，工作流继续执行
• 人工确认：该任务失败时，需要人工判断是跳过该任务还是工作流停止
• 失败重试：该任务失败时，可以根据配置的重试次数自动重试

# 通知

工作流任务可根据实际的任务状态单独配置通知，比如任务开始、任务成功、任务失败、任务取消等，通知方式包括：

1. 飞书群组通知
2. 飞书成员通知
3. 钉钉
4. 企业微信
5. Microsoft Teams
6. 邮件
7. Webhook

# 触发器配置

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

# Git 触发器

参数说明：

• 代码库：需要监听触发事件的代码仓库，代码源选择不同对应的触发事件也会不同。
• 目标分支：提交 pull request 时的 Base 分支。支持正则表达式配置，语法参见 Regexp Syntax(opens new window)。
• 触发事件: 指定触发工作流运行的 Webhook 事件，可选事件如下：
  • Push commits 事件（Merge 操作）时触发。代码仓库中 description 字段变更将被过滤，不会触发工作流执行。
  • Pull requests 提交 pull request 时触发。
  • Push tags 新建 tag 之后触发。
• 触发策略: Push commits 和 Pull requests 事件支持自动取消，如果你希望只触发最新的提交，则使用这个选项会自动取消队列中正在进行的前序任务。
• 文件目录: 通过设置文件和文件目录，可以实现对文件以及目录的监听，当文件或者目录发生变化时（新增、修改或者删除），触发工作流。也可以忽略对应的文件或者目录变更，不进行工作流的触发。

使用以下代码仓库文件结构为例：

├── reponame  # 仓库名称
  ├── Dockerfile 
  ├── Makefile
  ├── README.md   
  ├── src        
    ├── service1/
    ├── service2/
    └── service3/

# 定时器

通过配置定时器，可以实现周期性的运行工作流。目前工作流支持的定时器方式主要有：

• 定时循环：在某个时间点定时执行某个工作流，例如每天 12:00 运行，每周一 10:00 运行
• 周期循环：周期性的执行某个任务，例如每 30 分钟执行一次工作流
• Cron 表达式：使用标准的 Linux Cron 表达式灵活的配置定时器，例如："45 4 1,10,22 * *"，每月 1、10、22 日 4:45 分执行工作流任务

# 定时循环

具体操作步骤：

• 点击添加按钮添加一项定时循环条目，分别选择周期时间以及时间点
• 设置工作流任务参数，执行时按设置的参数执行

# 间隔循环

具体操作步骤：

• 第 1 步：点击添加按钮添加一项间隔循环条目，分别选择间隔时间以及间隔时间单位
• 第 2 步：设置工作流参数，执行时按设置的参数执行

# Cron 表达式

具体操作步骤：

• 第 1 步：点击添加按钮添加一项 Cron 表达式条目，填写 Cron 表达式
• 第 2 步：设置工作流参数，执行时按设置的参数执行

# 通知配置

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

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

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

以飞书示例通知效果：

# 执行并发数

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

# 禁用

开启禁用模式后, 工作流将无法执行，包括手动执行、通过触发器执行。

# 备注

运行工作流可以输入备注信息，方便后续查看工作流执行备注。支持运行时必填，设置必填后，运行工作流时必须输入备注。

# 调试

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

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

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

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

# 自定义执行记录列字段

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

• 服务组件(构建任务名称)
• 代码信息(构建任务名称)
• 服务组件(部署任务名称)
• 环境(部署任务名称)
• 测试结果(测试任务名称)
• 备注
• 分支信息
• 发布计划
• 飞书项目

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

# 共享存储

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

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

# 集群资源配置

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

# 工作流配置

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

# 工作流任务配置

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

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

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