Documentation

22. 使用 Webhook

Webhook 提供了通过 Web 在应用程序间执行指定命令的功能。Ansible Tower 目前提供了与 GitHub 和 GitLab 的 webhook 集成。这个部分介绍了通过各自服务在 Tower 中设置 webhook 的步骤。

webhook 的 GitHub 和 GitLab 的 post-status-back 功能仅用于在特定 CI 事件下工作。接收另一类事件会导致在 Tower 日志中出现类似以下的消息:

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

22.1. GitHub webhook 设置

Tower 可根据触发的 webhook 事件运行作业。作业状态信息(待定、错误、成功)只能针对拉取请求事件发回。如果您确定不希望 Tower 将作业状态回发到 webhook 服务,请跳过第 1-2 步并直接进入 step 3

  1. (可选)生成用于 Tower 的个人访问令牌 (PAT)。

    1. 在 GitHub 帐户的配置集设置中,点击 Settings

    2. 在 Personal settings 下,点击 Developer Settings

      _images/webhooks-create-webhook-github-settings.png
    3. 在 Developer settings 中,点击 Personal access tokens

    4. 在 Personal access tokens 屏幕中点击 Generate new token

    5. 提示时,请输入您的 GitHub 帐户密码以继续。

    6. Note 字段中,输入有关此 PAT 用途的简要描述。

    7. 在 Scope 字段中,Tower 自动化 webhook 只需要范围访问权限,但邀请例外。有关其他范围的信息,请点击表上方的链接来访问文档。

    _images/webhooks-create-webhook-github-scope.png
    1. 点击 Generate Token 按钮。

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

  2. 使用 PAT 在 Tower 中创建 GitHub 凭证(可选):

    1. 进入您的 Tower 实例,并使用上面生成的令牌:ref:create a new credential for the GitHub PAT <ug_credentials_github>

    2. 记下此凭证的名称,因为它将用于回发到 GitHub 的作业模板。

    _images/webhooks-create-credential-github-PAT-token.png
    1. 进入您要启用 webhook 的作业模板,然后选择 webhook 服务和您在上一步中创建的凭证。

    _images/webhooks-job-template-gh-webhook-credential.png

    1. 点击 Save。现在,您的作业模板已设置为可以回发到 GitHub。某个示例可能类似如下:

    _images/webhooks-tower-to-github-status.png
  1. 进入您要配置 webhook 的特定 GitHub 存储库,并点击 Settings

_images/webhooks-github-repo-settings.png
  1. 在 Options 下,点击 Webhooks

_images/webhooks-github-repo-settings-options.png
  1. 在 Webhooks 页面中,点击 Add webhook

  2. 要完成 Add Webhook 页面,您需要:ref:`enable webhooks in a job template in Tower <ug_jt_enable_webhooks>`(或者在:ref:`workflow job template <ug_wfjt_enable_webhooks>`中),这会为您提供以下信息:

    1. 从 Tower 作业模板中复制 Webhook URL 的内容,并将它粘贴到 Payload URL 字段中。GitHub 使用这个地址来发送结果。

    2. Content type 设置为 application/json

    3. 从上面的 Tower 作业模板中复制 Webhook Key 的内容,并将它粘贴到 Secret 字段中。

    4. Enable SSL verification 保留为选中状态。

    _images/webhooks-github-repo-add-webhook.png

    1. 接下来,您必须选择要触发 webhook 的事件类型。任何这样的事件都会触发作业或工作流。为了使作业状态(待定、错误、成功)可以返回 GitHub,您必须在单独的 events 部分中选择 Pull requests

    _images/webhooks-github-repo-choose-events.png
    1. Active 保留为选中状态,并点击 Add Webhook

    _images/webhooks-github-repo-add-webhook-actve.png
  3. 配置了 webhook 后,它会显示在您的存储库的活跃 webhook 列表中,并允许编辑或删除。点击 Webhook 会转到 Manage webhook 屏幕。滚动到屏幕的最底部,查看所有对 webhook 所做的传送尝试,以及它们是成功还是失败。

