亚马逊 CodeCatalyst 不再向新买家开放。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [如何从中迁移 CodeCatalyst](migration.md)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用触发器自动启动工作流运行 您可以使用 CodeCatalyst 工作流程触发器自动启动 Amazon 工作流程。 *工作流触发器*简称*触发器*，使您可以在发生某些事件（例如代码推送）时自动启动工作流运行。您可能需要配置触发器，使软件开发人员不必通过 CodeCatalyst 控制台手动启动工作流程。 您可以使用三种类型的触发器： + **推送** – 每当推送提交时，代码推送触发器都会启动工作流运行。 + **拉取请求** – 每当创建、修改或关闭拉取请求时，拉取请求触发器都会启动工作流运行。 + **计划** – 计划触发器使工作流运行按您定义的计划启动。您可以考虑使用计划触发器在夜间运行软件的版本，这样在第二天早上可以准备好最新的版本供开发人员处理。 您可以单独使用推送、拉取请求和计划触发器，也可以在同一个工作流中组合使用这些触发器。 触发器是可选的，如果您未配置任何触发器，则只能手动启动工作流。 **提示** 要查看触发器的实际作用，请启动带有蓝图的项目。大多数蓝图都包含带有触发器的工作流。在蓝图的工作流定义文件中查找 `Trigger` 属性。有关蓝图的更多信息，请参阅[使用蓝图创建项目](projects-create.md#projects-create-console-template)。 **Topics** + [示例：工作流中的触发器](workflows-add-trigger-examples.md) + [触发器和分支的使用准则](workflows-add-trigger-considerations.md) + [添加触发器到工作流](workflows-add-trigger-add.md) # 示例：工作流中的触发器 以下示例说明如何在 Amazon CodeCatalyst 工作流程定义文件中添加不同类型的触发器。 有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。 **Topics** + [示例：一个简单的代码推送触发器](#workflows-add-trigger-examples-push-simple) + [示例：一个简单的“push to main”触发器](#workflows-add-trigger-examples-push-main) + [示例：一个简单的拉取请求触发器](#workflows-add-trigger-examples-pull-simple) + [示例：一个简单的计划触发器](#workflows-add-trigger-examples-schedule-simple) + [示例：带有计划和分支的触发器](#workflows-add-trigger-examples-schedule-branches) + [示例：带有计划、推送和分支的触发器](#workflows-add-trigger-examples-schedule-push-branches) + [示例：带有拉取和分支的触发器](#workflows-add-trigger-examples-pull-branches) + [示例：带有拉取、分支和“CLOSED”事件的触发器](#workflows-add-trigger-examples-push-pull-close) + [示例：带有推送、分支和文件的触发器](#workflows-add-trigger-examples-push-multi) + [示例：手动触发器](#workflows-add-trigger-examples-manual) + [示例： CI/CD 多工作流程设置中的触发器](#workflows-add-trigger-usecases) ## 示例：一个简单的代码推送触发器 以下示例显示了一个触发器，在代码被推送到源存储库中的*任何*分支时，该触发器将启动工作流运行。 激活此触发器后，使用您要推送*到*的分支（即目标分支）中的文件 CodeCatalyst 启动工作流程运行。 例如，如果您将提交推送到`main`，则使用工作流定义文件和其他源文件 CodeCatalyst 启动工作流程运行。`main` 再举一个例子，如果您将提交推送到`feature-branch-123`，则使用工作流定义文件和其他源文件 CodeCatalyst 启动工作流程运行。`feature-branch-123` ``` Triggers: - Type: PUSH ``` **注意** 如果您希望只有在推送到 `main` 时才启动工作流运行，请参阅[示例：一个简单的“push to main”触发器](#workflows-add-trigger-examples-push-main)。 ## 示例：一个简单的“push to main”触发器 以下示例显示了一个触发器，在代码被推送到源存储库中的 `main` 分支（而且*仅在*推送到 `main` 分支）时，该触发器将启动工作流运行。 ``` Triggers: - Type: PUSH Branches: - main ``` ## 示例：一个简单的拉取请求触发器 以下示例显示了一个触发器，在源存储库中创建或修订了任何拉取请求时，该触发器将启动工作流运行。 *激活此触发器后，使用工作流程定义文件和您要提取的分支（即源分支）中的其他源文件 CodeCatalyst 启动工作流程运行。* 例如，如果您使用名为的源分支`feature-123`和名为的目标分支创建拉取请求`main`，则使用工作流定义文件和其他源文件 CodeCatalyst 启动工作流程运行。`feature-123` ``` Triggers: - Type: PULLREQUEST Events: - OPEN - REVISION ``` ## 示例：一个简单的计划触发器 以下示例演示了在每星期一到星期五的午夜（UTC\$10）启动工作流运行的触发器。 激活此触发器后，将为源存储库中包含带有此触发器的工作流程定义文件的每个分支 CodeCatalyst 启动一个工作流程运行。 例如，如果您的源存储库中有三个分支、`main``release-v1``feature-123`、，并且每个分支都包含一个带有触发器的工作流程定义文件，则会 CodeCatalyst 启动三个工作流程运行：一个使用中的文件，另一个使用中的文件`main`，另一个使用中的文件`release-v1`，另一个使用中的文件，另一个使用中的文件`feature-123`。 ``` Triggers: - Type: SCHEDULE Expression: "0 0 ? * MON-FRI *" ``` 有关可在 `Expression` 属性中使用的 cron 表达式的更多示例，请参阅[Expression](workflow-reference.md#workflow.triggers.expression)。 ## 示例：带有计划和分支的触发器 以下示例演示了在每天下午 6:15（UTC\$10）启动工作流运行的触发器。 激活此触发器后，使用`main`分支中的文件 CodeCatalyst 启动工作流程运行，然后为以开头的每个分支开始额外运行`release-`。 例如，如果您的源存储库中有名为`main``release-v1``bugfix-1`、、和`bugfix-2`的分支，则会 CodeCatalyst 启动两个工作流程运行：一次使用中的文件`main`，另一次使用中的文件`release-v1`。它*不会*为 `bugfix-1` 和 `bugfix-1` 分支启动工作流运行。 ``` Triggers: - Type: SCHEDULE Expression: "15 18 * * ? *" Branches: - main - release\-.* ``` 有关可在 `Expression` 属性中使用的 cron 表达式的更多示例，请参阅[Expression](workflow-reference.md#workflow.triggers.expression)。 ## 示例：带有计划、推送和分支的触发器 以下示例演示了一个触发器，该触发器在每天午夜（UTC\$10）以及每当有代码推送到 `main` 分支时启动工作流运行。 在本示例中： + 工作流运行在每天午夜启动。工作流运行使用 `main` 分支中的工作流定义文件和其他源文件。 + 每当您将提交推送到 `main` 分支时，也会启动工作流运行。该工作流运行使用目标分支（`main`）中的工作流定义文件和其他源文件。 ``` Triggers: - Type: SCHEDULE Expression: "0 0 * * ? *" Branches: - main - Type: PUSH Branches: - main ``` 有关可在 `Expression` 属性中使用的 cron 表达式的更多示例，请参阅[Expression](workflow-reference.md#workflow.triggers.expression)。 ## 示例：带有拉取和分支的触发器 以下示例演示了一个触发器，每当有人对名为 `main` 的目标分支打开或修改拉取请求时，该触发器就会启动工作流运行。尽管 `Triggers` 配置中指定的分支是 `main`，但工作流运行将使用*源*分支（即您拉取*自*的分支）中的工作流定义文件和其他源文件。 ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` ## 示例：带有拉取、分支和“CLOSED”事件的触发器 以下示例演示了一个触发器，每当有人对以 `main` 开头的分支关闭拉取请求时，该触发器就会启动工作流运行。 在本示例中： + 当您关闭对以 `main` 开头的目标分支的拉取请求时，就会自动启动工作流运行，该工作流将使用（现已关闭）源分支中的工作流定义文件和其他源文件。 + 如果您已将源存储库配置为在合并拉取请求后自动删除分支，则这些分支将永远没有机会进入 `CLOSED` 状态。这意味着合并的分支不会激活拉取请求 `CLOSED` 触发器。在这种情况下，激活 `CLOSED` 触发器的唯一方法是关闭拉取请求而不合并。 ``` Triggers: - Type: PULLREQUEST Branches: - main.* Events: - CLOSED ``` ## 示例：带有推送、分支和文件的触发器 以下示例演示了一个触发器，每当对 `main` 分支上的 `filename.txt` 文件或 `src` 目录中的任何文件进行更改时，该触发器就会启动工作流运行。 激活此触发器后，使用`main`分支中的工作流定义文件和其他源文件 CodeCatalyst 启动工作流程运行。 ``` Triggers: - Type: PUSH Branches: - main FilesChanged: - filename.txt - src\/.* ``` ## 示例：手动触发器 要配置手动触发器，请在工作流定义文件中省略 `Triggers` 部分。如果没有此部分，用户将被迫通过在 CodeCatalyst控制台中选择 “**运行**” 按钮来手动启动工作流程。有关更多信息，请参阅 [手动启动工作流运行](workflows-manually-start.md)。 ## 示例： CI/CD 多工作流程设置中的触发器 此示例介绍当您想要使用单独的 Amazon CodeCatalyst 工作流程进行持续集成 (CI) 和持续部署 (CD) 时，如何设置触发器。 在此场景中，您设置两个工作流： + **CI 工作流** – 在创建或修订拉取请求时，此工作流会构建和测试您的应用程序。 + **CD 工作流** – 在合并拉取请求时，此工作流会构建和部署您的应用程序。 **CI 工作流**的定义文件如下所示： ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION Actions: BuildAction: instructions-for-building-the-app TestAction: instructions-for-test-the-app ``` 该`Triggers`代码指示每当软件开发人员创建拉取请求（或[修改](pull-requests-update.md)拉取请求），要求将其功能分支合并到分支时，就会自动启动工作流程运行。`main` CodeCatalyst 使用源分支（即功能分支）中的源代码启动工作流程运行。 **CD 工作流**的定义文件如下所示： ``` Triggers: - Type: PUSH Branches: - main Actions: BuildAction: instructions-for-building-the-app DeployAction: instructions-for-deploying-the-app ``` 该`Triggers`代码指示在`main`发生合并时自动启动工作流程。 CodeCatalyst 使用`main`分支中的源代码启动工作流程运行。 # 触发器和分支的使用准则 本节介绍设置包含分支的 Amazon CodeCatalyst 触发器时的一些主要指南。 有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。 + **准则 1：**对于推送和拉取请求触发器，如果要指定分支，您必须在触发器配置中指定目标（即“至”）分支。切勿指定源（即“自”）分支。 在以下示例中，从任何分支推送至 `main` 都会激活工作流。 ``` Triggers: - Type: PUSH Branches: - main ``` 在以下示例中，自任何分支拉取请求到 `main` 中都会激活工作流。 ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` + **准则 2：**对于推送触发器，激活工作流后，工作流将使用*目标*分支中的工作流定义文件和源文件运行。 + **准则 3：**对于拉取请求触发器，激活工作流后，工作流将使用*源*分支中的工作流定义文件和源文件运行（即使您在触发器配置中指定了目标分支）。 + **准则 4：**完全相同的触发器，在一个分支中能够运行，但在另一个分支中可能无法运行。 请考虑以下推送触发器： ``` Triggers: - Type: PUSH Branches: - main ``` 如果包含此触发器的工作流定义文件存在于 `main` 中，然后被克隆到 `test`，则工作流永远不会使用 `test` 中的文件自动启动（尽管您可以*手动*启动工作流以使其使用 `test` 中的文件）。请查看**准则 2** 来了解为什么工作流永远不会使用 `test` 中的文件自动运行。 还要考虑以下拉取请求触发器： ``` Triggers: - Type: PULLREQUEST Branches: - main Events: - OPEN - REVISION ``` 如果包含此触发器的工作流定义文件位于 `main` 中，则工作流将永远不会使用 `main` 中的文件运行。（但是，如果您在 `main` 中创建 `test` 分支，则工作流将使用 `test` 中的文件运行。） 请查看**准则 3** 以了解原因。 # 添加触发器到工作流 按照以下说明在您的 Amazon CodeCatalyst 工作流程中添加推送、拉取或计划触发器。 有关触发器的更多信息，请参阅[使用触发器自动启动工作流运行](workflows-add-trigger.md)。 ------ #### [ Visual ] **添加触发器（可视化编辑器）** 1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。 1. 选择您的项目。 1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。 1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。 1. 选择**编辑**。 1. 选择**可视化**。 1. 在工作流图表中，选择**源**和**触发器**框。 1. 在配置窗格中，选择**添加触发器**。 1. 在**添加触发器**对话框中，在字段中提供信息，如下所示。 **触发器类型** 指定触发器的类型。可以使用下列值之一： + **推送**（可视化编辑器）或 `PUSH`（YAML 编辑器） 当更改推送到源存储库时，推送触发器会启动工作流运行。工作流运行将使用您推送*到*的分支（即目标分支）中的文件。 + **拉取请求**（可视化编辑器）或 `PULLREQUEST`（YAML 编辑器） 在源存储库中打开、更新或关闭拉取请求时，拉取请求触发器会启动工作流运行。工作流运行将使用您拉取*自*的分支（即源分支）中的文件。 + **计划**（可视化编辑器）或 `SCHEDULE`（YAML 编辑器） 计划触发器按您指定的 cron 表达式定义的计划来启动工作流运行。对于源存储库中的每个分支，将使用分支的文件启动单独的工作流运行。[要限制在其上激活触发器的分支，请使用**分支**字段（可视化编辑器）或 `Branches` 属性（YAML 编辑器）。] 配置计划触发器时，请遵循以下指南： + 每个工作流只能使用一个计划触发器。 + 如果您在自己的 CodeCatalyst 空间中定义了多个工作流程，我们建议您安排的同时启动不超过 10 个工作流程。 + 确保将触发器的 cron 表达式配置为在两次运行之间留出足够的时间。有关更多信息，请参阅[Expression](workflow-reference.md#workflow.triggers.expression)。 有关示例，请参阅 [示例：工作流中的触发器](workflows-add-trigger-examples.md)。 **拉取请求的事件** 仅当您选择了**拉取请求**触发器类型时，此字段才会显示。 指定将启动工作流运行的拉取请求事件的类型。有效值如下所示： + **拉取请求已创建**（可视化编辑器）或 `OPEN`（YAML 编辑器） 工作流运行将在拉取请求创建后启动。 + **拉取请求已关闭**（可视化编辑器）或 `CLOSED`（YAML 编辑器） 工作流运行将在拉取请求关闭后启动。`CLOSED` 事件的行为不太好说明，最好通过一个例子来理解。请参阅[示例：带有拉取、分支和“CLOSED”事件的触发器](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-pull-close)了解更多信息。 + **对拉取请求进行了新的修订**（可视化编辑器）或 `REVISION`（YAML 编辑器） 工作流运行将在对拉取请求的修订创建后启动。在创建拉取请求时，将创建第一个修订。之后，每当有人将新的提交推送到拉取请求中指定的源分支时，就会创建一个新的修订。如果您在拉取请求触发器中包含 `REVISION` 事件，则可以忽略 `OPEN` 事件，因为 `REVISION` 是 `OPEN` 的超集。 您可以在同一个拉取请求触发器中指定多个事件。 有关示例，请参阅 [示例：工作流中的触发器](workflows-add-trigger-examples.md)。 **计划** 仅当您选择了**计划**触发器类型时，此字段才会显示。 指定 cron 表达式，用于描述您希望何时执行计划的工作流运行。 中的 Cron 表达式 CodeCatalyst 使用以下六字段语法，其中每个字段用空格分隔： *minutes* *hours* *days-of-month* *month* *days-of-week* *year* **cron 表达式示例** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codecatalyst/latest/userguide/workflows-add-trigger-add.html) 在中指定 cron 表达式时 CodeCatalyst，请务必遵循以下准则： + 为每个 `SCHEDULE` 触发器指定一个 cron 表达式。 + 在 YAML 编辑器中，将 cron 表达式用双引号（`"`）括起来。 + 使用协调世界时（UTC）格式指定时间。不支持其他时区。 + 两次运行之间应至少配置 30 分钟的运行间隔。不支持更快的节奏。 + 指定*days-of-month*或字*days-of-week*段，但不能同时指定两者。如果您在其中一个字段中指定值或星号（`*`），则必须在另一个字段中使用问号（`?`）。星号表示“全部”，问号表示“任何”。 有关 cron 表达式的更多示例以及有关通配符（如`?`、和）的信息 `*``L`，请参阅《*亚马逊 EventBridge *用户指南[》中的 Cron 表达式参考](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html)。 EventBridge 和中的 Cron 表达式 CodeCatalyst 的工作方式完全相同。 有关计划触发器的示例，请参阅[示例：工作流中的触发器](workflows-add-trigger-examples.md)。 **分支**和**分支模式** （可选） 指定触发器监控的源存储库中的分支，以便知道何时启动工作流运行。您可以使用正则表达式模式来定义分支名称。例如，使用 `main.*` 来匹配以 `main` 开头的所有分支。 根据触发器的类型，要指定的分支会有所不同： + 对于推送触发器，请指定要推送*至*的分支，即*目标*分支。对于每个匹配的分支，将使用匹配分支中的文件，启动一个工作流运行。 示例：`main.*`、`mainline` + 对于拉取请求触发器，请指定要推送*至*的分支，即*目标*分支。对于每个匹配的分支，将使用工作流定义文件和**源**分支（*不是*匹配的分支）中的文件，启动一个工作流运行。 示例：`main.*`、`mainline`、`v1\-.*`（匹配以 `v1-` 开头的分支） + 对于计划触发器，请指定包含您希望计划运行使用的文件的分支。对于每个匹配的分支，将使用工作流定义文件和匹配分支中的源文件，启动一个工作流运行。 示例：`main.*`、`version\-1\.0` **注意** 如果您*未*指定分支，则触发器会监控源存储库中的所有分支，并将使用以下位置中的工作流定义文件和源文件启动工作流运行： 您要推送*至*的分支（对于推送触发器）。有关更多信息，请参阅[示例：一个简单的代码推送触发器](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-simple)。 您要拉取*自*的分支（对于拉取请求触发器）。有关更多信息，请参阅[示例：一个简单的拉取请求触发器](workflows-add-trigger-examples.md#workflows-add-trigger-examples-pull-simple)。 所有分支（对于计划触发器）。源存储库中的每个分支将启动一个工作流运行。有关更多信息，请参阅[示例：一个简单的计划触发器](workflows-add-trigger-examples.md#workflows-add-trigger-examples-schedule-simple)。 有关分支和触发器的更多信息，请参阅[触发器和分支的使用准则](workflows-add-trigger-considerations.md)。 有关更多示例，请参阅[示例：工作流中的触发器](workflows-add-trigger-examples.md)。 **文件已更改** 仅当您选择了**推送**或**拉取请求**触发器类型时，才会显示此字段。 指定触发器监控的源存储库中的文件或文件夹，以便知道何时启动工作流运行。您可以使用正则表达式来匹配文件名或路径。 有关示例，请参阅 [示例：工作流中的触发器](workflows-add-trigger-examples.md)。 1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。 1. 选择**提交**，输入提交消息，然后再次选择**提交**。 ------ #### [ YAML ] **添加触发器（YAML 编辑器）** 1. 打开 CodeCatalyst 控制台，[网址为 https://codecatalyst.aws/](https://codecatalyst.aws/)。 1. 选择您的项目。 1. 在导航窗格中，选择 **CI/CD**，然后选择**工作流**。 1. 选择工作流的名称。您可以按定义工作流的源存储库或分支名称筛选，也可以按工作流名称或状态筛选。 1. 选择**编辑**。 1. 选择 **YAML**。 1. 根据以下示例的指导，添加 `Triggers` 部分和底层属性。有关更多信息，请参阅 [工作流 YAML 定义](workflow-reference.md)中的[Triggers](workflow-reference.md#triggers-reference)。 代码推送触发器类似于下文： ``` Triggers: - Type: PUSH Branches: - main ``` 拉取请求触发器类似于下文： ``` Triggers: - Type: PULLREQUEST Branches: - main.* Events: - OPEN - REVISION - CLOSED ``` 计划触发器类似于下文： ``` Triggers: - Type: SCHEDULE Branches: - main.* # Run the workflow at 1:15 am (UTC+0) every Friday until the end of 2023 Expression: "15 1 ? * FRI 2022-2023" ``` 有关可在 `Expression` 属性中使用的 cron 表达式的更多示例，请参阅[Expression](workflow-reference.md#workflow.triggers.expression)。 有关推送、拉取请求和计划触发器的更多示例，请参阅[示例：工作流中的触发器](workflows-add-trigger-examples.md)。 1. （可选）选择**验证**，在提交之前验证工作流的 YAML 代码。 1. 选择**提交**，输入提交消息，然后再次选择**提交**。 ------