CloudBees Docker Hub/Registry Notification plugin

3 minute read

The CloudBees Docker Hub/Registry Notification plugin lets you configure Jenkins to trigger builds when an image is pushed to Docker Hub or Docker Registry. E.g. to run verification for the container.

Using

This plugin introduces a new trigger option to Jenkins jobs; Monitor Docker Hub for image changes.

On this trigger type, you can specify a list of one or more Docker Hub repositories from which to receive build trigger notifications following a push on any of the listed repositories. You can also select to receive notifications for any Docker Hub repository consumed by other parts of the job (default) e.g. the image referenced by a "Pull Docker image from Docker Hub" Build Step. Click the help link for the Any referenced Docker image can trigger this job option to see a list of all currently installed plugins that supports this.

Figure 1. Trigger section of a freestyle job configuration
Figure 1. Trigger section of a freestyle job configuration

Once a Jenkins job is configured to use a Docker Hub Notification Trigger, you then need to go to Docker Hub and configure a Webhook on the repository from which you would like your Jenkins build trigger to receive notification. After selecting the repository, select Webhooks in the Settings.

Figure 2. Adding a Webhook
Figure 2. Adding a Webhook

Then add the Webhook, using http://your-jenkins/dockerhub-webhook/notify as the webhook URL.

Figure 3. Docker Hub Webhook Configuration
Figure 3. Docker Hub Webhook Configuration

Note that automatic Webhook configuration will be supported by this plugin soon after the Docker Hub service supports Webhook configuration via their public API.

On receipt of a Webhook notification from Docker Hub, a build of the job is triggered. The build will receive two additional build parameters specific to the Docker Hub Trigger:

  • DOCKER_TRIGGER_REPO_NAME containing the name of the repo e.g. "acme/prod", and

  • DOCKER_TRIGGER_DOCKER_HUB_HOST containing the name of the docker host that that is to receive the callback e.g. "registry.hub.docker.com" (i.e. the same that is shown for the build cause).

Multiple jobs can be configured to receive a trigger from a single repository. In that case, the callback to Docker Hub will contain a link to a page in Jenkins listing the builds that were triggered and the callback state will be based on the worst build result.

Figure 4. Callback landing page
Figure 4. Callback landing page

Pull image build step

The plugin provides a simple freestyle build step called Pull Docker image from Docker Hub that simply performs a docker pull of an image from the registry with specified credentials. The build step is compatible with the trigger’s Any referenced Docker image can trigger this job option described above.

List views

You can create a list view that lists all jobs that are triggering on specified image names and displays what images they are triggering on. On the Jenkins top page; click on new View (the plus sign at the right of the view tabs). Specify a name for the new View, choose List View from the available view types and then press OK. Select Triggered by push to Docker Hub from the Add Job Filter selection dropdown.

Figure 5. Job filter in the list view configuration
Figure 5. Job filter in the list view configuration

It’s possible to narrow the list of images shown in the View by entering a Regular Expression in the Pattern text box (one pattern per line to match against a list of images). Leaving this field empty results in the listing of all jobs that have a Docker Hub Trigger configured.

You will have noticed that the top level Jenkins View contains a column named "DHT" (Docker Hub Trigger). This View column shows the name(s) of the Docker image(s) responsible for triggering the Jenkins Job listed in a given row of the View table. By default, this column is not show in the List View. To make it visible, simply select Docker Hub image names being triggered on from the Add column selection dropdown, located in the "Columns" section below the "Job Filters" section. You can manage the number of image names listed in this column (per row) by configuring the "Max" option for the column. Leave "Max" at 0 to list all images names. This option is useful when job triggering on many image names.

Figure 6. Column selection of the list view configuration
Figure 6. Column selection of the list view configuration