diff --git a/docs/sources/docker-io/builds.md b/docs/sources/docker-io/builds.md index 0ca058663a..1f6e002208 100644 --- a/docs/sources/docker-io/builds.md +++ b/docs/sources/docker-io/builds.md @@ -7,20 +7,25 @@ page_keywords: Docker, docker, registry, accounts, plans, Dockerfile, Docker.io, ## Trusted Builds *Trusted Builds* is a special feature allowing you to specify a source -repository with a *Dockerfile* to be built by the Docker build clusters. The -system will clone your repository and build the Dockerfile using the repository -as the context. The resulting image will then be uploaded to the registry and -marked as a `Trusted Build`. +repository with a `Dockerfile` to be built by the +[Docker.io](https://index.docker.io) build clusters. The system will +clone your repository and build the `Dockerfile` using the repository as +the context. The resulting image will then be uploaded to the registry +and marked as a *Trusted Build*. Trusted Builds have a number of advantages. For example, users of *your* Trusted Build can be certain that the resulting image was built exactly how it claims to be. -Furthermore, the Dockerfile will be available to anyone browsing your repository +Furthermore, the `Dockerfile` will be available to anyone browsing your repository on the registry. Another advantage of the Trusted Builds feature is the automated builds. This makes sure that your repository is always up to date. -### Linking with a GitHub account +Trusted builds are supported for both public and private repositories on +both [GitHub](http://github.com) and +[BitBucket](https://bitbucket.org/). + +### Setting up Trusted Builds with GitHub In order to setup a Trusted Build, you need to first link your [Docker.io]( https://index.docker.io) account with a GitHub one. This will allow the registry @@ -30,23 +35,28 @@ to see your repositories. > https://index.docker.io) needs to setup a GitHub service hook. Although nothing > else is done with your account, this is how GitHub manages permissions, sorry! -### Creating a Trusted Build +Click on the [Trusted Builds tab](https://index.docker.io/builds/) to +get started and then select [+ Add +New](https://index.docker.io/builds/add/). + +Select the [GitHub +service](https://index.docker.io/associate/github/). + +Then follow the instructions to authorize and link your GitHub account +to Docker.io. + +#### Creating a Trusted Build You can [create a Trusted Build](https://index.docker.io/builds/github/select/) -from any of your public GitHub repositories with a Dockerfile. +from any of your public or private GitHub repositories with a `Dockerfile`. -> **Note:** We currently only support public repositories. To have more than -> one Docker image from the same GitHub repository, you will need to set up one -> Trusted Build per Dockerfile, each using a different image name. This rule -> applies to building multiple branches on the same GitHub repository as well. - -### GitHub organizations +#### GitHub organizations GitHub organizations appear once your membership to that organization is made public on GitHub. To verify, you can look at the members tab for your organization on GitHub. -### GitHub service hooks +#### GitHub service hooks You can follow the below steps to configure the GitHub service hooks for your Trusted Build: @@ -74,9 +84,32 @@ Trusted Build: +### Setting up Trusted Builds with BitBucket + +In order to setup a Trusted Build, you need to first link your +[Docker.io]( https://index.docker.io) account with a BitBucket one. This +will allow the registry to see your repositories. + +Click on the [Trusted Builds tab](https://index.docker.io/builds/) to +get started and then select [+ Add +New](https://index.docker.io/builds/add/). + +Select the [BitBucket +service](https://index.docker.io/associate/bitbucket/). + +Then follow the instructions to authorize and link your BitBucket account +to Docker.io. + +#### Creating a Trusted Build + +You can [create a Trusted +Build](https://index.docker.io/builds/bitbucket/select/) +from any of your public or private BitBucket repositories with a +`Dockerfile`. + ### The Dockerfile and Trusted Builds -During the build process, we copy the contents of your Dockerfile. We also +During the build process, we copy the contents of your `Dockerfile`. We also add it to the [Docker.io](https://index.docker.io) for the Docker community to see on the repository page. @@ -89,14 +122,18 @@ repository's full description. > If you change the full description after a build, it will be > rewritten the next time the Trusted Build has been built. To make changes, > modify the README.md from the Git repository. We will look for a README.md -> in the same directory as your Dockerfile. +> in the same directory as your `Dockerfile`. ### Build triggers -If you need another way to trigger your Trusted Builds outside of GitHub, you -can setup a build trigger. When you turn on the build trigger for a Trusted -Build, it will give you a URL to which you can send POST requests. This will -trigger the Trusted Build process, which is similar to GitHub webhooks. +If you need another way to trigger your Trusted Builds outside of GitHub +or BitBucket, you can setup a build trigger. When you turn on the build +trigger for a Trusted Build, it will give you a URL to which you can +send POST requests. This will trigger the Trusted Build process, which +is similar to GitHub web hooks. + +Build Triggers are available under the Settings tab of each Trusted +Build. > **Note:** > You can only trigger one build at a time and no more than one @@ -105,6 +142,52 @@ trigger the Trusted Build process, which is similar to GitHub webhooks. > You can find the logs of last 10 triggers on the settings page to verify > if everything is working correctly. +### Webhooks + +Also available for Trusted Builds are Webhooks. Webhooks can be called +after a successful repository push is made. + +The web hook 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_trusted":false, + "full_description":"This is my full description", + "repo_url":"https://index.docker.io/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" + } +} +``` + +Webhooks are available under the Settings tab of each Trusted +Build. + +> **Note:** If you want to test your webhook out then we recommend using +> a tool like [requestb.in](http://requestb.in/). + + ### Repository links Repository links are a way to associate one Trusted Build with another. If one diff --git a/docs/sources/use/workingwithrepository.md b/docs/sources/use/workingwithrepository.md index b78d9bdc0f..2b4ad613cc 100644 --- a/docs/sources/use/workingwithrepository.md +++ b/docs/sources/use/workingwithrepository.md @@ -146,17 +146,17 @@ or tag. ## Trusted Builds -Trusted Builds automate the building and updating of images from GitHub, -directly on Docker.io. It works by adding a commit hook to +Trusted Builds automate the building and updating of images from GitHub +or BitBucket, directly on Docker.io. It works by adding a commit hook to your selected repository, triggering a build and update when you push a commit. ### To setup a trusted build 1. Create a [Docker.io account](https://index.docker.io/) and login. -2. Link your GitHub account through the `Link Accounts` menu. +2. Link your GitHub or BitBucket account through the [`Link Accounts`](https://index.docker.io/account/accounts/) menu. 3. [Configure a Trusted build](https://index.docker.io/builds/). -4. Pick a GitHub project that has a `Dockerfile` that you want to build. +4. Pick a GitHub or BitBucket project that has a `Dockerfile` that you want to build. 5. Pick the branch you want to build (the default is the `master` branch). 6. Give the Trusted Build a name. 7. Assign an optional Docker tag to the Build. @@ -165,17 +165,17 @@ commit. Once the Trusted Build is configured it will automatically trigger a build, and in a few minutes, if there are no errors, you will see your new trusted build on the [Docker.io](https://index.docker.io) Registry. -It will will stay in sync with your GitHub repo until you deactivate the -Trusted Build. +It will stay in sync with your GitHub and BitBucket repository until you +deactivate the Trusted Build. If you want to see the status of your Trusted Builds you can go to your -[Trusted Builds page](https://index.docker.io/builds/) on the Docker -index, and it will show you the status of your builds, and the build -history. +[Trusted Builds page](https://index.docker.io/builds/) on the Docker.io, +and it will show you the status of your builds, and the build history. Once you've created a Trusted Build you can deactivate or delete it. You cannot however push to a Trusted Build with the `docker push` command. -You can only manage it by committing code to your GitHub repository. +You can only manage it by committing code to your GitHub or BitBucket +repository. You can create multiple Trusted Builds per repository and configure them to point to specific `Dockerfile`'s or Git branches.