diff --git a/components/engine/docs/sources/docker-hub/builds.md b/components/engine/docs/sources/docker-hub/builds.md index 7bf8b27eb2..5d73e4aae9 100644 --- a/components/engine/docs/sources/docker-hub/builds.md +++ b/components/engine/docs/sources/docker-hub/builds.md @@ -209,7 +209,7 @@ repository's full description.The build process will look for a > rewritten the next time the Automated Build has been built. To make changes, > modify the `README.md` from the Git repository. -### Build triggers +## Remote Build triggers If you need a way to trigger Automated Builds outside of GitHub or Bitbucket, you can set up a build trigger. When you turn on the build trigger for an @@ -219,6 +219,16 @@ This will trigger the Automated Build, much as with a GitHub webhook. Build triggers are available under the Settings menu of each Automated Build repo on the Docker Hub. +![Build trigger screen](/docker-hub/hub-images/build-trigger.png) + +You can use `curl` to trigger a build: + +``` +$ curl --data "build=true" -X POST https://registry.hub.docker.com/u/svendowideit/testhook/trigger/be579c +82-7c0e-11e4-81c4-0242ac110020/ +OK +``` + > **Note:** > You can only trigger one build at a time and no more than one > every five minutes. If you already have a build pending, or if you @@ -226,53 +236,96 @@ repo on the Docker Hub. > To verify everything is working correctly, check the logs of last > ten triggers on the settings page . -### Webhooks +## Webhooks Automated Builds also include a Webhooks feature. Webhooks can be called -after a successful repository push is made. +after a successful repository push is made. This includes when a new tag is added +to an existing image. The webhook call will generate a HTTP POST with the following JSON payload: ``` { - "push_data":{ - "pushed_at":1385141110, - "images":[ - "imagehash1", - "imagehash2", - "imagehash3" - ], - "pusher":"username" - }, - "repository":{ - "status":"Active", - "description":"my docker repo that does cool things", - "is_automated":false, - "full_description":"This is my full description", - "repo_url":"https://registry.hub.docker.com/u/username/reponame/", - "owner":"username", - "is_official":false, - "is_private":false, - "name":"reponame", - "namespace":"username", - "star_count":1, - "comment_count":1, - "date_created":1370174400, - "dockerfile":"my full dockerfile is listed here", - "repo_name":"username/reponame" - } + "callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/", + "push_data": { + "images": [], + "pushed_at": 1.417566161e+09, + "pusher": "trustedbuilder" + }, + "repository": { + "comment_count": 0, + "date_created": 1.417494799e+09, + "description": "", + "dockerfile": "#\n# BUILD\u0009\u0009docker build -t svendowideit/apt-cacher .\n# RUN\u0009\u0009docker run -d -p 3142:3142 -name apt-cacher-run apt-cacher\n#\n# and then you can run containers with:\n# \u0009\u0009docker run -t -i -rm -e http_proxy http://192.168.1.2:3142/ debian bash\n#\nFROM\u0009\u0009ubuntu\nMAINTAINER\u0009SvenDowideit@home.org.au\n\n\nVOLUME\u0009\u0009[\"/var/cache/apt-cacher-ng\"]\nRUN\u0009\u0009apt-get update ; apt-get install -yq apt-cacher-ng\n\nEXPOSE \u0009\u00093142\nCMD\u0009\u0009chmod 777 /var/cache/apt-cacher-ng ; /etc/init.d/apt-cacher-ng start ; tail -f /var/log/apt-cacher-ng/*\n", + "full_description": "Docker Hub based automated build from a GitHub repo", + "is_official": false, + "is_private": true, + "is_trusted": true, + "name": "testhook", + "namespace": "svendowideit", + "owner": "svendowideit", + "repo_name": "svendowideit/testhook", + "repo_url": "https://registry.hub.docker.com/u/svendowideit/testhook/", + "star_count": 0, + "status": "Active" + } } ``` -Webhooks are available under the Settings menu of each Automated -Build's repo. +Webhooks are available under the Settings menu of each Repository. > **Note:** If you want to test your webhook out we recommend using > a tool like [requestb.in](http://requestb.in/). +### Webhook chains -### Repository links +Webhook chains allow you to chain calls to multiple services. For example, +you can use this to trigger a deployment of your container only after +it has been successfully tested, then update a separate Changelog once the +deployment is complete. +After clicking the "Add webhook" button, simply add as many URLs as necessary +in your chain. + +The first webhook in a chain will be called after a successful push. Subsequent +URLs will be contacted after the callback has been validated. + +### Validating a callback + +In order to validate a callback in a webhook chain, you need to + +1. Retrieve the `callback_url` value in the request's JSON payload. +1. Send a POST request to this URL containing a valid JSON body. + +> **Note**: A chain request will only be considered complete once the last +> callback has been validated. + +To help you debug or simply view the results of your webhook(s), +view the "History" of the webhook available on its settings page. + +### Callback JSON data + +The following parameters are recognized in callback data: + +* `state` (required): Accepted values are `success`, `failure` and `error`. + If the state isn't `success`, the webhook chain will be interrupted. +* `description`: A string containing miscellaneous information that will be + available on the Docker Hub. Maximum 255 characters. +* `context`: A string containing the context of the operation. Can be retrieved + from the Docker Hub. Maximum 100 characters. +* `target_url`: The URL where the results of the operation can be found. Can be + retrieved on the Docker Hub. + +*Example callback payload:* + + { + "state": "success", + "description": "387 tests PASSED", + "context": "Continuous integration by Acme CI", + "target_url": "http://ci.acme.com/results/afd339c1c3d27" + } + +## Repository links Repository links are a way to associate one Automated Build with another. If one gets updated,the linking system triggers a rebuild diff --git a/components/engine/docs/sources/docker-hub/hub-images/build-trigger.png b/components/engine/docs/sources/docker-hub/hub-images/build-trigger.png new file mode 100644 index 0000000000..25597a27bd Binary files /dev/null and b/components/engine/docs/sources/docker-hub/hub-images/build-trigger.png differ diff --git a/components/engine/docs/sources/docker-hub/repos.md b/components/engine/docs/sources/docker-hub/repos.md index d0c2faea19..0749c0814c 100644 --- a/components/engine/docs/sources/docker-hub/repos.md +++ b/components/engine/docs/sources/docker-hub/repos.md @@ -110,34 +110,31 @@ similar to the example shown below. *Example webhook JSON payload:* - { - "push_data":{ - "pushed_at":1385141110, - "images":[ - "imagehash1", - "imagehash2", - "imagehash3" - ], - "pusher":"username" - }, - "repository":{ - "status":"Active", - "description":"my docker repo that does cool things", - "is_automated":false, - "full_description":"This is my full description", - "repo_url":"https://registry.hub.docker.com/u/username/reponame/", - "owner":"username", - "is_official":false, - "is_private":false, - "name":"reponame", - "namespace":"username", - "star_count":1, - "comment_count":1, - "date_created":1370174400, - "dockerfile":"my full dockerfile is listed here", - "repo_name":"username/reponame" - } - } +``` +{ + "callback_url": "https://registry.hub.docker.com/u/svendowideit/busybox/hook/2141bc0cdec4hebec411i4c1g40242eg110020/", + "push_data": { + "images": [], + "pushed_at": 1.417566822e+09, + "pusher": "svendowideit" + }, + "repository": { + "comment_count": 0, + "date_created": 1.417566665e+09, + "description": "", + "full_description": "webhook triggered from a 'docker push'", + "is_official": false, + "is_private": false, + "is_trusted": false, + "name": "busybox", + "namespace": "svendowideit", + "owner": "svendowideit", + "repo_name": "svendowideit/busybox", + "repo_url": "https://registry.hub.docker.com/u/svendowideit/busybox/", + "star_count": 0, + "status": "Active" +} +``` Webhooks allow you to notify people, services and other applications of new updates to your images and repositories. To get started adding webhooks, @@ -153,7 +150,8 @@ deployment is complete. After clicking the "Add webhook" button, simply add as many URLs as necessary in your chain. -The first webhook in a chain will be called after a successful push. Subsequent URLs will be contacted after the callback has been validated. +The first webhook in a chain will be called after a successful push. Subsequent +URLs will be contacted after the callback has been validated. #### Validating a callback @@ -172,10 +170,14 @@ view the "History" of the webhook available on its settings page. The following parameters are recognized in callback data: -* `state` (required): Accepted values are `success`, `failure` and `error`. If the state isn't `success`, the webhook chain will be interrupted. -* `description`: A string containing miscellaneous information that will be available on the Docker Hub. Maximum 255 characters. -* `context`: A string containing the context of the operation. Can be retrieved on the Docker Hub. Maximum 100 characters. -* `target_url`: The URL where the results of the operation can be found. Can be retrieved on the Docker Hub. +* `state` (required): Accepted values are `success`, `failure` and `error`. + If the state isn't `success`, the webhook chain will be interrupted. +* `description`: A string containing miscellaneous information that will be + available on the Docker Hub. Maximum 255 characters. +* `context`: A string containing the context of the operation. Can be retrieved + from the Docker Hub. Maximum 100 characters. +* `target_url`: The URL where the results of the operation can be found. Can be + retrieved on the Docker Hub. *Example callback payload:*