配置流水线参数

什么是流水线参数

流水线参数是在流水线运行过程中使用的可配置值，用于控制流水线的行为、流程和输出结果，流水线参数可以传递给各个任务使用，实现任务间数据流动的统一，只需要配置好流水线参数，即可完成构建、部署、接口测试等任务的数据拉通。流水线参数包括以下三种。

系统预定义参数：系统默认提供的参数，无需定义、不能删除、不能修改。
自定义参数：根据需要自定义添加，参数类型包括字符串类型、枚举类型、自增长类型。最多可以新建100个自定义参数。
通用参数组：项目下通用流水线参数，所有流水线都可以关联并使用通用参数组。最多可以新建5个通用参数组，每个参数组最多可以添加20个自定义参数。

约束与限制

新建流水线时如果设置了别名，可基于别名生成仓库对应的系统参数，未设置别名则以仓库名作为别名，生成系统参数，如：“别名_TAG”，表示仓库标签名称。
当存在同名参数时，参数优先级为：系统预定义参数 > 自定义参数 > 通用参数组。
当同一条流水线关联多个参数组，且多个参数组存在同名参数时，以最后关联的参数组的参数取值为准。

前提条件

已开通并授权使用CodeArts Pipeline。
当用户角色为“项目管理员”或者“流水线创建者”，可以配置流水线参数，权限配置请参考授权流水线服务。

配置流水线参数

介绍流水线预定义参数、自定义参数和通用参数组。

流水线系统预定义参数请参见表1，参数引用形式：${参数名}，在参数输入框输入“$”符号后会自动出现系统预定义参数列表。

表1 流水线系统预定义参数
参数信息	说明
PROJECT_ID	当前流水线所属项目ID。
PIPELINE_ID	当前流水线ID。
PIPELINE_NUMBER	流水线执行编号。
COMMIT_ID	执行时代码最后一次提交的ID。
COMMIT_ID_SHORT	执行时代码最后一次提交的短ID。
TIMESTAMP	流水线执行时间戳。例如：20211222124301。
PIPELINE_TRIGGER_TYPE	流水线触发类型。包括：Manual、Scheduler、RollBack以及WebHook类型（CreateTag、Note、Issue、MR、Push）。
PIPELINE_NAME	流水线名称。
REPO_URL	代码仓地址（HTTPS）。
EXECUTE_USER	执行人。
EXECUTE_USER_ID	执行人ID。
EXECUTE_USER_NAME	执行人名称。
EXECUTE_USER_NICKNAME	执行人昵称。
PASS_CONDITIONS_LINK	流水线执行详情链接。
PIPELINE_RUN_ID	流水线执行ID。
MERGE_ID	合并请求ID。
WEBHOOK_PAYLOAD	Webhook请求负载信息。
COMPONENT_CHANGE_IDS	变更ID列表(<ID1>, <ID2>, ...<IDn>)。若基于变更运行则为运行的变更ID列表，若基于代码源运行则为微服务中关联对应代码仓的变更ID列表。
Repo01_REPOSITORY_NAME	仓库名称。
Repo01_SOURCE_BRANCH	合并请求触发流水线时的仓库运行源分支名称。
Repo01_TARGET_BRANCH	仓库运行目标分支名称。
Repo01_TAG	仓库标签名称。
Repo01_COMMIT_ID	仓库执行时代码最后一次提交的ID。
Repo01_COMMIT_ID_SHORT	执行时代码最后一次提交的短ID。
Repo01_REPO_URL	代码仓地址（HTTPS）。

介绍流水线自定义参数的新建和配置。参数引用形式：${参数名}，在参数输入框输入“$”符号后会自动出现自定义参数列表。

访问CodeArts Pipeline首页。
在流水线列表页搜索目标流水线，单击操作列，选择“编辑”。
进入流水线“任务编排”页面，切换至“参数设置”页面。

单击参数列表下的“立即新建”（已存在自定义参数，则单击“新建参数”），填写参数信息。

图1 新建自定义参数
点击放大

