Code Manager API

You can use the Code Manager API to deploy code and check the status of deployments on your primary server and compilers without direct shell access.

Forming Code Manager API requests

The Code Manager API accepts well-formed HTTPS requests and requires authentication.

Requests must include a URI path following the pattern:

https://<DNS>:8170/code-manager/v1/<ENDPOINT>

The variable path components derive from:

DNS: Your primary server's DNS name. You can use localhost, manually enter the DNS name, or use a puppet command (as explained in Using example commands).
ENDPOINT: One or more sections specifying the endpoint, either deploys, webhook, or deploys/status.

Tip: If your Code Manager service does not use port 8170, you need to change the port number in the path.

For example, you could use any of these paths to call the GET /v1/deploys/status endpoint:

https://$(puppet config print server):8170/code-manager/v1/deploys/status
https://localhost:8170/code-manager/v1/deploys/status
https://puppet.example.dns:8170/code-manager/v1/deploys/status

To form a complete curl command, you need to provide appropriate curl arguments, authentication, and you might need to supply the content type and/or additional parameters specific to the endpoint you are calling.

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Code Manager API authentication

Code Manager API requests require token-based authentication. For instructions on generating, configuring, revoking, and deleting authentication tokens in PE, go to Request an authentication token for deployments or Token-based authentication.

To provide tokens for deploys endpoints, you can use an X-authentication header with the puppet-access show command, such as:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8170/code-manager/v1/deploys/status"

curl --insecure --header "$auth_header" "$uri"

Or you can use the actual token, such as:

auth_header="X-Authentication: <TOKEN>"
uri="https://$(puppet config print server):8170/code-manager/v1/deploys/status"

curl --insecure --header "$auth_header" "$uri"

Important: Unlike the deploys endpoints, when calling the webhook endpoint, you must append the token as a query parameter. Tokens supplied in query parameters might appear in access logs.

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` is`false` 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`. Restriction: 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

Note: If your request included the wait key, the response arrives after the deployments finish. You might have to wait several minutes, depending on the number of environments, deployment sizes, and how geographically dispersed the deployments are.

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"
     }

Tip: If deployments are failing when triggered by the deploys endpoint, refer to Troubleshooting Code Manager for information about monitoring logs associated with this endpoint.

POST /v1/webhook

Deploy code by triggering your Code Manager webhook.

Request format

Unlike other POST requests, when forming Code Manager API requests to the webhook endpoint, you must append parameters to the URI path, rather than using a JSON body. Available parameters include:

type: Always required. Identifies your Git host.
prefix: Required if your source configuration uses prefixing. Specifies the prefix to use when converting branch names to environment names.
token: Required unless you disabled authenticate_webhook in your Code Manager configuration. You must supply the authentication token in the token parameter. Tokens supplied in query parameters might appear in access logs.

For more information and examples for each parameter, refer to Code Manager webhook query parameters.

For example, this request includes the type and token parameters:

curl -X POST 'https://$(puppet config print server):8170/code-manager/v1/webhook?type=github&token=<TOKEN>'

Tip: For more information, refer to Triggering Code Manager with a webhook.

Response format

When your Code Manager webhook is automatically triggered by a push to the control repo, all responses appear in your Git provider's interface. Code Manager does not give command line responses to automatic webhook triggers.

If you use a curl command to manually trigger the webhook, and your request is well-formed and valid, Code Manager returns an OK response. This only indicates that the request was valid, it does not indicate whether a resulting code deployment succeeded or failed.

Error responses

If an error occurs when the webhook is automatically triggered, check your Git provider interface for error responses. If there is a problem with the webhook, refer to Troubleshoot a Code Manager webhook.

If you use a curl command to manually trigger the webhook, and the request has a missing or invalid type, the endpoint returns an unrecognized-webhook-type error along with a copy of the supplied type value and a list of valid type values.

GET /v1/deploys/status

Get the status of code deployments that Code Manager is currently processing for each environment. You can specify an id query parameter to get the status of a particular deployment.

Request format

When forming Code Manager API requests to this endpoint, the request is a basic call with authentication, such as:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8170/code-manager/v1/deploys/status"

curl --header "$type_header" --header "$auth_header" "$uri"

A basic request returns the status of all deployments in the queue. You can append the optional id query parameter to get the status of a specific deployment by calling its position in the current deployment queue. For example, this request calls the status of the fifth deployment in the current queue:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8170/code-manager/v1/deploys/status?id=5"

curl --header "$type_header" --header "$auth_header" "$uri"

Response format

