AWS CLI 实战：使用 create-custom-action-type 创建 CodePipeline 自定义 Action

AWS CLI 实战：使用 create-custom-action-type 创建 CodePipeline 自定义 Action

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

导读

本文讲解如何使用 AWS CLI 的aws codepipeline create-custom-action-type命令，将自建的外部系统（例如 Jenkins 服务器）封装为 CodePipeline 流水线中可复用的自定义 Action。你将掌握自定义 Action JSON 定义文件的完整结构、每个字段的含义与约束、通过--cli-input-json提交定义的方法，以及配套的查询与删除命令，让自定义 Action 真正接入流水线并与外部构建系统联动。文中所有命令与参数均以当前仓库 awscli/examples/codepipeline/create-custom-action-type.rst 及 codepipeline 服务模型 为事实依据。

命令概览：一条命令注册自定义 Action

CodePipeline 允许用户在流水线中使用三类 Action：AWS 官方提供的（Owner 为AWS）、第三方合作伙伴提供的（ThirdParty），以及用户自己注册的（Custom）。当你的构建、测试或部署系统不在 CodePipeline 原生集成列表中时，可以将其注册为自定义 Action。

核心命令只有一条，通过--cli-input-json指向一个预先生成的 JSON 文件：

aws codepipeline create-custom-action-type --cli-input-json file://MyCustomAction.json

该命令没有其他必填的参数选项——定义文件即一切。命令成功后，AWS 会返回所创建 Action 的完整结构（包括id、settings、actionConfigurationProperties、inputArtifactDetails、outputArtifactDetails），作为 JSON 输出到终端。

从服务模型可以看到，该操作对应的 HTTP 请求为POST /，输入形状为CreateCustomActionTypeInput，输出形状为CreateCustomActionTypeOutput（见 service-2.json 中 CreateCustomActionType 的定义）。

JSON 定义文件逐字段详解

MyCustomAction.json是自定义 Action 的"身份证"，以下示例来自官方文档，涵盖了一个 Build 类自定义 Action 的全部要素：

{ "category": "Build", "provider": "MyJenkinsProviderName", "version": "1", "settings": { "entityUrlTemplate": "https://192.0.2.4/job/{Config:ProjectName}/", "executionUrlTemplate": "https://192.0.2.4/job/{Config:ProjectName}/lastSuccessfulBuild/{ExternalExecutionId}/" }, "configurationProperties": [ { "name": "MyJenkinsExampleBuildProject", "required": true, "key": true, "secret": false, "queryable": false, "description": "The name of the build project must be provided when this action is added to the pipeline.", "type": "String" } ], "inputArtifactDetails": { "maximumCount": 1, "minimumCount": 0 }, "outputArtifactDetails": { "maximumCount": 1, "minimumCount": 0 } }

顶层必需字段：category、provider、version

根据服务模型中的CreateCustomActionTypeInput，以下字段为必填：

字段	说明	约束（来自 service-2.json）
category	Action 类别，决定该 Action 在流水线中的语义角色	枚举值：Source、Build、Deploy、Test、Invoke、Approval、Compute
provider	提供方名称，即外部服务的标识	长度 1–35 字符，仅允许[0-9A-Za-z_-]+
version	Action 版本标识，用于区分同一 provider 的多个版本	长度 1–9 字符，仅允许[0-9A-Za-z_-]+
inputArtifactDetails	输入工件数量上下限	minimumCount/maximumCount均为 0–10 的整数
outputArtifactDetails	输出工件数量上下限	同上

category与provider、version三者的组合唯一确定一个 Action 类型，注册后不可重复。选择category时需遵循 CodePipeline 的语义约束：例如 Source 类 Action 通常不应接收输入工件（输入/输出数量均应设 0），而 Build 类 Action 则至少消费一个输入工件、产出一个输出工件。

settings：外部系统 URL 模板

settings用于告诉 CodePipeline 控制台如何跳转到你的外部系统，其四个可选字段定义在ActionTypeSettings形状中：

字段	用途
entityUrlTemplate	控制台流水线视图中展示的深链接，指向外部系统的资源配置页（如 Jenkins 的 Job 页面）
executionUrlTemplate	指向外部系统执行实体的落地页链接，在流水线视图页展示（如某次构建的运行详情页）
thirdPartyConfigurationUrl	外部服务的注册/首次配置页面 URL
revisionUrlTemplate	允许用户更新或变更外部 Action 配置的页面链接

URL 模板中可以嵌入占位符{Config:name}（引用配置属性，该属性必须同时为required: true且secret: false）以及{ExternalExecutionId}（引用外部系统返回的执行 ID）。全部 URL 模板字段长度均为 1–2048 字符。

configurationProperties：配置属性定义

configurationProperties是自定义 Action 的核心——它决定了用户在流水线中添加该 Action 时需要填写哪些配置。ActionConfigurationProperty形状中每个属性的字段如下：

