Create new deployment

This method will create a deployment.

URL

/projects/<project>/deployments

Replace <project> with the permalink of the project.

HTTP Method

POST

Supported Parameters

parent_identifier - The UUID of the server or server group to deploy to (required)
start_revision - The start revision of the deployment (required, a blank value can be sent if you wish to deploy the entire branch)
end_revision - The end revision of the deployment (required)
branch - The branch you wish to deploy from
mode - The deployment mode, can be queue or preview
copy_config_files - If config files should be copied during the deployment, either true or false
run_build_commands - If you want to run build commands during the deployment, either true or false
use_build_cache - If you want to use the project's build cache (if configured), either true or false
use_latest - Set the deployment to use the last commit deployed and the latest in the repository (used only for scheduling deployments). Send a string of "1" to enable the option.

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-d '{"deployment":{ "parent_identifier":"7563d091-ca73-588e-cfe2-e4936f190145", \
      "start_revision" : "e8f6302c76baae1cef0ea4960f770087bfe3a129", \
      "end_revision" : "e84b5937f1132932dd56026db26a76f406555c19", \
      "mode" : "queue", \
      "copy_config_files" : 1, \
      "email_notify" : 1 \
    }}' http://test.deployhq.com/projects/project/deployments/

Example Response (Completed)

{
  "files": {
    "7563d091-ca73-588e-cfe2-e4936f190145" : {
      "removed": [
        "removed_file_1.txt",
        "removed_file_2.txt"
      ],
      "changed": [
        "added_file_1.txt",
        "modified_file_1.txt"
      ]
    }
  },
  "log": [
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "Disconnected from SFTP/SSH server"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "success",
      "message": "Deployment complete"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "0 config file(s) need to be uploaded"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "0 file(s) have been changed and will be uploaded"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "0 file(s) are no longer required and will be removed"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "Connected to SFTP/SSH server at host.example.com:22"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "note",
      "message": "Connecting to server at host.example.com:22"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "note",
      "message": "Calculating changes required for deployment"
    },
    {
      "timestamp": "2011-11-28T12:35:55Z",
      "type": "note",
      "message": "Beginning deployment from e84b5937f1132932dd56026db26a76f406555c19 to e84b5937f1132932dd56026db26a76f406555c19 (master)"
    }
  ],
  "project": {
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAsj+rjTUvuaXXAsI4WapI8WXH...= DeployHQ.com Key for example-project",
    "permalink": "example-project",
    "name": "Example Project",
    "repository": {
      "port": null,
      "username": "",
      "url": "git@codebasehq.account/example-project/app.git",
      "branch": "master",
      "scm_type": "git",
      "cached": true,
      "hosting_service": {
        "name": "Codebase",
        "url": "http://www.codebasehq.com",
        "commits_url": "http://account.codebasehq.com/projects/example-project/repositories/app/commits/master",
        "tree_url": "http://phoenixdev5.codebasehq.com/projects/example-project/repositories/app/tree/master"
      }
    }
  },
  "servers": [
    {
      "name": "Server",
      "port": 22,
      "server_path": "/var/www/app",
      "username": "dan",
      "use_ssh_keys": false,
      "last_revision": "e84b5937f1132932dd56026db26a76f406555c19",
      "hostname": "host.example.com",
      "identifier": "7563d091-ca73-588e-cfe2-e4936f190145",
      "protocol_type": "ssh"
    }
  ],
  "start_revision": {
    "author": "Dan Wentworth",
    "timestamp": "2011-01-30T00:12:58+00:00",
    "ref": "e84b5937f1132932dd56026db26a76f406555c19",
    "message": "updated configs",
    "email": "dan@atechmedia.com"
  },
  "configuration": {
    "email_notify": false,
    "notification_addresses": "dan@atechmedia.com",
    "copy_config_files": true
  },
  "timestamps": {
    "duration": null,
    "completed_at": "2011-11-28T12:36:13Z",
    "queued_at": "2011-11-28T12:35:52Z",
    "started_at": "2011-11-28T12:35:55Z"
  },
  "identifier": "22585edc-e0c6-24d7-372e-c13755d1c2da",
  "end_revision": {
    "author": "Dan Wentworth",
    "timestamp": "2011-01-30T00:12:58+00:00",
    "ref": "e84b5937f1132932dd56026db26a76f406555c19",
    "message": "updated database configs",
    "email": "dan@atechmedia.com"
  },
  "status": "completed"
}

Example Response (Preview)

{
  "status":"preview_pending",
  "identifier":"6bd5cdc4-d652-92e8-322f-287929091f03"
}

When creating a preview deployment, you can poll the /projects/<project>/deployments/<uuid>/preview endpoint to see its progress and a list of potential file changes once the preview has been fully generated.

Scheduling a deployment

When scheduling a deployment using the API, the following data must be sent in addition to the normal parameters for a deployment:

at - Use future, daily, weekly or monthly to schedule a new deployment.

Depending on the type of at schedule used, the following parameters will be required (all values are numeric unless otherwise stated):

`future`

day - The starting day of the month
month - The starting month of the year
year - The starting year
hour - The starting hour
minute - The starting minute

`daily`

hour - The starting hour
minute - The starting minute

`weekly`

weekday - The start day of the week (send as literal string representing the day of the week, i.e. "Monday")
hour - The starting hour
minute - The starting minute

`monthly`

day - The starting day of the month
hour - The starting hour
minute - The starting minute

Example cURL request (for a weekly schedule set for 9am every Monday)

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-d '{ \
      "deployment":{ \
        "parent_identifier":"7563d091-ca73-588e-cfe2-e4936f190145", \
        "start_revision" : "e84b5937f1132932dd56026db26a76f406555c19", \
        "end_revision" : "e84b5937f1132932dd56026db26a76f406555c19", \
        "mode" : "queue", \
        "copy_config_files" : 1, \
        "email_notify" : 1 \
      }, \
      "schedule":{ \
        "frequency": "weekly", \
        "weekly":{ \
          "weekday" : "Monday", \
          "hour": "9", \
          "minute": "0" \
        } \
      } \
    }' http://test.deployhq.com/projects/project/deployments/

Example Response

This additional data is returned if a deployment has been scheduled, along with the normal payload for a deployment:

  "frequency":"weekly",
  "at":{
    "weekday":"Monday",
    "hour":9,
    "minute":0
  },
  "next_deployment_at":"2018-07-30T09:00:00.000+01:00"