For requests that do not include the id parameter, the successful response is a JSON object describing the status of each deployment in the queue. The body is divided into three secondary objects (deploys-status, file-sync-storage-status, and file-sync-client-status) that report information about deployments depending on the deployments' statuses.:

deploys-status: Contains four arrays representing possible code deployment statuses, which are new, queued, deploying, or failed.
- For each new, queued, deploying, and failed deployment, there is a nested object containing the deployment's position in the queue (id), the environment name (environment), and the time the deployment was put in the queue (queued-at).
- For failed deployments, there is an additional error object describing the failure (details and corrected-name), the type of error (kind), and a longer error message (msg). 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.
- If there are no deployments with a particular status in the queue, the array for that status is empty.
- Successfully completed deployments are reported in either the file-sync-storage-status or file-sync-client-status objects.
file-sync-storage-status: Contains a deployed object that lists environments that Code Manager has successfully deployed to the code staging directory, but not yet synced to the live code directory. For each deployed environment, the response includes the environment name (environment), the deployment date and time (date), and the commit SHA from the control repo that Code Manager used for the environment's code deploy (deploy-signature).
file-sync-client-status: Lists the status of your primary server and each compiler that Code Manager is deploying environments to, including whether the code in the primary server's staging directory has been synced to the live code directory. Contains:
- all-synced: A Boolean indicating whether all requested code deployments are synced to the live code directories on their respective servers.
- file-sync-clients: An object containing a list of servers that Code Manager deployed code to. For each server, the response includes the date and time of the server's last check in (last_check_in_time), whether the server synchronized with file sync storage (synced-with-file-sync-storage), and an array of deployment objects associated with that server. Each deployment object includes the environment name (environment), the deployment date and time (date), and the commit SHA from the control repo that Code Manager used for the environment's code deploy (deploy-signature).

For requests that include the id parameter, the response is condensed and uses the following keys to describe the specified deployment:

environment: The name of the environment.
status: The deployment's status at the time of the response. Can be new, queued, deploying, failed, syncing, or synced.
queued-at: The date and time when the deployment was put in the queue.

For example, this is a response for a single deployment:

{
  "environment": "production",
  "id": 1,
  "status": "deploying",
  "queued-at": "2018-05-10T21:44:25.000Z"
}

And this is an example response for an entire deployment queue:

{  
   "deploys-status":{  
      "queued":[  
         {  
            "environment":"dev",
            "id":3,
            "queued-at":"2018-05-15T17:42:34.988Z"
         }
      ],
      "deploying":[  
         {  
            "environment":"test",
            "id":1,
            "queued-at":"2018-05-15T17:42:34.988Z"
         },
         {  
            "environment":"prod",
            "id":2,
            "queued-at":"2018-05-15T17:42:34.988Z"
         }
      ],
      "new":[  

      ],
      "failed":[  
         {
            "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"
            },
            "queued-at": "2018-06-01T21:28:18.292Z"
         }
     ]
   },
   "file-sync-storage-status":{
      "deployed":[
         {
            "environment":"prod",
            "date":"2018-05-10T21:44:24.000Z",
            "deploy-signature":"66d620604c9465b464a3dac4884f96c43748b2c5"
         },
         {
            "environment":"test",
            "date":"2018-05-10T21:44:25.000Z",
            "deploy-signature":"24ecc7bac8a4d727d6a3a2350b6fda53812ee86f"
         },
         {
            "environment":"dev",
            "date":"2018-05-10T21:44:21.000Z",
            "deploy-signature":"503a335c99a190501456194d13ff722194e55613"
         }
      ]
   },
   "file-sync-client-status":{
      "all-synced":false,
      "file-sync-clients":{
         "chihuahua":{
            "last_check_in_time":null,
            "synced-with-file-sync-storage":false,
            "deployed":[

            ]
         },
         "localhost":{
            "last_check_in_time":"2018-05-11T22:41:20.270Z",
            "synced-with-file-sync-storage":true,
            "deployed":[
               {
                  "environment":"prod",
                  "date":"2018-05-11T22:40:48.000Z",
                  "deploy-signature":"66d620604c9465b464a3dac4884f96c43748b2c5"
               },
               {
                  "environment":"test",
                  "date":"2018-05-11T22:40:48.000Z",
                  "deploy-signature":"24ecc7bac8a4d727d6a3a2350b6fda53812ee86f"
               },
               {
                  "environment":"dev",
                  "date":"2018-05-11T22:40:50.000Z",
                  "deploy-signature":"503a335c99a190501456194d13ff722194e55613"
               }
            ]
         }
      }
   }
}

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.