字段	必填	说明与约束
name	是	属性名，1–50 字符
required	是	是否为必填值
key	是	是否为键属性（用于唯一标识该 Action 实例）
secret	是	是否为机密值。机密值会对除GetJobDetails、GetThirdPartyJobDetails、PollForJobs、PollForThirdPartyJobs之外的调用隐藏；更新流水线时传入*****可保留原值
queryable	否	是否用于PollForJobs轮询匹配。一个自定义 Action 最多只能有一个 queryable 属性，且该属性必须required: true且secret: false；当流水线使用该属性时，值必须 ≤20 字符，且仅限字母、数字、下划线和连字符
description	否	展示给用户的描述，1–160 字符
type	否	属性类型，枚举值：String、Number、Boolean

上述示例定义了一个名为MyJenkinsExampleBuildProject的字符串属性，它是必填且作为 key，用户在添加 Action 时必须提供构建项目名。结合settings中的{Config:ProjectName}占位符，CodePipeline 会把用户填写的项目名动态拼入 Jenkins Job 的 URL 中——这正是文档示例中entityUrlTemplate与configurationProperties联动工作的方式。

input/outputArtifactDetails：工件契约

inputArtifactDetails与outputArtifactDetails声明该 Action 消费与产出工件（artifact）的数量范围：

• minimumCount：最少工件数（0–10）；
• maximumCount：最多工件数（0–10）。

示例中 Build Action 输入与输出均为 0–1，表示它可选消费一个输入工件并至多产出一个输出工件，供流水线后续阶段使用。

与流水线定义联动：如何被 ActionTypeId 引用

注册后的自定义 Action 通过流水线定义中的ActionTypeId被引用。ActionTypeId形状包含四个必填字段：category、owner、provider、version，其中owner的合法值为AWS、ThirdParty、Custom。自定义 Action 在流水线 stage 中的 action 配置如下：

{ "name": "MyJenkinsBuild", "actionTypeId": { "category": "Build", "owner": "Custom", "provider": "MyJenkinsProviderName", "version": "1" }, "configuration": { "ProjectName": "MyJenkinsExampleBuildProject" }, "inputArtifacts": [ { "name": "SourceArtifact" } ], "outputArtifacts": [ { "name": "BuildArtifact" } ] }

注意这里的owner必须为Custom，provider与version必须与你注册时使用的值完全一致，configuration中的键即对应注册时configurationProperties中声明的属性名。

验证与生命周期管理：查询、列出与删除

查看所有可用 Action 类型

使用list-action-types并配合--action-owner-filter Custom过滤，可查看当前账号下已注册的自定义 Action：

aws codepipeline list-action-types --action-owner-filter Custom

官方示例 的输出展示了两个已注册的 Build/Test 类自定义 Action，其id中owner均为Custom，settings中 URL 模板引用了{Config:ProjectName}与{ExternalExecutionId}。该命令也用于在删除前核对category、version、provider的准确取值。

删除自定义 Action

使用delete-custom-action-type删除不再使用的 Action，同样通过 JSON 文件指定三元组（category / version / provider）：

aws codepipeline delete-custom-action-type --cli-input-json file://DeleteMyCustomAction.json

{ "category": "Build", "version": "1", "provider": "MyJenkinsProviderName" }

删除成功时命令输出None（见 delete-custom-action-type 示例）。删除操作要求该 Action 不再被任何流水线引用，且category、version、provider必须与注册时完全一致。

错误处理与注意事项

服务模型为CreateCustomActionType声明了以下错误形状（service-2.json）：

• ValidationException：定义文件字段缺失、枚举值非法或违反上述长度/正则约束；
• LimitExceededException：自定义 Action 数量已达账号上限；
• TooManyTagsException/InvalidTagsException：传入的标签过多或标签格式不合法；
• ConcurrentModificationException：与其他请求并发修改冲突。

实际使用中的常见失败点包括：provider或version含非法字符（如空格、点号）；configurationProperties中 queryable 属性不满足"必填且非机密"的组合约束；inputArtifactDetails的 min 大于 max 等。定义 JSON 时建议先用 JSON 校验工具检查格式，再执行命令。

小结

aws codepipeline create-custom-action-type是 CodePipeline 自定义扩展能力的入口：通过一份结构化的 JSON 文件，你可以把任意外部系统封装为标准的 Build/Test/Deploy 等类别 Action，并通过settingsURL 模板与控制台深度联动、通过configurationProperties定义用户配置项、通过工件数量声明接入流水线数据流。配合list-action-types --action-owner-filter Custom与delete-custom-action-type，即可完成自定义 Action 的完整生命周期管理。定义文件结构与全部字段约束均可对照仓库中的 create-custom-action-type.rst 示例 和 codepipeline 服务模型 进行核验。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli