POST /v1/deploys

Trigger Code Manager to deploy code to a specific environment or all environments, or use the dry-run parameter to test your control repo connection.

Request format

When forming Code Manager API requests to this endpoint, the content type is application/json. The body must be a JSON object using the keys described in the following table. You must supply either deploy-all or environments, and, although not required, you might find the other keys useful in certain situations.

Key	Format	Definition
deploy-all	Boolean	Set to true if you want to trigger code deployments for all known environments. If false or omitted, you must include the environments key. For information about how Code Manager detects environments, refer to Add an environment.
environments	Array of strings	Specify the names of one or more specific environments for which you want to trigger code deployments. This key is required if deploy-all isfalse or omitted.
deploy-modules	Boolean	Indicate whether Code Manager deploys modules declared in an environment's Puppetfile. If false, modules aren't deployed. If omitted, the default value is true. Modules are always deployed the first time an environment is deployed, even if you set deploy-modules to false. This ensures environments are fully populated upon first use. If you want to exclude a module from an environments initial deployment, remove or comment-out the module in the environment's Puppetfile. For more information, refer to: Managing modules with a Puppetfile
modules	JSON object	A comma-separated or space-separated list of specific modules to deploy.
wait	Boolean	Indicates how soon you want Code Manager to return a response. If false or omitted, Code Manager returns a list of queued deployments immediately after receiving the request. If true, Code Manager returns a more detailed response after all deployments have finished (either successfully or with an error).
dry-run	Boolean	Use to test Code Manager's connection to your source control provider. If true, Code Manager attempt to connect to each of your remotes, attempts to fetch a list of environments from each source, and reports any connection errors. For more information about having multiple remotes, refer to: How the control repository works

Here are three examples of complete curl commands for the deploys endpoint.

This example deploys the production environment and uses the wait key to get a more detailed response after the deployment finishes:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8170/code-manager/v1/deploys"
data='{"environments": ["production"], "wait": true}'

curl --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

This example deploys two environments and uses the wait key:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
cacert="$(puppet config print localcacert)"
uri="https://$(puppet config print server):8170/code-manager/v1/deploys"
data='{"environments": ["production", "testing"], "wait": true}'

curl --header "$type_header" --header "$auth_header" --cacert "$cacert" --request POST "$uri" --data "$data"

This example deploys all environments and returns queueing information immediately after the submitting the request:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
cacert="$(puppet config print localcacert)"
uri="https://$(puppet config print server):8170/code-manager/v1/deploys"
data='{"deploy-all": true}'

curl --header "$type_header" --header "$auth_header" --cacert "$cacert" --request POST "$uri" --data "$data"

Response format

A successful response contains a list of objects, where each object contains data about a queued or deployed environment. Response objects use keys described in the following table. Which keys are included and possible values for the status key depend on the value of the wait key in the request.

Key	Definition
environment	The name of the queued or deployed environment.
id	An integer generated by Code Manager that identifies the environment's order in the deployment queue.
status	A code deployment's status at the time of the response. If the request omitted wait or included "wait": false, then the status is either new or queued. new: The deploy request is accepted but not yet queued. queued: The deploy is queued and waiting to start. If the request included "wait": true, the status is either complete or failed. complete: The deploy is complete and synced to the live code directory on the primary server and compilers. failed: The deploy failed. Response objects for failed deployments also include the error key.
deploy-signature	The commit SHA from the control repo that Code Manager used for the environment's code deploy. Only included if the request included "wait": true.
file-sync	An object containing environment-commit and code-commit, which are commit SHAs used internally by file sync to identify the code synced to the code staging directory. Only included if the request included "wait": true.
error	Only included if the request included "wait": true and the deployment failed. The error key is an object that uses the following keys to describe the failure: details: Can contain the corrected-name of the environment. kind: The type of error encountered. msg: A longer error message that can help you troubleshoot the failure. Failure information remains in this endpoint's responses until cleaned up by garbage collection, even if the environment has a successful deployment after the failure. For more information, refer to Configuring garbage collection.

For example, this response resulted from a request that included a false or omitted wait key:

[
  {
    "environment": "production",
    "id": 1,
    "status": "queued"
  },
  {
    "environment": "testing",
    "id": 2,
    "status": "queued"
  }
]

Whereas this example response is from a request that included "wait": true:

[
  {
    "deploy-signature":"482f8d3adc76b5197306c5d4c8aa32aa8315694b",
    "file-sync":{
      "environment-commit":"6939889b679fdb1449545c44f26aa06174d25c21",
      "code-commit":"ce5f7158615759151f77391c7b2b8b497aaebce1"},
    "environment":"production",
    "id":3,Code Manager
    "status":"complete"
  }
]

This example describes a failed deployment:

    {
         "environment": "test14",
         "error": {
             "details": {
                 "corrected-name": "test14"
             },
             "kind": "puppetlabs.code-manager/deploy-failure",
             "msg": "Errors while deploying environment 'test14' (exit code: 1):\nERROR\t -> Authentication failed for Git remote \"https://github.com/puppetlabs/puffppetlabs-apache\".\n"
         },
         "id": 52,
         "status": "failed"
     }