26. 使用 Webhook

一个 Webhook 提供了在应用程序之间通过网络执行指定命令的功能。AWX 目前提供与 GitHub 和 GitLab 的 Webhook 集成。本节介绍了通过各自服务设置 Webhook 的过程。

GitHub 和 GitLab 的 Webhook 后状态回传功能仅在某些 CI 事件下设计为工作。接收其他类型的事件将在服务日志中导致如下所示的消息

awx.main.models.mixins Webhook event did not have a status API endpoint associated, skipping.

26.1. GitHub Webhook 设置

AWX 能够根据传入的触发 Webhook 事件运行作业。作业状态信息（待处理、错误、成功）仅可针对拉取请求事件发送回。如果您确定不希望 AWX 将作业状态回传到 Webhook 服务，请跳过步骤 1-2，直接转到 步骤 3。

  1. 可选地生成一个用于与 AWX 配合使用的个人访问令牌 (PAT)。

    1. 在您的 GitHub 帐户的个人资料设置中，点击**设置**。

    2. 在设置的最底部，点击**<> 开发者设置**。

    3. 在开发者设置中，点击**个人访问令牌**。

    4. 在个人访问令牌屏幕上，点击**生成新令牌**。

    5. 出现提示时，输入您的 GitHub 帐户密码以继续。

    6. 在**备注**字段中，输入关于此 PAT 将用于什么的简要说明。

    7. 在范围字段中，自动化 Webhook 仅需要存储库范围的访问权限，邀请除外。有关其他范围的信息，请点击表格上方的链接以访问文档。

    Link to more information on scopes

    1. 点击**生成令牌**按钮。

    2. 生成令牌后，请确保复制 PAT，因为它将在后面的步骤中使用。您将无法在 GitHub 中再次访问此令牌。

  2. 使用 PAT 可选地创建 GitHub 凭据

    1. 转到您的实例，并使用上面生成的令牌 为 GitHub PAT 创建新的凭据。

    2. 记下此凭据的名称，因为它将在回传到 GitHub 的作业模板中使用。

    Enter your generated PAT into the Token field

    1. 转到您要启用 Webhook 的作业模板，并选择您在上一步中创建的 Webhook 服务和凭据。

    Select the webhook service and credential you created

    1. 点击**保存**。现在您的作业模板已设置为能够回传到 GitHub。一个示例可能如下所示

    An example GitHub status that shows all checks have passed

  1. 转到您要配置 Webhook 的特定 GitHub 存储库，然后点击**设置**。

Settings link in your GitHub repo

  1. 在选项下，点击**Webhook**。

Webhooks link under Options

  1. 在 Webhook 页面上，点击**添加 Webhook**。

  2. 要完成添加 Webhook 页面，您需要 在作业模板中启用 Webhook（或在 工作流作业模板中），这将为您提供以下信息

    1. 复制作业模板中**Webhook URL**的内容，并将其粘贴到**有效负载 URL**字段中。GitHub 使用此地址发送结果。

    2. 将**内容类型**设置为**application/json**。

    3. 复制上面作业模板中**Webhook 密钥**的内容，并将其粘贴到**密钥**字段中。

    4. 保持**启用 SSL 验证**处于选中状态。

    Add Webhook page

    1. 接下来，您必须选择要触发 Webhook 的事件类型。任何此类事件都将触发作业或工作流。为了将作业状态（待处理、错误、成功）发送回 GitHub，您必须在单个事件部分中选择**拉取请求**。

    List of trigger events for the webhook

    1. 保持**激活**处于选中状态，然后点击**添加 Webhook**。

    Active option and Add Webhook button

  3. 配置 Webhook 后，它将显示在您的存储库中活动 Webhook 的列表中，并可以选择编辑或删除它。点击 Webhook，它将带您进入管理 Webhook 屏幕。滚动到屏幕的最底部，以查看发送到您的 Webhook 的所有传递尝试以及它们是成功还是失败。

An example listing of recent deliveries

有关更多信息，请参阅 GitHub Webhook 开发人员文档。

26.2. GitLab Webhook 设置

AWX 能够根据传入的触发 Webhook 事件运行作业。作业状态信息（待处理、错误、成功）仅可针对合并请求事件发送回。如果您确定不希望 AWX 将作业状态回传到 Webhook 服务，请跳过步骤 1-2，直接转到 步骤 3。

  1. 可选地，生成一个个人访问令牌 (PAT)。此令牌使 AWX 能够在根据传入的 Webhook 运行作业时回传状态。

    1. 在您的 GitLab 帐户的个人资料设置中，点击**设置**。

    2. 在侧边栏中，在用户设置下，点击**访问令牌**。

      Access Tokens link under User Settings

    3. 在**名称**字段中，输入关于此 PAT 将用于什么的简要说明。

    4. 跳过**过期时间**字段，除非您希望为您的 Webhook 设置过期日期。

    5. 在范围字段中，选择适用于您的集成的字段。对于 AWX，API 是唯一必要的选项。

    Personal Access Token page

    1. 点击**创建个人访问令牌**按钮。

    2. 生成令牌后，请确保复制 PAT，因为它将在后面的步骤中使用。您将无法在 GitLab 中再次访问此令牌。

  2. 使用 PAT 可选地创建 GitLab 凭据

    1. 转到您的实例，并使用上面生成的令牌 为 GitLab PAT 创建新的凭据。

    2. 记下此凭据的名称，因为它将在回传到 GitHub 的作业模板中使用。

    Create New Credential page

    1. 转到您要启用 Webhook 的作业模板，并选择您在上一步中创建的 Webhook 服务和凭据。

    Select the webhook credential you created

    1. 点击**保存**。现在您的作业模板已设置为能够回传到 GitLab。一个示例可能如下所示

    An example GitLab status message

  1. 转到您要配置 Webhook 的特定 GitLab 存储库，然后点击**设置 > 集成**。

Integrations link under Settings

  1. 要完成集成页面，您需要 在作业模板中启用 Webhook（或在 工作流作业模板中），这将为您提供以下信息

    1. 复制上面作业模板中**Webhook URL**的内容，并将其粘贴到**URL**字段中。GitLab 使用此地址发送结果。

    2. 复制上面作业模板中**Webhook 密钥**的内容，并将其粘贴到**密钥令牌**字段中。

    3. 接下来，您必须选择要触发 Webhook 的事件类型。任何此类事件都将触发作业或工作流。为了将作业状态（待处理、错误、成功）发送回 GitLab，您必须在触发器部分中选择**合并请求事件**。

    4. 保持**启用 SSL 验证**处于选中状态。

    5. 点击**添加 Webhook**。

Integrations page

  1. 配置 Webhook 后，它将显示在您的存储库的项目 Webhook 列表中，并可以选择测试事件、编辑或删除 Webhook。测试 Webhook 事件将在页面顶部显示结果，表明它是成功还是失败。

有关更多信息，请参阅 GitLab Webhook 集成文档。

26.3. 有效负载输出

整个有效负载作为额外变量公开。要查看有效负载信息，请转到启用了 Webhook 的作业模板的作业详细信息视图。在详细信息窗格的**额外变量**字段中，查看来自 awx_webhook_payload 变量的有效负载输出，如下面的示例所示。

Details page with payload output Variables field expanded view