Can I have an SCM (Source Code Management) update trigger the launch of an AWX job? The answer is yes, and it’s one of the interesting things I can do to remote-control AWX.
What I need is some way to invoke a program as soon as I commit something. Subversion, git, etc. support hooks, but cloud-based repository systems (Github, Bitbucket) also support Webhooks which I’ll use here.
In this example I’m using gitea which calls itself a painless self-hosted Git service; it’s all of that and more – it’s one of those gorgeous single-binary Go programs which I’m liking more and more. (I showed you another recently – CoreDNS.) Gitea is very much like using Github, but you host it yourself, and it’s trivial to get started with it.
Within gitea, I configure an outgoing Webhook:
From now on, as soon as this repository gets a commit pushed to it, the specified URL will be invoked
On the other side, I run a lightweight, configurable utility (again in Go), called adnanh/webhook. This listens for HTTP payloads, extracts JSON from them, and it can invoke a program of my choice to react to the hook. This could be any kind of HTTP endpoint which reacts to a Webhook POST, but I chose this for simplicity.
I configure webhook to run with the following configuration, which will extract the repository’s name and the secret specified in the hook invocation from the incoming payload (here is the full payload sent by gitea).
[
{
"id": "awx-atest",
"execute-command": "/Users/jpm/bin/awx-hook.sh",
"command-working-directory": "/tmp/",
"pass-arguments-to-command": [
{
"source": "payload",
"name": "repository.full_name"
},
{
"source": "payload",
"name": "secret"
}
]
}
]I launch webhook and watch what happens when I commit and push to the repository:
./webhook -hooks hooks.json -verbose
[webhook] 2017/10/23 18:17:07 version 2.6.5 starting
[webhook] 2017/10/23 18:17:07 setting up os signal watcher
[webhook] 2017/10/23 18:17:07 attempting to load hooks from hooks.json
[webhook] 2017/10/23 18:17:07 os signal watcher ready
[webhook] 2017/10/23 18:17:07 found 1 hook(s) in file
[webhook] 2017/10/23 18:17:07 loaded: awx-atest
[webhook] 2017/10/23 18:17:07 serving hooks on http://0.0.0.0:9000/hooks/{id}
[webhook] 2017/10/23 18:17:09 incoming HTTP request from [::1]:54005
[webhook] 2017/10/23 18:17:09 awx-atest got matched
[webhook] 2017/10/23 18:17:09 awx-atest hook triggered successfully
[webhook] 2017/10/23 18:17:09 200 | 388.746µs | localhost:9000 | POST /hooks/awx-atest
[webhook] 2017/10/23 18:17:09 executing /Users/jpm/bin/awx-hook.sh with arguments ["/Users/jpm/bin/awx-hook.sh" "jpm/atest" "none-of-your-business"] and environment [] using /tmp/ as cwd
[webhook] 2017/10/23 18:17:10 command output: {"job":331,"ignored_fields":{},...
[webhook] 2017/10/23 18:17:10 finished handling awx-atestThe truncated output in the second to last line is the JSON returned from the AWX job launch which happens in the awx-hook.sh script:
#!/bin/sh
mysecret="none-of-your-business"
repo="$1"
secret="$2"
if [ "$secret" == "none-of-your-business" ]; then
curl -qs \
-d '{"extra_vars":{"newpoem":"hello good world"}}' \
-H "Content-type: application/json" \
-u admin:password \
"http://192.168.1.210/api/v2/job_templates/${repo}/launch/"
fiAll this is obviously just an example. Refine to your taste (and add lots of error-handling!)
From AWX
Whilst on the topic of Webhooks: AWX can trigger an arbitrary Webhook as a notification; these are invoked on success or on failure (as desired), and produce a payload which looks like this:
{
"created_by": "admin",
"credential": "jp-ed25519",
"extra_vars": "{}",
"finished": "2017-10-24T06:05:09.626734+00:00",
"friendly_name": "Job",
"hosts": {
"alice": {
"changed": 0,
"dark": 0,
"failed": false,
"failures": 0,
"ok": 2,
"processed": 1,
"skipped": 0
}
},
"id": 335,
"inventory": "j1",
"limit": "",
"name": "pi1",
"playbook": "ping.yml",
"project": "p1",
"started": "2017-10-24T06:04:54.127124+00:00",
"status": "successful",
"traceback": "",
"url": "https://towerhost/#/jobs/335"
}The next step is to take bits of the payload to indicate success or failure on your monitoring blinkenlights.