You can build your images automatically from a build context stored in a repository. A build context is a Dockerfile and any files at a specific location. For an automated build, the build context is a repository containing a Dockerfile.
Automated Builds have several advantages:
Dockerfileis available to anyone with access to your Docker Hub repository.
Automated Builds are supported for both public and private repositories on both GitHub and Bitbucket. This document guides you through the process of working with automated builds.
To use automated builds you must have an account on Docker Hub and on the hosted repository provider (GitHub or Bitbucket). If you have previously linked your Github or Bitbucket account, you must have chosen the Public and Private connection type.
To view your current connection settings, log in to Docker Hub and choose Profile > Settings > Linked Accounts & Services.
Currently Docker Hub does not support Git LFS (Large File Storage). If you have binaries in your build context that are managed by Git LFS, only the pointer file will be present in the clone made during the automated build, which is not what you want.
Subscribe to the GitHub issue tracking this limitation.
Log into Docker Hub.
Navigate to Profile > Settings > Linked Accounts & Services.
Click the service you want to link.
The system prompts you to choose between Public and Private and Limited Access. The Public and Private connection type is required if you want to use the Automated Builds.
Press Select under Public and Private connection type.
The system prompts you to enter your service credentials (Bitbucket or GitHub) to login. For example, Bitbucket’s prompt looks like this:
After you grant access to your code repository, the system returns you to Docker Hub and the link is complete.
Automated build repositories rely on the integration with your code repository
in order to build. However, you can also push already-built images to these
repositories using the
docker push command.
Select Create > Create Automated Build from Docker Hub.
The system prompts you with a list of User/Organizations and code repositories.
Select from the User/Organizations.
Optionally, type to filter the repository list.
Pick the project to build.
The system displays the Create Automated Build dialog.
The dialog assumes some defaults which you can customize. By default, Docker builds images for each branch in your repository. It assumes the Dockerfile lives at the root of your source. When it builds an image, Docker tags it with the branch name.
Customize the automated build by pressing the Click here to customize this behavior link.
Specify which code branches or tags to build from. You can add new configurations by clicking the + (plus sign). The dialog accepts regular expressions.
The system displays the home page for your AUTOMATED BUILD.
Within GitHub, a Docker integration appears in your repositories Settings > Webhooks & services page.
A similar page appears in Bitbucket if you use that code repository.Be careful to leave the Docker integration in place. Removing it causes your automated builds to stop.
The first time you create a new automated build, Docker Hub builds your image. In a few minutes, you should see your new build on the image dashboard. The Build Details page shows a log of your build systems:
During the build process, Docker copies the contents of your
Docker Hub. The Docker community (for public repositories) or approved team
members/orgs (for private repositories) can then view the Dockerfile on your
The build process looks for a
README.md in the same directory as your
Dockerfile. If you have a
README.md file in your repository, it is used in
the repository as the full description. If you change the full description after
a build, it’s overwritten the next time the Automated Build runs. To make
changes, modify the
README.md in your Git repository.
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 recently submitted a build request, Docker ignores new requests.
You can view the status of the builds for a specific repository by looking at the Build Details screen. If you have builds that are queued or in progress, you can click Cancel to end them.
The statuses are:
The Build Settings page allows you to manage your existing automated build configurations and add new ones. By default, when new code is merged into your source repository, it triggers a build of your DockerHub image.
Clear the checkbox to turn this behavior off. You can use the other settings on the page to configure and build images.
At the top of the Build Dialog is a list of configured builds. You can build from a code branch or by build tag.
Docker builds everything listed whenever a push is made to the code repository. If you specify a branch or tag, you can manually build that image by pressing the Trigger. If you use a regular expression syntax (regex) to define your build branch or tag, Docker does not give you the option to manually build. To add a new build:
Press the + (plus sign).
Choose the Type.
You can build by a code branch or by an image tag.
Enter the Name of the branch or tag.
You can enter a specific value or use a regex to select multiple values. To see examples of regex, press the Show More link on the right of the page.
Enter a Dockerfile location.
Specify a Tag Name.
Press Save Changes.
If you make a mistake or want to delete a build, press the - (minus sign) and then Save Changes.
Repository links let you link one Automated Build with another. If one Automated Build gets updated, Docker triggers a build of the other. This makes it easy to ensure that related images are kept in sync. You can link more than one image repository. You only need to link one side of two related builds. Linking both sides causes an endless build loop.
To add a link:
Go to the Build Settings for an automated build repository.
In the Repository Links section, enter an image repository name.
A remote repository name should be either an official repository name such as
ubuntu or a public repository name
To trigger Automated Builds programmatically, you can set up a remote build trigger in another application such as GitHub or Bitbucket. When you Activate the build trigger for an Automated Build, it supplies you with a Token and a URL.
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
To verify everything is working correctly, check the Last 10 Trigger Logs on the page.