github.com/brianfoshee/docker@v1.6.0/docs/sources/docker-hub/builds.md (about) 1 page_title: Automated Builds on Docker Hub 2 page_description: Docker Hub Automated Builds 3 page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, documentation, trusted, builds, trusted builds, automated builds 4 5 # Automated Builds on Docker Hub 6 7 ## About Automated Builds 8 9 *Automated Builds* are a special feature of Docker Hub which allow you to 10 use [Docker Hub's](https://hub.docker.com) build clusters to automatically 11 create images from a specified `Dockerfile` and a GitHub or Bitbucket repository 12 (or "context"). The system will clone your repository and build the image 13 described by the `Dockerfile` using the repository as the context. The 14 resulting automated image will then be uploaded to the Docker Hub registry 15 and marked as an *Automated Build*. 16 17 Automated Builds have several advantages: 18 19 * Users of *your* Automated Build can trust that the resulting 20 image was built exactly as specified. 21 22 * The `Dockerfile` will be available to anyone with access to 23 your repository on the Docker Hub registry. 24 25 * Because the process is automated, Automated Builds help to 26 make sure that your repository is always up to date. 27 28 Automated Builds are supported for both public and private repositories 29 on both [GitHub](http://github.com) and [Bitbucket](https://bitbucket.org/). 30 31 To use Automated Builds, you must have an [account on Docker Hub]( 32 http://docs.docker.com/userguide/dockerhub/#creating-a-docker-hub-account) 33 and on GitHub and/or Bitbucket. In either case, the account needs 34 to be properly validated and activated before you can link to it. 35 36 ## Setting up Automated Builds with GitHub 37 38 In order to set up an Automated Build, you need to first link your 39 [Docker Hub](https://hub.docker.com) account with a GitHub account. 40 This will allow the registry to see your repositories. 41 42 > *Note:* 43 > Automated Builds currently require *read* and *write* access since 44 > [Docker Hub](https://hub.docker.com) needs to setup a GitHub service 45 > hook. We have no choice here, this is how GitHub manages permissions, sorry! 46 > We do guarantee nothing else will be touched in your account. 47 48 To get started, log into your Docker Hub account and click the 49 "+ Add Repository" button at the upper right of the screen. Then select 50 [Automated Build](https://registry.hub.docker.com/builds/add/). 51 52 Select the [GitHub service](https://registry.hub.docker.com/associate/github/). 53 54 Then follow the onscreen instructions to authorize and link your 55 GitHub account to Docker Hub. Once it is linked, you'll be able to 56 choose a repo from which to create the Automatic Build. 57 58 ### Creating an Automated Build 59 60 You can [create an Automated Build]( 61 https://registry.hub.docker.com/builds/github/select/) from any of your 62 public or private GitHub repositories with a `Dockerfile`. 63 64 ### GitHub Submodules 65 66 If your GitHub repository contains links to private submodules, you'll get an 67 error message in your build. 68 69 Normally, the Docker Hub sets up a deploy key in your GitHub repository. 70 Unfortunately, GitHub only allows a repository deploy key to access a single repository. 71 72 To work around this, you need to create a dedicated user account in GitHub and attach 73 the automated build's deploy key that account. This dedicated build account 74 can be limited to read-only access to just the repositories required to build. 75 76 <table class="table table-bordered"> 77 <thead> 78 <tr> 79 <th>Step</th> 80 <th>Screenshot</th> 81 <th>Description</th> 82 </tr> 83 </thead> 84 <tbody> 85 <tr> 86 <td>1.</td> 87 <td><img src="/docker-hub/hub-images/gh_org_members.png"></td> 88 <td>First, create the new account in GitHub. It should be given read-only 89 access to the main repository and all submodules that are needed.</td> 90 </tr> 91 <tr> 92 <td>2.</td> 93 <td><img src="/docker-hub/hub-images/gh_team_members.png"></td> 94 <td>This can be accomplished by adding the account to a read-only team in 95 the organization(s) where the main GitHub repository and all submodule 96 repositories are kept.</td> 97 </tr> 98 <tr> 99 <td>3.</td> 100 <td><img src="/docker-hub/hub-images/gh_repo_deploy_key.png"></td> 101 <td>Next, remove the deploy key from the main GitHub repository. This can be done in the GitHub repository's "Deploy keys" Settings section.</td> 102 </tr> 103 <tr> 104 <td>4.</td> 105 <td><img src="/docker-hub/hub-images/deploy_key.png"></td> 106 <td>Your automated build's deploy key is in the "Build Details" menu 107 under "Deploy keys".</td> 108 </tr> 109 <tr> 110 <td>5.</td> 111 <td><img src="/docker-hub/hub-images/gh_add_ssh_user_key.png"></td> 112 <td>In your dedicated GitHub User account, add the deploy key from your 113 Docker Hub Automated Build.</td> 114 </tr> 115 </tbody> 116 </table> 117 118 ### GitHub Organizations 119 120 GitHub organizations will appear once your membership to that organization is 121 made public on GitHub. To verify, you can look at the members tab for your 122 organization on GitHub. 123 124 ### GitHub Service Hooks 125 126 Follow the steps below to configure the GitHub service 127 hooks for your Automated Build: 128 129 <table class="table table-bordered"> 130 <thead> 131 <tr> 132 <th>Step</th> 133 <th>Screenshot</th> 134 <th>Description</th> 135 </tr> 136 </thead> 137 <tbody> 138 <tr> 139 <td>1.</td> 140 <td><img src="/docker-hub/hub-images/gh_settings.png"></td> 141 <td>Log in to Github.com, and go to your Repository page. Click on "Settings" on 142 the right side of the page. You must have admin privileges to the repository in order to do this.</td> 143 </tr> 144 <tr> 145 <td>2.</td> 146 <td><img src="/docker-hub/hub-images/gh_menu.png" alt="Webhooks & Services"></td> 147 <td>Click on "Webhooks & Services" on the left side of the page.</td></tr> 148 <tr><td>3.</td> 149 <td><img src="/docker-hub/hub-images/gh_service_hook.png" alt="Find the service labeled Docker"></td><td>Find the service labeled "Docker" and click on it.</td></tr> 150 <tr><td>4.</td><td><img src="/docker-hub/hub-images/gh_docker-service.png" alt="Activate Service Hooks"></td> 151 <td>Make sure the "Active" checkbox is selected and click the "Update service" button to save your changes.</td> 152 </tr> 153 </tbody> 154 </table> 155 156 ## Setting up Automated Builds with Bitbucket 157 158 In order to setup an Automated Build, you need to first link your 159 [Docker Hub](https://hub.docker.com) account with a Bitbucket account. 160 This will allow the registry to see your repositories. 161 162 To get started, log into your Docker Hub account and click the 163 "+ Add Repository" button at the upper right of the screen. Then 164 select [Automated Build](https://registry.hub.docker.com/builds/add/). 165 166 Select the [Bitbucket source]( 167 https://registry.hub.docker.com/associate/bitbucket/). 168 169 Then follow the onscreen instructions to authorize and link your 170 Bitbucket account to Docker Hub. Once it is linked, you'll be able 171 to choose a repository from which to create the Automatic Build. 172 173 ### Creating an Automated Build 174 175 You can [create an Automated Build]( 176 https://registry.hub.docker.com/builds/bitbucket/select/) from any of your 177 public or private Bitbucket repositories with a `Dockerfile`. 178 179 ### Adding a Hook 180 181 When you link your Docker Hub account, a `POST` hook should get automatically 182 added to your Bitbucket repository. Follow the steps below to confirm or modify the 183 Bitbucket hooks for your Automated Build: 184 185 <table class="table table-bordered"> 186 <thead> 187 <tr> 188 <th>Step</th> 189 <th>Screenshot</th> 190 <th>Description</th> 191 </tr> 192 </thead> 193 <tbody> 194 <tr> 195 <td>1.</td> 196 <td><img src="/docker-hub/hub-images/bb_menu.png" alt="Settings" width="180"></td> 197 <td>Log in to Bitbucket.org and go to your Repository page. Click on "Settings" on 198 the far left side of the page, under "Navigation". You must have admin privileges 199 to the repository in order to do this.</td> 200 </tr> 201 <tr> 202 <td>2.</td> 203 <td><img src="/docker-hub/hub-images/bb_hooks.png" alt="Hooks" width="180"></td> 204 <td>Click on "Hooks" on the near left side of the page, under "Settings".</td></tr> 205 <tr> 206 <td>3.</td> 207 <td><img src="/docker-hub/hub-images/bb_post-hook.png" alt="Docker Post Hook"></td><td>You should now see a list of hooks associated with the repo, including a <code>POST</code> hook that points at 208 registry.hub.docker.com/hooks/bitbucket.</td> 209 </tr> 210 </tbody> 211 </table> 212 213 214 ## The Dockerfile and Automated Builds 215 216 During the build process, Docker will copy the contents of your `Dockerfile`. 217 It will also add it to the [Docker Hub](https://hub.docker.com) for the Docker 218 community (for public repositories) or approved team members/orgs (for private 219 repositories) to see on the repository page. 220 221 ### README.md 222 223 If you have a `README.md` file in your repository, it will be used as the 224 repository's full description.The build process will look for a 225 `README.md` in the same directory as your `Dockerfile`. 226 227 > **Warning:** 228 > If you change the full description after a build, it will be 229 > rewritten the next time the Automated Build has been built. To make changes, 230 > modify the `README.md` from the Git repository. 231 232 ## Remote Build triggers 233 234 If you need a way to trigger Automated Builds outside of GitHub or Bitbucket, 235 you can set up a build trigger. When you turn on the build trigger for an 236 Automated Build, it will give you a URL to which you can send POST requests. 237 This will trigger the Automated Build, much as with a GitHub webhook. 238 239 Build triggers are available under the Settings menu of each Automated Build 240 repository on the Docker Hub. 241 242 ![Build trigger screen](/docker-hub/hub-images/build-trigger.png) 243 244 You can use `curl` to trigger a build: 245 246 ``` 247 $ curl --data "build=true" -X POST https://registry.hub.docker.com/u/svendowideit/testhook/trigger/be579c 248 82-7c0e-11e4-81c4-0242ac110020/ 249 OK 250 ``` 251 252 > **Note:** 253 > You can only trigger one build at a time and no more than one 254 > every five minutes. If you already have a build pending, or if you 255 > recently submitted a build request, those requests *will be ignored*. 256 > To verify everything is working correctly, check the logs of last 257 > ten triggers on the settings page . 258 259 ## Webhooks 260 261 Automated Builds also include a Webhooks feature. Webhooks can be called 262 after a successful repository push is made. This includes when a new tag is added 263 to an existing image. 264 265 The webhook call will generate a HTTP POST with the following JSON 266 payload: 267 268 ``` 269 { 270 "callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/", 271 "push_data": { 272 "images": [ 273 "27d47432a69bca5f2700e4dff7de0388ed65f9d3fb1ec645e2bc24c223dc1cc3", 274 "51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c", 275 ... 276 ], 277 "pushed_at": 1.417566161e+09, 278 "pusher": "trustedbuilder" 279 }, 280 "repository": { 281 "comment_count": 0, 282 "date_created": 1.417494799e+09, 283 "description": "", 284 "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", 285 "full_description": "Docker Hub based automated build from a GitHub repo", 286 "is_official": false, 287 "is_private": true, 288 "is_trusted": true, 289 "name": "testhook", 290 "namespace": "svendowideit", 291 "owner": "svendowideit", 292 "repo_name": "svendowideit/testhook", 293 "repo_url": "https://registry.hub.docker.com/u/svendowideit/testhook/", 294 "star_count": 0, 295 "status": "Active" 296 } 297 } 298 ``` 299 300 Webhooks are available under the Settings menu of each Repository. 301 302 > **Note:** If you want to test your webhook out we recommend using 303 > a tool like [requestb.in](http://requestb.in/). 304 305 > **Note**: The Docker Hub servers are currently in the IP range 306 > `162.242.195.64 - 162.242.195.127`, so you can restrict your webhooks to 307 > accept webhook requests from that set of IP addresses. 308 309 ### Webhook chains 310 311 Webhook chains allow you to chain calls to multiple services. For example, 312 you can use this to trigger a deployment of your container only after 313 it has been successfully tested, then update a separate Changelog once the 314 deployment is complete. 315 After clicking the "Add webhook" button, simply add as many URLs as necessary 316 in your chain. 317 318 The first webhook in a chain will be called after a successful push. Subsequent 319 URLs will be contacted after the callback has been validated. 320 321 ### Validating a callback 322 323 In order to validate a callback in a webhook chain, you need to 324 325 1. Retrieve the `callback_url` value in the request's JSON payload. 326 1. Send a POST request to this URL containing a valid JSON body. 327 328 > **Note**: A chain request will only be considered complete once the last 329 > callback has been validated. 330 331 To help you debug or simply view the results of your webhook(s), 332 view the "History" of the webhook available on its settings page. 333 334 ### Callback JSON data 335 336 The following parameters are recognized in callback data: 337 338 * `state` (required): Accepted values are `success`, `failure` and `error`. 339 If the state isn't `success`, the webhook chain will be interrupted. 340 * `description`: A string containing miscellaneous information that will be 341 available on the Docker Hub. Maximum 255 characters. 342 * `context`: A string containing the context of the operation. Can be retrieved 343 from the Docker Hub. Maximum 100 characters. 344 * `target_url`: The URL where the results of the operation can be found. Can be 345 retrieved on the Docker Hub. 346 347 *Example callback payload:* 348 349 { 350 "state": "success", 351 "description": "387 tests PASSED", 352 "context": "Continuous integration by Acme CI", 353 "target_url": "http://ci.acme.com/results/afd339c1c3d27" 354 } 355 356 ## Repository links 357 358 Repository links are a way to associate one Automated Build with 359 another. If one gets updated,the linking system triggers a rebuild 360 for the other Automated Build. This makes it easy to keep all your 361 Automated Builds up to date. 362 363 To add a link, go to the repository for the Automated Build you want to 364 link to and click on *Repository Links* under the Settings menu at 365 right. Then, enter the name of the repository that you want have linked. 366 367 > **Warning:** 368 > You can add more than one repository link, however, you should 369 > do so very carefully. Creating a two way relationship between Automated Builds will 370 > cause an endless build loop.