mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
c9ff01ffc7
* Wording based on suggestions by @thaJeztah, @moxiegirl in PR #14700. Signed-off-by: Charles Chan <charleswhchan@users.noreply.github.com>
465 lines
19 KiB
Markdown
465 lines
19 KiB
Markdown
<!--[metadata]>
|
|
+++
|
|
title = "Automated Builds on Docker Hub"
|
|
description = "Docker Hub Automated Builds"
|
|
keywords = ["Docker, docker, registry, accounts, plans, Dockerfile, Docker Hub, docs, documentation, trusted, builds, trusted builds, automated builds"]
|
|
[menu.main]
|
|
parent = "smn_pubhub"
|
|
weight = 3
|
|
+++
|
|
<![end-metadata]-->
|
|
|
|
# Automated Builds on Docker Hub
|
|
|
|
## About Automated Builds
|
|
|
|
*Automated Builds* are a special feature of Docker Hub which allow you to
|
|
use [Docker Hub's](https://hub.docker.com) build clusters to automatically
|
|
create images from a GitHub or Bitbucket repository containing a `Dockerfile`
|
|
The system will clone your repository and build the image described by the
|
|
`Dockerfile` using the directory the `Dockerfile` is in (and subdirectories)
|
|
as the build context. The resulting automated image will then be uploaded
|
|
to the Docker Hub registry and marked as an *Automated Build*.
|
|
|
|
Automated Builds have several advantages:
|
|
|
|
* Users of *your* Automated Build can trust that the resulting
|
|
image was built exactly as specified.
|
|
* The `Dockerfile` will be available to anyone with access to
|
|
your repository on the Docker Hub registry.
|
|
* Because the process is automated, Automated Builds help to
|
|
make sure that your repository is always up to date.
|
|
* Not having to push local Docker images to Docker Hub saves
|
|
you both network bandwidth and time.
|
|
|
|
Automated Builds are supported for both public and private repositories
|
|
on both [GitHub](http://github.com) and [Bitbucket](https://bitbucket.org/).
|
|
|
|
To use Automated Builds, you must have an [account on Docker Hub](
|
|
https://docs.docker.com/userguide/dockerhub/#creating-a-docker-hub-account)
|
|
and on GitHub and/or Bitbucket. In either case, the account needs
|
|
to be properly validated and activated before you can link to it.
|
|
|
|
The first time you to set up an Automated Build, your
|
|
[Docker Hub](https://hub.docker.com) account will need to be linked to
|
|
a GitHub or Bitbucket account.
|
|
This will allow the registry to see your repositories.
|
|
|
|
If you have previously linked your Docker Hub account, and want to view or modify
|
|
that link, click on the "Manage - Settings" link in the sidebar, and then
|
|
"Linked Accounts" in your Settings sidebar.
|
|
|
|
## Automated Builds from GitHub
|
|
|
|
If you've previously linked your Docker Hub account to your GitHub account,
|
|
you'll be able to skip to the [Creating an Automated Build](#creating-an-automated-build).
|
|
|
|
### Linking your Docker Hub account to a GitHub account
|
|
|
|
> *Note:*
|
|
> Automated Builds currently require *read* and *write* access since
|
|
> [Docker Hub](https://hub.docker.com) needs to setup a GitHub service
|
|
> hook. We have no choice here, this is how GitHub manages permissions, sorry!
|
|
> We do guarantee nothing else will be touched in your account.
|
|
|
|
To get started, log into your Docker Hub account and click the
|
|
"+ Add Repository" button at the upper right of the screen. Then select
|
|
[Automated Build](https://registry.hub.docker.com/builds/add/).
|
|
|
|
Select the [GitHub service](https://registry.hub.docker.com/associate/github/).
|
|
|
|
When linking to GitHub, you'll need to select either "Public and Private",
|
|
or "Limited" linking.
|
|
|
|
The "Public and Private" option is the easiest to use,
|
|
as it grants the Docker Hub full access to all of your repositories. GitHub
|
|
also allows you to grant access to repositories belonging to your GitHub
|
|
organizations.
|
|
|
|
By choosing the "Limited" linking, your Docker Hub account only gets permission
|
|
to access your public data and public repositories.
|
|
|
|
Follow the onscreen instructions to authorize and link your
|
|
GitHub account to Docker Hub. Once it is linked, you'll be able to
|
|
choose a source repository from which to create the Automatic Build.
|
|
|
|
You will be able to review and revoke Docker Hub's access by visiting the
|
|
[GitHub User's Applications settings](https://github.com/settings/applications).
|
|
|
|
> **Note**: If you delete the GitHub account linkage that is used for one of your
|
|
> automated build repositories, the previously built images will still be available.
|
|
> If you re-link to that GitHub account later, the automated build can be started
|
|
> using the "Start Build" button on the Hub, or if the webhook on the GitHub repository
|
|
> still exists, will be triggered by any subsequent commits.
|
|
|
|
### Auto builds and limited linked GitHub accounts.
|
|
|
|
If you selected to link your GitHub account with only a "Limited" link, then
|
|
after creating your automated build, you will need to either manually trigger a
|
|
Docker Hub build using the "Start a Build" button, or add the GitHub webhook
|
|
manually, as described in [GitHub Service Hooks](#github-service-hooks).
|
|
|
|
### Changing the GitHub user link
|
|
|
|
If you want to remove, or change the level of linking between your GitHub account
|
|
and the Docker Hub, you need to do this in two places.
|
|
|
|
First, remove the "Linked Account" from your Docker Hub "Settings".
|
|
Then go to your GitHub account's Personal settings, and in the "Applications"
|
|
section, "Revoke access".
|
|
|
|
You can now re-link your account at any time.
|
|
|
|
### GitHub organizations
|
|
|
|
GitHub organizations and private repositories forked from organizations will be
|
|
made available to auto build using the "Docker Hub Registry" application, which
|
|
needs to be added to the organization - and then will apply to all users.
|
|
|
|
To check, or request access, go to your GitHub user's "Setting" page, select the
|
|
"Applications" section from the left side bar, then click the "View" button for
|
|
"Docker Hub Registry".
|
|
|
|
|
|
|
|
The organization's administrators may need to go to the Organization's "Third
|
|
party access" screen in "Settings" to Grant or Deny access to the Docker Hub
|
|
Registry application. This change will apply to all organization members.
|
|
|
|
|
|
|
|
More detailed access controls to specific users and GitHub repositories would be
|
|
managed using the GitHub People and Teams interfaces.
|
|
|
|
### Creating an Automated Build
|
|
|
|
You can [create an Automated Build](
|
|
https://registry.hub.docker.com/builds/github/select/) from any of your
|
|
public or private GitHub repositories that have a `Dockerfile`.
|
|
|
|
Once you've selected the source repository, you can then configure:
|
|
|
|
- The Hub user/org the repository is built to - either your Hub account name,
|
|
or the name of any Hub organizations your account is in
|
|
- The Docker repository name the image is built to
|
|
- If the Docker repository should be "Public" or "Private"
|
|
You can change the accessibility options after the repository has been created.
|
|
If you add a Private repository to a Hub user, then you can only add other users
|
|
as collaborators, and those users will be able to view and pull all images in that
|
|
repository. To configure more granular access permissions, such as using groups of
|
|
users or allow different users access to different image tags, then you need
|
|
to add the Private repository to a Hub organization that your user has Administrator
|
|
privilege on.
|
|
- If you want the GitHub to notify the Docker Hub when a commit is made, and thus trigger
|
|
a rebuild of all the images in this automated build.
|
|
|
|
You can also select one or more
|
|
- The git branch/tag, which repository sub-directory to use as the context
|
|
- The Docker image tag name
|
|
|
|
You can set a description for the repository by clicking "Description" link in the righthand side bar after the automated build - note that the "Full Description" will be over-written next build from the README.md file.
|
|
has been created.
|
|
|
|
### GitHub private submodules
|
|
|
|
If your GitHub repository contains links to private submodules, you'll get an
|
|
error message in your build.
|
|
|
|
Normally, the Docker Hub sets up a deploy key in your GitHub repository.
|
|
Unfortunately, GitHub only allows a repository deploy key to access a single repository.
|
|
|
|
To work around this, you need to create a dedicated user account in GitHub and attach
|
|
the automated build's deploy key that account. This dedicated build account
|
|
can be limited to read-only access to just the repositories required to build.
|
|
|
|
<table class="table table-bordered">
|
|
<thead>
|
|
<tr>
|
|
<th>Step</th>
|
|
<th>Screenshot</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>1.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_org_members.png"></td>
|
|
<td>First, create the new account in GitHub. It should be given read-only
|
|
access to the main repository and all submodules that are needed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>2.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_team_members.png"></td>
|
|
<td>This can be accomplished by adding the account to a read-only team in
|
|
the organization(s) where the main GitHub repository and all submodule
|
|
repositories are kept.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>3.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_repo_deploy_key.png"></td>
|
|
<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>
|
|
</tr>
|
|
<tr>
|
|
<td>4.</td>
|
|
<td><img src="/docker-hub/hub-images/deploy_key.png"></td>
|
|
<td>Your automated build's deploy key is in the "Build Details" menu
|
|
under "Deploy keys".</td>
|
|
</tr>
|
|
<tr>
|
|
<td>5.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_add_ssh_user_key.png"></td>
|
|
<td>In your dedicated GitHub User account, add the deploy key from your
|
|
Docker Hub Automated Build.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
### GitHub service hooks
|
|
|
|
The GitHub Service hook allows GitHub to notify the Docker Hub when something has
|
|
been committed to that git repository. You will need to add the Service Hook manually
|
|
if your GitHub account is "Limited" linked to the Docker Hub.
|
|
|
|
Follow the steps below to configure the GitHub Service hooks for your Automated Build:
|
|
|
|
<table class="table table-bordered">
|
|
<thead>
|
|
<tr>
|
|
<th>Step</th>
|
|
<th>Screenshot</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>1.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_settings.png"></td>
|
|
<td>Log in to GitHub.com, and go to your Repository page. Click on "Settings" on
|
|
the right side of the page. You must have admin privileges to the repository in order to do this.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>2.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_menu.png" alt="Webhooks & Services"></td>
|
|
<td>Click on "Webhooks & Services" on the left side of the page.</td></tr>
|
|
<tr><td>3.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_service_hook.png" alt="Find the service labeled Docker"></td>
|
|
<td>Find the service labeled "Docker" (or click on "Add service") and click on it.</td></tr>
|
|
<tr><td>4.</td>
|
|
<td><img src="/docker-hub/hub-images/gh_docker-service.png" alt="Activate Service Hooks"></td>
|
|
<td>Make sure the "Active" checkbox is selected and click the "Update service" button to save your changes.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
## Automated Builds with Bitbucket
|
|
|
|
In order to setup an Automated Build, you need to first link your
|
|
[Docker Hub](https://hub.docker.com) account with a Bitbucket account.
|
|
This will allow the registry to see your repositories.
|
|
|
|
To get started, log into your Docker Hub account and click the
|
|
"+ Add Repository" button at the upper right of the screen. Then
|
|
select [Automated Build](https://registry.hub.docker.com/builds/add/).
|
|
|
|
Select the [Bitbucket source](
|
|
https://registry.hub.docker.com/associate/bitbucket/).
|
|
|
|
Then follow the onscreen instructions to authorize and link your
|
|
Bitbucket account to Docker Hub. Once it is linked, you'll be able
|
|
to choose a repository from which to create the Automatic Build.
|
|
|
|
### Creating an Automated Build
|
|
|
|
You can [create an Automated Build](
|
|
https://registry.hub.docker.com/builds/bitbucket/select/) from any of your
|
|
public or private Bitbucket repositories with a `Dockerfile`.
|
|
|
|
### Adding a Hook
|
|
|
|
When you link your Docker Hub account, a `POST` hook should get automatically
|
|
added to your Bitbucket repository. Follow the steps below to confirm or modify the
|
|
Bitbucket hooks for your Automated Build:
|
|
|
|
<table class="table table-bordered">
|
|
<thead>
|
|
<tr>
|
|
<th>Step</th>
|
|
<th>Screenshot</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>1.</td>
|
|
<td><img src="/docker-hub/hub-images/bb_menu.png" alt="Settings" width="180"></td>
|
|
<td>Log in to Bitbucket.org and go to your Repository page. Click on "Settings" on
|
|
the far left side of the page, under "Navigation". You must have admin privileges
|
|
to the repository in order to do this.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>2.</td>
|
|
<td><img src="/docker-hub/hub-images/bb_hooks.png" alt="Hooks" width="180"></td>
|
|
<td>Click on "Hooks" on the near left side of the page, under "Settings".</td></tr>
|
|
<tr>
|
|
<td>3.</td>
|
|
<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
|
|
registry.hub.docker.com/hooks/bitbucket.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
## The Dockerfile and Automated Builds
|
|
|
|
During the build process, Docker will copy the contents of your `Dockerfile`.
|
|
It will also add it to the [Docker Hub](https://hub.docker.com) for the Docker
|
|
community (for public repositories) or approved team members/orgs (for private
|
|
repositories) to see on the repository page.
|
|
|
|
### README.md
|
|
|
|
If you have a `README.md` file in your repository, it will be used as the
|
|
repository's full description.The build process will look for a
|
|
`README.md` in the same directory as your `Dockerfile`.
|
|
|
|
> **Warning:**
|
|
> If you change the full description after a build, it will be
|
|
> rewritten the next time the Automated Build has been built. To make changes,
|
|
> modify the `README.md` from the Git repository.
|
|
|
|
## 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
|
|
Automated Build, it will give you a URL to which you can send POST requests.
|
|
This will trigger the Automated Build, much as with a GitHub webhook.
|
|
|
|
Build triggers are available under the Settings menu of each Automated Build
|
|
repository on the Docker Hub.
|
|
|
|
|
|
|
|
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
|
|
> recently submitted a build request, those requests *will be ignored*.
|
|
> To verify everything is working correctly, check the logs of last
|
|
> ten triggers on the settings page .
|
|
|
|
## Webhooks
|
|
|
|
Automated Builds also include a Webhooks feature. Webhooks can be called
|
|
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:
|
|
|
|
```
|
|
{
|
|
"callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/",
|
|
"push_data": {
|
|
"images": [
|
|
"27d47432a69bca5f2700e4dff7de0388ed65f9d3fb1ec645e2bc24c223dc1cc3",
|
|
"51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c",
|
|
...
|
|
],
|
|
"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 Repository.
|
|
Use a tool like [requestb.in](http://requestb.in/) to test your webhook.
|
|
|
|
> **Note**: The Docker Hub servers use an elastic IP range, so you can't
|
|
> filter requests by IP.
|
|
|
|
### Webhook chains
|
|
|
|
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
|
|
for the other Automated Build. This makes it easy to keep all your
|
|
Automated Builds up to date.
|
|
|
|
To add a link, go to the repository for the Automated Build you want to
|
|
link to and click on *Repository Links* under the Settings menu at
|
|
right. Then, enter the name of the repository that you want have linked.
|
|
|
|
> **Warning:**
|
|
> You can add more than one repository link, however, you should
|
|
> do so very carefully. Creating a two way relationship between Automated Builds will
|
|
> cause an endless build loop.
|