表2 流水线自定义参数说明
参数信息	说明	取值样例
名称	自定义参数名称，不可与系统预定义参数名称相同。支持大小写英文字母、数字、“_”，长度不超过128个字符。	输入“test01”。
类型	参数可选类型：字符串、自增长、枚举，默认选择字符串类型。	选择“字符串”。
默认值	自定义参数的默认取值。字符串：长度不超过8192个字符，可以为空。自增长：长度不超过8192个字符。不能为空。自增长类型参数如果被引用，全新执行一次后，下次执行时参数值末位如果是数字则会自动加1。枚举：长度不超过8192个字符，仅支持中文、大小写英文字母、数字、“-”、“_”、“,”、“.”、“/”。选择枚举类型后，在弹出的对话框中添加可选取值，可选取值不能为空。添加完成后在“默认值”下拉框中选择一个默认值，支持输入关键词搜索过滤。	输入“releaseversion”。
私密参数	参数为私密参数时，系统会将输入参数做加密存储，并在使用时自动解密。该参数在运行日志中不可见，且在流水线复制时不会被同步复制。仅字符串类型参数可设置为私密参数。	-
运行时设置	打开“运行时设置”开关，在手动执行流水线时支持修改该参数的值。	单击打开“运行时设置”。
参数描述	对该自定义参数的相关描述，长度不超过512个字符。	-
操作	单击“操作”列，可以新增参数。单击“操作”列，可以删除参数。	-

配置完成后，单击“保存”，弹出“保存信息成功”提示，保存流水线成功。

通过项目入口方式访问CodeArts Pipeline首页。
切换至“通用参数组”页面，单击“新建参数组”。

进入“新建通用参数组”页面，参考表3填写参数信息。

图2 新建通用参数组

点击放大

表3 通用参数组参数说明
基本信息	说明	取值样例
所属项目	通用参数组归属项目，不可更改。	默认为“project01”。
参数组名称	仅支持大小写英文字母、数字、“_”，长度不超过128个字符。	输入“group01”。
描述	对所新建的通用参数组的描述，长度不超过512个字符。	-
自定义参数列表	单击“立即新建”，可根据需要添加自定义参数，参数配置方法同自定义参数。	配置示例如下图：

单击“确定”，完成新建通用参数组。
找到需要关联通用参数组的流水线，单击操作列，选择“编辑”，单击“参数设置” ，单击“通用参数组”，进入“通用参数组”页面。
单击“立即关联”，选择需要关联的参数组，单击“确定”，即可将参数组关联到当前流水线。
- 展开通用参数组，可以查看参数详情。
- 单击操作列，可以解除关联参数组。
图3 关联参数组
配置完成后，单击“保存”，弹出“操作成功”提示，保存成功。

流水线参数应用示例

本文以通过流水线统一配置releaseversion参数并传递到构建任务为例，介绍流水线参数使用方法。

新建构建任务。
单击“参数设置”，在“参数设置”页面添加releaseversion参数并设置好默认值，打开“运行时设置”。

图4 新建构建任务参数
单击“构建步骤”，切换至“构建步骤”页面，单击“点击添加构建步骤”，选择“上传软件包到软件发布库”，将鼠标移动至插件卡片，单击“添加”，将“发布版本号”配置为引用参数形式。在参数输入框输入“$”符号后会自动出现参数列表，选择上一步已经新建好的releaseversion参数。使用“$”符号引用通用参数组的参数时不会自动生成提示。

图5 引用构建任务参数
配置完成后，单击“保存”，保存构建任务。
新建流水线，选择“空白模板”，在流水线阶段添加一个新的任务，然后在该任务中添加“Build构建”插件并调用刚创建的构建任务，即可看到刚新建好的构建任务参数releaseversion。

图6 配置构建任务参数
将鼠标移动到releaseversion参数上，单击“设置为流水线参数”，可以将该参数设置为流水线参数并能直接引用该参数；或直接单击“确定”，单击“参数设置”，切换到流水线“参数设置”页面，新建流水线参数releaseversion，类型可以根据需求选择自增长或字符串等，设置默认值并打开“运行时设置”。

图7 新建流水线参数
单击“任务编排”，切换至“任务编排”页面，编辑刚添加的构建任务，将流水线的releaseversion参数通过“$”符号引用到构建任务的releaseversion参数内。

图8 引用流水线参数
- 该处只显示构建任务中开启“运行时设置”的文本类型参数。
- 鼠标移至参数名称，可以快速将该参数设置为流水线参数并能直接引用该参数。
完成参数引用后，保存信息，然后单击“保存并执行”，弹出“执行配置”弹窗，可查看“运行参数配置”。

运行参数配置值默认为添加参数时为参数设置的默认值，可根据需要进行修改。流水线运行时在构建任务内使用的就是此时输入的参数值。
设置完参数，单击“执行”，开始使用配置的参数执行流水线。