Triggering a DockerHub Build Using Python

By | April 29, 2017

This article contain a small example program that triggers a Docker image build at DockerHub. I suspect I am late to the party as usual, but this is an improvement to a small utility program I created earlier that help me to trigger a build of a Docker image I have created based on code in a GitHub repository that I do not own.

Activate DockerHub Build Triggers

Before we can trigger builds on DockerHub, build triggers need to be activated for the DockerHub repository in question. In the example below, I will activate build triggers in my Elastalert Docker image repository.

  • Log in to DockerHub.
  • Go to the repository for which you want to be able to trigger builds over HTTP.
  • Click the Build Settings tab.

    Locate the Build Settings tab in the DockerHub repository.

  • Scroll down and locate the Build Triggers section.

    Build Triggers section in DockerHub repository with build triggers inactive.

  • Click the Activate Triggers button.
    You should now see  a trigger token and a trigger URL appear for the repository:

    Build triggers activated in DockerHub repository.

  • Copy the trigger token and store it for later use.
  • Click the Blue text saying “Show examples”.
    This should show you some examples how to trigger the build of one or more Docker images using curl.

Yes, I have regenerated my trigger token after taking the above screenshots.

Python Code to Trigger Docker Image Build

Having activated build triggers for the DockerHub repository I then wrote the following Python function to trigger the build of one specific tag, “latest” in the example below, of a Docker image.

import contextlib
import json
import urllib2

from datetime import datetime

DOCKERHUB_USER = "ivankrizsan"
DOCKERHUB_TRIGGER_TOKEN = "12345678-1234-1234-1234-123456789abc"

def trigger_dockerhub_tag_build(in_dockerhub_user, in_dockerhub_repository_name, in_dockerhub_trigger_token,
                                in_dockerhub_tagname, in_request_timeout):
    """Triggers the build of the Docker image with the suppplied tag name in the DockerHub repository with the supplied
    name owned by the DockerHub user with the supplied name using the supplied DockerHub trigger token.
    Note that build triggers must be activated in the DockerHub repository and a trigger token obtained prior to
    attempting to trigger a Docker image build using this function.

    :param in_dockerhub_user: Name of DockerHub user owning the repository.
    :param in_dockerhub_repository_name:  Name of DockerHub repository.
    :param in_dockerhub_trigger_token: DockerHub trigger token.
    :param in_dockerhub_tagname: Name of tag in DockerHub repository.
    :param in_request_timeout: Request timeout in seconds.
    # Create the complete trigger URL and the trigger payload.
    dockerhub_trigger_url = DOCKERHUB_BASE_URL + in_dockerhub_user + "/" + in_dockerhub_repository_name + \
                            "/trigger/" + in_dockerhub_trigger_token + "/"
    dockerhub_trigger_payload_map = {"docker_tag": in_dockerhub_tagname}
    dockerhub_trigger_payload = json.dumps(dockerhub_trigger_payload_map)

    # Send trigger request.
    dockerhub_trigger_request = urllib2.Request(dockerhub_trigger_url)
    dockerhub_trigger_request.add_header("Content-Type", "application/json")
    contextlib.closing(urllib2.urlopen(dockerhub_trigger_request, dockerhub_trigger_payload,

# -------------------- Main program!
print "----------"
print "Triggering DockerHub build at " + str(

If a HTTP response code indicating an error is returned by DockerHub an error will be raised.
Note how the trigger URL is assembled on rows 27 and 28 using the base DockerHub URL, the username of the DockerHub user owning the repository, the DockerHub repository name and, finally, the trigger token that was obtained after having activated build triggers for the repository.

Happy coding!


Leave a Reply

Your email address will not be published. Required fields are marked *