本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用触发器和筛选功能自动启动管道
通过触发器，您可以将管道配置为在特定事件类型或筛选的事件类型时启动，例如检测到特定分支或拉取请求的更改时。触发器可配置为使用中操作的连接的`CodeStarSourceConnection`源操作 CodePipeline GitHub，例如 Bitbucket 和 GitLab。有关使用连接的源操作的更多信息，请参阅[使用 CodeConnections 向管道添加第三方源提供程序](pipelines-connections.md)。
源操作（例如 CodeCommit 和 S3）在进行更改时使用自动变更检测来启动管道。有关更多信息，请参阅 [CodeCommit 源操作和 EventBridge](triggering.md)。
您可以使用控制台或 CLI 来指定触发器。
您可以按如下方式指定筛选类型：
+ **无筛选条件**
此触发器配置会在推送到操作配置中指定的默认分支时启动管道。
+ **指定筛选条件**
您可以添加一个筛选条件，根据特定筛选条件（如代码推送的分支名称）启动管道，并获取确切的提交。这也会将管道配置为，在发生任何更改时都不会自动启动。
+ **Push**
+ 有效的筛选条件组合是：
+ **Git 标签**
包含或排除
+ **分支**
包含或排除
+ **分支 \+ 文件路径**
包含或排除
+ **拉取请求**
+ 有效的筛选条件组合是：
+ **分支**
包含或排除
+ **分支 \+ 文件路径**
包含或排除
+ **不检测更改**
这不会添加触发器，管道也不会在发生任何更改时自动启动。
下表提供了每种事件类型的有效筛选选项。该表还显示了在操作配置中配置自动更改检测时，哪些触发器配置默认为 true 或 false。
****
| 触发器配置 | 事件类型 | 筛选条件选项 | 检测更改 |
| --- | --- | --- | --- |
| 添加触发器 – 无筛选条件 | none | none | true |
| 添加触发器 – 根据推送代码筛选 | 推送事件 | Git 标签、分支、文件路径 | false |
| 添加触发器 – 筛选拉取请求 | 拉取请求 | 分支、文件路径 | false |
| 无触发器 – 不检测 | none | none | false |
**注意**
此触发器类型使用自动更改检测（作为 `Webhook` 触发器类型）。使用此触发器类型的源操作提供程序是为代码推送配置的连接（Bitbucket Cloud GitHub、E GitHub nterprise Server、 GitLab .com 和 GitLab自我管理）。
有关字段定义和更多触发器参考，请参阅
有关 JSON 结构中字段定义的列表，请参阅[`triggers`](pipeline-requirements.md#pipeline.triggers)。
对于筛选，支持 glob 格式的正则表达式模式，详见[使用语法中的 glob 模式](syntax-glob.md)。
**注意**
在某些情况下，对于带有根据文件路径进行筛选的触发器的管道，当首次创建带有文件路径筛选条件的分支时，管道可能无法启动。有关更多信息，请参阅 [具有使用文件路径触发筛选的连接的管道可能不会在创建分支时启动](troubleshooting.md#troubleshooting-file-paths-filtering)。
## 触发器筛选的注意事项
使用触发器时应注意以下几点。
+ 不能为每个源操作指定多个触发器。
+ 可以向一个触发器添加多个筛选条件类型。有关示例，请参阅[4：具有两种推送筛选条件类型的触发器，包含和排除之间存在冲突](#example-filter-multiple-push)。
+ 对于带有分支和文件路径筛选条件的触发器，在首次推送分支时，由于无法访问新创建分支的已更改文件列表，管道将无法运行。
+ 在推送（分支筛选条件）和拉取请求（分支筛选条件）触发器配置相交的情况下，合并拉取请求可能会触发两次管道执行。
+ 对于在拉取请求事件中触发管道的筛选条件，在已关闭拉取请求事件类型中，连接的第三方存储库提供商可能为合并事件设置了独立状态。例如，在 Bitbucket 中，合并的 Git 事件不是拉取请求关闭事件。但是，在中 GitHub，合并拉取请求是一个关闭事件。有关更多信息，请参阅 [不同提供商的触发器的拉取请求事件](#pipelines-filter-pullrequest-events)。
+ 当管道中的多个源操作通过连接引用同一存储库的不同分支时，只有一个分支可以可靠地触发管道。连接的 webhook 订阅是针对管道和存储库的组合注册的，而不是按分支注册的。要解决这个问题，请为每个分支使用单独的管道。
## 不同提供商的触发器的拉取请求事件
下表汇总了 Git 事件（如拉取请求关闭）在不同提供方处对应的拉取请求事件类型。
****
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_cn/codepipeline/latest/userguide/pipelines-triggers.html)
## 触发器筛选条件示例
对于带有推送和拉取请求事件类型筛选条件的 Git 配置，指定的筛选条件可能会相互冲突。以下是推送和拉取请求事件的有效筛选条件组合示例。一个触发器可能包含多种筛选条件类型，例如在触发器配置中包含两种推送筛选条件类型，此时推送请求和拉取请求筛选条件类型之间将采用 OR 运算，这意味着任意条件匹配就会启动管道。同样，每种筛选条件类型都可以包含多个筛选条件，例如文件路径和分支；这些筛选条件将使用 AND 运算，这意味着只有完全匹配才会启动管道。每种过滤器类型都可以包含包含和排除，其中排除优先于包含。如果分支或文件路径与排除模式匹配，则即使它也匹配包含模式，它也不会触发管道。当提交更改多个文件时，将根据过滤器独立评估每个文件；如果任何更改的文件通过（匹配包含但不匹配排除项），则管道将启动。包含/排除中的名称（例如分支名称）使用 OR 运算。以下列表总结了 Git 配置对象各部分的运算。
有关 JSON 结构中的字段定义的列表，以及包含和排除的详细参考，请参阅[`triggers`](pipeline-requirements.md#pipeline.triggers)。
**Example 1：带有分支和文件路径筛选条件的筛选条件类型（AND 运算）**
对于单一筛选条件类型，例如拉取请求，您可以组合筛选条件，这些筛选条件将使用 AND 运算，这意味着只有完全匹配才会启动管道。下面的示例显示了推送事件类型的 Git 配置，它有两个不同的筛选条件（`filePaths` 和 `branches`）。在下面的示例中，`filePaths` 与 `branches` 之间是 AND 运算：
```
{
"filePaths": {
"includes": ["common/**/*.js"]
},
"branches": {
"includes": ["feature/**"]
}
}
```
在上述 Git 配置下，此示例显示了一个事件，该事件会因 AND 运算成功而启动管道执行。换句话说，该筛选条件包含文件路径 `common/app.js`，即使指定的 `refs/heads/feature/triggers ` 分支没有影响，它也会以 AND 启动管道。
```
{
"ref": "refs/heads/feature/triggers",
...
"commits": [
{
...
"modified": [
"common/app.js"
]
...
}
]
}
```
以下示例展示了一个具有上述配置的触发器事件，该事件不会启动管道执行，因为分支能够进行筛选，但文件路径无法筛选。
```
{
"ref": "refs/heads/feature/triggers",
...
"commits": [
{
...
"modified": [
"src/Main.java"
]
...
}
]
}
```
**Example 2：排除优先于包含**
在单个筛选器中，排除优先于包含。下面的示例显示了一个 Git 配置，配置对象中只有一个筛选条件（`branches`）。这意味着，如果分支与排除模式匹配（`feature-branch`在示例中），则管道不会被触发，即使它也与包含模式匹配。如果 include 模式匹配且没有排除模式匹配（例如`main`分支），则管道将被触发。
对于以下示例 JSON：
+ 将提交推送到 `main` 分支将触发管道
+ 将提交推送到 `feature-branch` 分支将不会触发管道
```
{
"branches": {
"Includes": [
"main"
],
"Excludes": [
"feature-branch"
]
}
```
**Example 3：具有推送和拉取请求筛选器类型（OR 操作）、文件路径和分支过滤器（AND 操作）和 includes/excludes （排除优先顺序）的触发器**
触发器配置对象（例如包含推送事件类型和拉取请求事件类型的触发器）在两种事件类型之间使用 OR 运算。以下示例显示了一种触发器配置，其推送事件类型包含 `main` 分支，拉取请求事件类型排除了同一 `main` 分支。此外，推送事件类型排除了一个文件路径 `LICENSE.txt` 并包含了一个文件路径 `README.MD`。对于第二种事件类型，位于`Closed`或`feature-branch`分支（包括）`Created`上的拉取请求会启动管道，而在或分`main`支上创建或关闭拉取请求（已排除）时，管道不会启动。`feature-branch-2`在每种事件类型中，排除优先于包含。例如，对于`feature-branch`分支上的拉取请求事件（包含在拉取请求中），推送事件类型不包括`feature-branch`分支，因此推送不会触发管道。
对于以下示例：
+ 将提交推送到 `README.MD` 文件路径（包含）的 `main` 分支（包含）将触发管道。
+ 在 `feature-branch` 分支（排除）上，推送提交将不会触发管道。
+ 在包含的分支上，编辑 `README.MD` 文件路径（包含）会触发管道。
+ 在包含的分支上，仅编辑`LICENSE.TXT`文件路径（已排除）不会触发管道。但是，如果同一个提交也发生了变化`README.MD`（包括在内），则管道将触发，因为每个文件都是独立评估的。
+ 在`feature-branch`分支上，关闭拉取请求将触发管道，因为`feature-branch`拉取请求事件类型包含在拉取请求事件类型中，CLOSED 事件类型与 CLOSED 事件类型相匹配。
下图显示配置。
以下是用于配置的 JSON 示例。
```
"triggers": [
{
"providerType": "CodeStarSourceConnection",
"gitConfiguration": {
"sourceActionName": "Source",
"push": [
{
"branches": {
"includes": [
"main"
],
"excludes": [
"feature-branch",
"feature-branch-2"
]
},
"filePaths": {
"includes": [
"README.md"
],
"excludes": [
"LICENSE.txt"
]
}
}
],
"pullRequest": [
{
"events": [
"CLOSED",
"OPEN"
],
"branches": {
"includes": [
"feature-branch"
],
"excludes": [
"feature-branch-2",
"main"
]
}
}
]
}
}
]
},
```
**Example 4：具有两种推送筛选条件类型的触发器，包含和排除之间存在冲突**
下图显示了指定对标签 `release-1`（包含）进行筛选的推送筛选条件类型。添加了第二种推送筛选条件类型，指定在分支 `main`（包含）上进行筛选，推送到 `feature*` 分支（排除）不会启动管道。
对于以下示例：
+ 将标签`release-1`（包含在第一个推送过滤器中）的版本推送到`feature-branch`分支（第二个推送过滤器除外）将触发管道，因为两种推送过滤器类型之间使用 OR 操作，并且第一个推送过滤器（标签`release-1`）匹配。`feature*`
+ 从 `main` 分支（第二个推送筛选条件中包含）推送版本将启动管道。
以下“编辑”页面示例显示了两种推送筛选条件类型及其包含和排除的配置。
以下是用于配置的 JSON 示例。
```
"triggers": [
{
"providerType": "CodeStarSourceConnection",
"gitConfiguration": {
"sourceActionName": "Source",
"push": [
{
"tags": {
"includes": [
"release-1"
]
}
},
{
"branches": {
"includes": [
"main*"
],
"excludes": [
"feature*"
]
}
}
]
}
}
]
},
```
**Example 5：在使用默认操作配置 BranchName 进行手动启动时配置触发器**
操作配置默认 `BranchName` 字段定义了手动启动管道时将使用的单个分支，而带有筛选条件的触发器可用于您指定的任何一个或多个分支。
以下是显示 `BranchName` 字段的操作配置的示例 JSON。
```
{
"name": "Source",
"actions": [
{
"name": "Source",
"actionTypeId": {
"category": "Source",
"owner": "AWS",
"provider": "CodeStarSourceConnection",
"version": "1"
},
"runOrder": 1,
"configuration": {
"BranchName": "main",
"ConnectionArn": "ARN",
"DetectChanges": "false",
"FullRepositoryId": "{{owner-name}}/my-bitbucket-repo",
"OutputArtifactFormat": "CODE_ZIP"
},
"outputArtifacts": [
{
"name": "SourceArtifact"
}
],
"inputArtifacts": [],
"region": "us-west-2",
"namespace": "SourceVariables"
}
],
```
以下示例操作输出显示了手动启动管道时使用的默认分支 main。
以下示例操作输出显示了按拉取请求筛选时用于触发器的拉取请求和分支。
