使用说明

角色与权限

流水线的角色与其关联的代码库角色密切相关，详见代码库中角色管理：

执行记录

通过流水线的执行记录可以看到某个代码库、某个分支、某条流水线的最近构建记录。
点击流水线的任何一个阶段会展开显示该阶段下的任务。
对于编译任务，甚至还可以点击直接在右浮窗口查看编译日志。
整个交互完全在一个单一界面中完成。

流水线管理

通过流水线管理功能，可以对流水线进行新建、编辑、删除、复制等操作。

流水线复制

在流水线管理主界面，可对现有流水线单个复制或批量复制。

单个复制

点击操作列【复制】 默认选择当前所在代码库，单个复制支持将单个流水线批量复制到多个代码库下。复制时默认目标库流水线名称在被复制流水线名称后增加-copy，如有重名则会有提示，需要将预复制流水线冲突名称更改为与目标库流水线不冲突的名称。

批量复制

点击【批量操作】按钮，勾选需要复制的流水线，再次点击【批量操作】按钮选择点击【复制】，批量复制支持将勾选的流水线复制到多个代码库下。复制时默认目标库流水线名称在被复制流水线名称后增加-copy，如有重名则会有提示，需要将预复制流水线冲突名称更改为与目标库流水线不冲突的名称。。

流水线的触发

流水线的触发事件比较重要，需要单独提出来说明一下

具体触发事件包括：代码库触发、定时触发、手动触发、API触发四类。其中界面可配置的是前三类。

代码库触发

• 代码更新触发：
  触发条件：当匹配分支被创建、有代码被合入（直接push合入，代码评审通过后被合入、在线编辑合入）时触发
  使用场景：对合入后的代码进行质量验证
  注意：流水线要配置在有代码更新的分支上

• 发起及更新MR评审触发：
  触发条件：发起或更新向目标分支的分支合并请求(Merge Request)时，在源分支触发
  使用场景：在MR评审场景下，保障源分支上的代码质量，否则污染目标分支代码
  注意：流水线要配置在源分支上

• 收到及更新DCR评审触发：
  触发条件：本地开发完毕，向远程分支通过git push命令，直接发起DCR(Direct code review)评审时，在远程分支上触发
  使用场景：在DCR评审场景下，保障提交的评审代码质量，否则污染远程分支代码
  注意：流水线要配置在远程分支上，因为DCR不存在源分支的概念

• 模拟预合入触发(代码库专利技术)： 触发条件：MR评审场景下,发起MR或者MR源分支、目标分支有更新；
  DCR场景下，发起DCR或者重新向远程分支推送了代码更新、或者远程分支以其他方式合入了代码（例如合入了其他评审的代码）
  使用场景：在MR和DCR评审场景下，如果希望提前预知被评审的代码合入目标分支后是否会有质量问题（不是代码冲突）可以使用
  注意：流水线要配置MR评审的目标分支上，DCR评审的远程分支上；代码库配置要打开评审模拟预合入功能(SaaS版收费功能)

定时触发

顾名思义，定时触发只有在预定的时间才会触发，定时触发时，会在关联的分支上，对最新的commit进行进行构建。
同时定时触发还可以设置目标分支上是否在相对上次触发有代码变更时才触发、单次触发还是循环多次触发。

手动触发

顾名思义，手动触发就是只有在“流水线管理”菜单下，点击执行按钮进行手动触发时才触发。
注意：所有的流水线都可以在“流水线管理”菜单下，通过手动点击执行按钮的方式进行手动触发。

API触发方式

所有的流水线都支持通过API触发
使用场景：在脚本里通过API调用，完成自定义的自动化操作
使用方法：例如使用curl命令调用，在流水线管理操作列点击【复制为cURL】

复制出来粘贴内容如下：

【令牌字符串】在个人设置-访问令牌-新建令牌包含流水线读写。

【分支名称】可以是触发的分支名称、触发tag名称、触发commitID

【scmTriggerType】字段对应的值分别为：BRANCH（触发为分支）、TAG（触发为版本）、COMMIT（触发为commitID）

# 触发分支
curl --location --request POST 'https://10.1.2.3/v1/pipeline/pipelines/1/manual' \
                    -H 'access_token:{令牌字符串}' \
                    --header 'Content-Type: application/json' \
                    --data '{"externalName":"{分支名}","scmTriggerType":"BRANCH","variables":null}'

# 触发tag
curl --location --request POST 'https://10.1.2.3/v1/pipeline/pipelines/1/manual' \
                    -H 'access_token:{令牌字符串}' \
                    --header 'Content-Type: application/json' \
                    --data '{"externalName":"{tag名}","scmTriggerType":"TAG","variables":null}'

# 触发commit
curl --location --request POST 'https://10.1.2.3/v1/pipeline/pipelines/1/manual' \
                    -H 'access_token:{令牌字符串}' \
                    --header 'Content-Type: application/json' \
                    --data '{"externalName":"{commitID}","scmTriggerType":"COMMIT","variables":null}'

触发成功样例：

~ curl --location --request POST 'https://iii.***.work/v1/pipeline/pipelines/891/manual' \
                    -H 'access_token:a573****755a1677305851601' \
                    --header 'Content-Type: application/json' \
                    --data '{"externalName":"1.1","scmTriggerType":"TAG","variables":null}'
{"code":0,"data":{"id":"168407","companyId":"9","pipelineId":"891","pipelineName":"发布流水线","jobTimeoutMinute":30,"snapshotVersion":"1.1-7","releaseVersion":"","buildNumber":"16","repoKey":"817787672809758720","scmTriggerType":"TAG","externalName":"1.1","commitId":"d507c433b59f5fca28f97695fd89b9a0a175fd03","status":"WAITING","triggerMode":"MANUAL","triggerUser":"guantiantian","externalKey":"","dashboardUrl":"","callbackUrl":"","createTime":1677307422372}}%

~

流水线编辑

流水线管理中最核心的功能是流水线编辑，在流水线配置界面中主要分为如下四个设置部分：

• 基本信息
  此部分主要配置流水线关联的代码库分支、触发条件

• 通知提醒
  此部分主要配置当流水线执行过程中遇到开始、失败、结束等事件时，是否需要通知相关人员。

• 环境变量
  使用场景：
  当系统内置的环境变量无法满足需求时，可在此处编辑自定义环境变量。且环变量在整个流水线的所有任务中均可用。
  
  环境变量的使用：可以在流水线的插件脚本中通过${环境变量名}的方式使用对于保密信息，可以通过密文环境变量实现。
  此处创建的环境变量为静态环境变量，如果希望在插件脚本中通过程序动态创建和修改环境变量，可参考本帮助文档“产品术语->环境变量”章节。

• 阶段&任务 这是流水线配置的核心，整个流水线由串行执行的阶段组成，每个阶段又可以由串行或者并行的任务组成。从而可以实现任意复杂的串并行复杂流水线。

  流水线的跳过功能：
  点击任务前的icon可选择如何执行此任务，此动作包括“自动触发”、“手动触发”、“程序控制”

  

  当选择自动触发时在执行流水线时此任务将会自动执行，当选择手动触发时在执行流水线时需要用户手动触发才能执行此任务。
  程序控制为通过设置变量的值来决定对任务的执行方式：
  
  程序控制的类型有两种分别为：“跳过”、“停止”，其中跳过为满足条件时此任务将跳过不再执行，停止为不执行此任务，用户可手动执行此任务。
  不论是跳过还是停止都需要变量满足条件时才会为此任务执行“跳过”、“执行”，即在流水线中配置的环境变量与变量值、
  触发流水线时填写的环境变量与变量值与程序控制填写的环境变量与变量值相同时才会执行选择的“跳过”或“执行”。
  
  

• 构建集群
  构建集群可以选择内置的Kubernetes构建集群，也可以使用在计算资源模块配置的自定义集群。
  

插件介绍

流水线插件从整体上分为编译构建、构建镜像、发版、部署、测试、扫描和通用类插件

编译构建

编译类插件（如下图）的工作逻辑由三部分组成

• 下载代码（默认为单 commit 克隆）

• 执行编译脚本

• 自动上传制品到半成品库
  对于不同的语言，提供了不同的编译插件
  对于无需编译的语言，例如纯HTML静态页面，只需打包，无需编译，则可以使用代码打包插件
  
  其他插件不会自动下载代码，也不会在构建完毕后自动上传制品

• 按目录结构克隆开关开启后： 将代码库名称一起下载，否则下载代码为代码根目录。

  例如：代码库目录名称为：test/mavenbankend；

  开启开关后克隆代码为：mavenbankend；

  关闭开关后克隆代码为：直接是mavenbankend目录下的文件。

构建镜像

构建镜像插件的基本工作逻辑由五部分组成

• 架构类型（默认与构建资源硬件环境一致）

• 下载代码（默认为单 commit 克隆）

• 执行编译脚本

• 基于 Dockerfile制作镜像

• 推送镜像到制品库的半成品库或推送到外置镜像源上

• 按目录结构克隆开关开启后： 将代码库名称一起下载，否则下载代码为代码根目录。

  例如：代码库目录名称为：test/mavenbankend；

  开启开关后克隆代码为：mavenbankend；

  关闭开关后克隆代码为：直接是mavenbankend目录下的文件。

下面以maven构建插件为例说明：

• 设置任务名称;
• 需要的maven版本号;
• 运行的编译命令（可以将编译脚本放在代码库中,例如名字叫做build.sh，此处直接通过./build.sh执行该脚本）;
• 如果需要上传jar或者war文件、则在编译命令中使用mvn deploy命令上传，系统会根据pom.xml中的配置上传到指定制品库；
• 文件类制品： 打开制作文件制品开关，插件会自动打包并上传构建产出到制品库文件类半成品库（半成品库中版本号即是构建版本号），只需要在构建脚本中将需要打包的文件放在指定路径下即可。
• Docker镜像： 打开制作docker镜像开关，插件会自动打包并上传docker镜像到制品库的docker半成品库（半成品库中版本号即是构建版本号）
  

构建多平台镜像

其中构建镜像插件还可生成支持多平台的镜像。如生成的镜像同时支持arm64、amd64平台。 在流水线的编译构建插件中有架构类型的选择

• 与构建资源硬件环境一致
• 从基础镜像的manifest读取
• 用户自定义

发版插件

代码经过测试，可以发布稳定版本的时候，可以通过此插件发一个正式的三位版本
发版插件主要的工作内容是给代码库创建一个版本Tag、并且把本次构建中，编译插件生成的半成品制品归档到成品库

部署插件

主机部署插件

主机部署插件的功能是自动创建 主机部署 部署任务。
使用主机部署插件之前，需要先在通过 主机部署 配置好主机组、并且在主机组中配置好部 署模板。
在主机部署插件中，只需要简单的选择需要将应用部署到哪个主机组、使用哪个部署模板、 选择半成品制品还是成品即可。
如果选择半成品，则插件会自动根据构建版本号创建主机部署部署任务单。 如果选择成品，则插件会自动根据发布版本号创建 主机部署 部署任务单

Helm 部署

通过此插件，选择k8s 集群、命名空间、填写实例名称、设置相关的参数、选择 chart 库、chart 包、版本、values配置，可以快速通过配置进行 helm 部署。

Helm 模板部署

通过此插件，选择k8s 集群、命名空间、选择模板名称，调用 k8s 管理命名空间下的模板进行部署。

K8S 部署发单

通过此插件，可以调用 k8s 部署模块的模板进行部署。

Yaml 部署

通过此插件，可以写 yaml 文件或者在代码库写 yaml 文件进行在k8s 集群上部署。

测试类插件

内置接口测试

通过此插件，可以调用测试管理接口测试套件，并且支持设置测试质量门禁。

内置性能测试

通过此插件，可以调用测试管理性能测试套件。

Cobertura覆盖率插件

Cobertura覆盖率插件提供了一个开箱即用，可以方便的执行测试并统计测试覆盖率的方法。
插件基本配置：通过配置基本maven环境与版本、命令与测试报告目录即可。
质量门禁：Cobertura插件提供了分支覆盖率和行覆盖率两种质量门禁。当覆盖率低于门禁设置时，会导致任务失败。

Jacoco覆盖率插件