_images/webhooks-github-repo-webhooks-deliveries.png

有关详情请参阅 GitHub Webhooks developer documentation

22.2. GitLab webhook 设置

Tower 可根据触发的 webhook 事件运行作业。作业状态信息(待定、错误、成功)只能针对 merge 请求事件发回。如果您确定不希望 Tower 将作业状态回发到 webhook 服务,请跳过第 1-2 步并直接进入 step 3

  1. (可选)生成用于 Tower 的个人访问令牌 (PAT)。此令牌可让 Tower 在我们基于传入的 webhook 运行作业时回发状态。

    1. 在 GitLab 帐户的配置集设置中,点击 Settings

    2. 在侧边栏中,点击 User Settings 下的 Access Tokens

      _images/webhooks-create-webhook-gitlab-settings.png
    3. Name 字段中,输入有关此 PAT 用途的简要描述。

    4. 跳过 Expires at 字段,除非您要为您的 webhook 设置过期日期。

    5. 在 Scopes 字段中,选择适用于您的集成的范围。对于 Tower,API 是必不可少的唯一选择。

    _images/webhooks-create-webhook-gitlab-scope.png
    1. 点击 Create personal access token 按钮。

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

  2. 使用 PAT 在 Tower 中创建 GitLab 凭证(可选):

    1. 进入您的 Tower 实例,并使用上面生成的令牌:ref:create a new credential for the GitLab PAT <ug_credentials_gitlab>

    2. 记下此凭证的名称,因为它将用于回发到 GitHub 的作业模板。

    _images/webhooks-create-credential-gitlab-PAT-token.png
    1. 进入您要启用 webhook 的作业模板,然后选择 webhook 服务和您在上一步中创建的凭证。

    _images/webhooks-job-template-gl-webhook-credential.png

    1. 点击 Save。现在,您的作业模板已设置为可以回发到 GitLab。某个示例可能类似如下:

    _images/webhooks-tower-to-gitlab-status.png
  1. 进入您要配置 Webhook 的特定 GitLab 存储库,并点击 Settings > Integrations

_images/webhooks-gitlab-repo-settings.png
  1. 要完成 Integrations 页面,您需要:ref:`enable webhooks in a job template in Tower <ug_jt_enable_webhooks>`(或者在:ref:`workflow job template <ug_wfjt_enable_webhooks>`中),这会为您提供以下信息:

    1. 从上面的 Tower 作业模板中复制 Webhook URL 的内容,并将它粘贴到 URL 字段中。GitLab 使用这个地址来发送结果。

    2. 从上面的 Tower 作业模板中复制 Webhook Key 的内容,并将它粘贴到 Secret Token 字段中。

    3. 接下来,您必须选择要触发 webhook 的事件类型。任何这样的事件都会触发作业或工作流。为了使作业状态(待定、错误、成功)可以返回到 GitLab,您必须在 Trigger 部分中选择 Merge request events

    4. Enable SSL verification 保留为选中状态。

    5. 点击 Add webhook

_images/webhooks-gitlab-repo-add-webhook.png
  1. 配置了 webhook 后,它会显示在您的存储库的项目 Webhook 列表中,并可以测试事件、编辑或删除 webhook。测试 webhook 事件后,会在页面顶部显示结果,无论是成功还是失败。

有关详情请参阅 GitLab webhooks integrations documentation

22.3. 有效负载 (playload) 输出

整个有效负载会作为 Tower 中的额外变量公开。要查看有效负载信息,请找到在启用了 Webhook 的情况下运行的作业模板,进入其作业详情视图。在 Details 窗格的 Extra Variables 字段中查看 tower_webhook_payload 变量的有效负载输出,如下例所示。

_images/webhooks-jobs-extra-vars-payload.png _images/webhooks-jobs-extra-vars-payload-expanded.png