25. Working with Webhooks

A Webhook provides the ability to execute specified commands between apps over the web. Automation controller provides webhook integration with GitHub, GitLab and Bitbucket Data Center. This section describes the procedure for setting up a webhook through GitHub and GitLab; the steps on the services may differ in their current versions, so refer also to their documentation. The Webhook URL of a template has the form https://<koios host>/api/controller/v2/job_templates/<id>/github/ (or .../gitlab/, .../bitbucket_dc/, and workflow_job_templates for workflows); the platform gateway accepts these requests without a platform login, and automation controller checks them with the Webhook key.

The webhook post-status-back functionality for GitHub and GitLab is designed for work only under certain CI events. Receiving another kind of event will result in messages like the one below in the service log:

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

25.1. GitHub webhook setup

Automation controller can launch jobs from GitHub webhook events. To send job status back for supported pull request events, select a GitHub Personal Access Token credential in the template’s Webhook credential field. The token must have permission to update status on the repository. The webhook key authenticates incoming deliveries; the token is used for outgoing status updates. See webhooks in job templates and in workflow job templates.

Edit form for Example Webhook Template with GitHub and Example GitHub token selected
  1. Go to a specific GitHub repo you want to configure webhooks and click Settings.

  2. Under Options, click Webhooks.

  3. On the Webhooks page, click Add webhook.

  4. To complete the Add Webhook page, you need to enable webhooks in a job template (or in a workflow job template), which will provide you with the following information:

    1. Copy the contents of the Webhook URL from the job template, and paste it in the Payload URL field. GitHub uses this address to send results to.

    2. Set the Content type to application/json.

    3. Copy the contents of the Webhook Key from the job template above and paste it in the Secret field.

    4. Leave Enable SSL verification selected.

    5. Next, you must select the types of events you want to trigger a webhook. Any such event will trigger the Job or Workflow. In order to have job status (pending, error, success) sent back to GitHub, you must select Pull requests in the individual events section.

    6. Leave Active checked and click Add Webhook.

  5. After your webhook is configured, it displays in the list of webhooks active for your repo, along with the ability to edit or delete it. Click on a webhook, and it brings you to the Manage webhook screen. Scroll to the very bottom of the screen to view all the delivery attempts made to your webhook and whether they succeeded or failed.

For more information, refer to the GitHub webhooks documentation.

25.2. GitLab webhook setup

Automation controller can launch jobs from GitLab webhook events. To send job status back for supported push, tag push and merge request events, select a GitLab Personal Access Token credential in the template’s Webhook credential field. The token must have permission to update status on the repository. The webhook key authenticates incoming deliveries; the token is used for outgoing status updates. See webhooks in job templates and in workflow job templates.

Edit form for Example Webhook Template with GitLab and Example GitLab token selected
  1. Go to a specific GitLab repo you want to configure webhooks and click Settings > Webhooks.

  2. To add the webhook, you need to enable webhooks in a job template (or in a workflow job template), which will provide you with the following information:

    1. Copy the contents of the Webhook URL from the job template above, and paste it in the URL field. GitLab uses this address to send results to.

    2. Copy the contents of the Webhook Key from the job template above and paste it in the Secret Token field.

    3. Next, you must select the types of events you want to trigger a webhook. Any such event will trigger the Job or Workflow. Automation controller can send the job status (pending, error, success) back to GitLab for Push events, Tag push events and Merge request events.

    4. Leave Enable SSL verification selected.

    5. Click Add webhook.

  3. After your webhook is configured, it displays in the list of Project Webhooks for your repo, along with the ability to test events, edit or delete the webhook. Testing a webhook event displays the results at the top of the page whether it succeeded or failed.

For more information, refer to the GitLab webhooks integrations documentation.

25.3. Payload output

The entire payload is exposed as an extra variable. To view the payload information, open the job launched by the webhook and look at the Extra variables of its Details tab. Automation controller adds these variables, with the tower_ prefix and, while the Include Deprecated AWX Variable Prefix setting is enabled, also with the awx_ prefix:

  • tower_webhook_event_type: the type of event, such as push or pull_request

  • tower_webhook_event_guid: the identifier of the delivery

  • tower_webhook_event_ref: the commit or reference of the event

  • tower_webhook_status_api: the address used to send the status back, when the event has one

  • tower_webhook_payload: the whole payload of the event

The example below shows a job launched by a GitHub push event.

Details of a job launched by a GitHub webhook, with the webhook variables in its extra variables