Documentation

22. 使用 Webhook

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

22.1. GitHub webhook 设置

要为 GitHub 设置 webhook,您可能需要选择性地让 Tower 能够在您基于传入的 webhook 运行作业时回发状态。如果您确定您不希望 Tower 将作业状态回发到 webhook 服务,请跳过第 1-2 步并直接进入:ref:step 3 <ug_webhooks_setup_github>

  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 保留为选中状态。

    5. 接下来,您可以选择要触发 webhook 的事件类型。

    6. Active 保留为选中状态,并点击 Add Webhook

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

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

有关详情请参阅 GitHub Webhooks developer documentation

22.2. GitLab webhook 设置

要为 GitLab 设置 webhook,您可能需要选择性地让 Tower 能够在您基于传入的 webhook 运行作业时回发状态。如果您确定您不希望 Tower 将作业状态回发到 webhook 服务,请跳过第 1-2 步并直接进入:ref:step 3 <ug_webhooks_setup_gitlab>

  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. 在 Trigger 部分,选择要触发 Webhook 的事件类型。

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

    5. 点击 Add webhook

_images/webhooks-gitlab-repo-add-webhook.png
  1. 配置了 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