Jacoco覆盖率插件提供了一个开箱即用，可以方便的执行测试并统计测试覆盖率的方法。
插件基本配置：如下图所示，通过配置基本maven环境与版本、命令与测试报告目录即可。
质量门禁：此处可设置当测试通过率低于某数值时，测试任务会被认为失败。Jacoco内置了多种覆盖率统计功能，故可以详细设置多个质量门禁。
关于本插件的详细介绍，请参考本文档“使用技巧->jacoco覆盖率采集插件使用”章节。

Jmete测试

Jmete 测试提供了一个开箱即用，可以方便的执行并统计测试结果和测试报告。

JUnit插件

JUnit插件相对简单，只提供了Junit运行、测试结果查看功能。
插件基本配置：和Maven单测插件相比，只需要设置测试报告目录用以服务端对执行结果进行解析即可。
因为JUnit的测试结果只有xml文件，故插件无需像Maven单测插件那样设置报告查看入口文件。
质量门禁：此处可设置当测试通过率低于某数值时，测试任务会被认为失败。

maven单测插件

Maven单测插件提供了执行maven单测任务、生成测试报告、查看结果数据等功能。 插件基本配置：在插件配置中，只需要配置测试命令、测试报告生成的相对路径、测试报告入口文件即可运行。 质量门禁：此处可设置当测试通过率低于某数值时，测试任务会被认为失败。

扫描类插件

内置代码扫描插件

此插件可以使用系统的代码扫描规则，进行代码扫描，并且支持质量门禁设置。

Sonarqube插件

代码扫描是当前流水线环节的重要一步，流水线内置了Sonarqube 扫描插件，只需要简单配置下Sonarqube信息，即可进行扫描，并支持质量门禁。
项目token 是用户在sonarqube服务器上的令牌、项目名称默认和代码库名称相同、项目版本默认是流水线的构建版本号；

且执行结果会回传给对应的代码库及对应分支，在文件浏览页面即可查看效果。

通用类插件

流水线触发插件

通过此插件，可以非常方便的在流水线的任何位置触发下游流水线

人工审批

通过此插件，可以非常方便的在流水线触发流程审批自定义的审批流。

制作docker 镜像

通过此插件，可以直接基于 dockerfile 依赖的制品进行制作镜像，无需进行编译。

Docker 镜像执行器

通过此插件，可以基于选择镜像环境创建容器，在容器环境中执行脚本。

JenkinsJob

通过此插件，可以调用 jenkins 平台的任务，执行成功并支持跳转到jenkins 平台。

shell 命令

通过此插件，可以执行些基本的 shell 命令。

流水线关联卡片

流水线关联卡片根据当前执行记录的触发事件自动获取卡片列表数据:

手动触发：手动选择的分支、tag或commitID的提交信息关联的卡片。

代码更新：更新的commitID中提交信息关联的卡片。

评审模拟预合入：本次评审生成的新的合入点（commitID）提交信息关联的卡片。

发起及更新MR评审：本次评审源分支到目标分支的commitID中提交信息关联的卡片。

收到及更新DCR评审：本次评审变更的 commitID中提交信息关联的卡片。

定时触发：定时触发的分支、tag或commitID的提交信息关联的卡片。

当流水线基准设置开启后，将以基准设置为基点。

流水线基准设置

流水线基准设置开启

流水线：当执行流水线时，手动触发流水线时，支持选择触发分支和基准分支；自动触发流水线将会根据配置的参数触发流水线。

执行记录：流水线执行记录系统环境变量增加：SYS_BUILD_BASE_COMMIT的值为当时触发流水线设置基准对应的commitId。此变量可以用于整条流水线的任务中。

发布版本插件：发布卡片类型默认为【选择基准】（选择基准默认为流水线设置的基准并不允许修改）；发布卡片列表显示数据为：【设置的基准】和【流水线触发分支】对比相差提交信息（commitMessage）中包含的卡片列表。

其他支持脚本的插件：通过脚本使用此值SYS_BUILD_BASE_COMMIT，可以获取增量代码，实现增量代码进行编译和扫描。

流水线基准设置关闭

执行记录：流水线执行记录系统环境变量增加：SYS_BUILD_BASE_COMMIT的值空。

发布版本插件：发布卡片类型默认为【本次流水线执行记录关联卡片】支持修改类型；