Pull Dog documentation


Getting started with Pull Dog only takes a minute, and requires two steps.

Installing the app

The first thing to do is to install the GitHub app to your user and/or organizations.

Customizing Pull Dog for a repository

Note: This step is only needed if you want to customize how Pull Dog works, if your Docker Compose file is not located in the root of your repository, or if its filename differs from the default docker-compose.yml.

To customize how Pull Dog works for a repository, you need to push a pull-dog.json configuration file to the repository's master branch.

The most minimal configuration possible contains just a pointer to the docker-compose.yml file in your repository that you want to provision a test environment from:

    "dockerComposeYmlFilePaths": [

For more ways to customize Pull Dog or how it builds your test environment, see Configuration.


All below configuration values can be set either using a lazy configuration or a JSON file configuration.

Possible values

You can customize Pull Dog's behavior in many ways.

dockerComposeYmlFilePaths (required)

Tells Pull Dog which Docker Compose YML file(s) to choose when provisioning a test environment.

  • Example: ["your/path/to/docker-compose.yml"]
  • Type: string[]

isLazy (optional)

Determines whether or not Pull Dog should wait until it receives an API call from a build server before provisioning. See lazy configuration for more details.

  • Example: true
  • Type: true|false
  • Default: false

expiry (optional)

Sets a timeout on when the environment should be destroyed again.

  • Example: "2.03:02:10" for 2 days, 3 hours, 2 minutes and 10 seconds.
  • Type: string|null
  • Default: null

buildArguments (optional)

Specifies build-time environment variables and build arguments. Need to provide these dynamically from your build server? See lazy configuration for more details.

  • Example: { "MY_KEY": "my value" }
  • Type: { [argumentName: string]: string }
  • Default: { }

conversationMode (optional)

Specifies how comments from Pull Dog should behave.

"singleComment" makes Pull Dog insert a new GitHub comment if none is present, and edit the existing one if one is present.

"multipleComments" inserts a new GitHub comment every time. This might be quite spammy, which is why "singleComment" is recommended.

  • Example: "multipleComments"
  • Type: "singleComment"|"multipleComments"
  • Default: "singleComment"

label (optional)

Specifies a GitHub label that should be set on the pull requests that have Pull Dog test environments ready for them. Make sure this label already exists in your repository.

  • Example: "pull-dog-environment-ready"
  • Type: string
  • Default: null

JSON file configuration

The simplest way of configuring Pull Dog is by pushing the configuration as a pull-dog.json file to your master branch.

    "expiry": "2.03:02:10",
    "buildArguments": { "MY_KEY": "my value" },
    "conversationMode": "singleComment",
    "label": "pull-dog-environment-ready",
    "dockerComposeYmlFilePaths": [ 

Lazy configuration

Lazy configuration will not provision a test environment when the pull request is opened, but will instead wait for a build server to make an API call to Pull Dog which then starts provisioning.

The reason this may be useful is to set dynamic variables that are only available from the build server (such as referencing a specific Docker image that was just built and published).


The below example uses the pull request portainer/portainer #3932 as an example.

59239347 is the GitHub ID of the repository. This (and the API key to use) can be optained by clicking the repository from the Pull Dog dashboard page.

Instead of specifying pullRequestHandle, you can also reference a branch name by specifying branchReference.

curl \
    --header "Content-Type: application/json" \
    --request POST \
    --data '
        "repositoryHandle": "59239347",
        "pullRequestHandle": "3932", 
        "configuration": {
            "expiry": "2.03:02:10",
            "buildArguments": { "MY_KEY": "my value" },
            "conversationMode": "singleComment",
            "label": "pull-dog-environment-ready",
            "dockerComposeYmlFilePaths": [
    }' \