Code Manager API
Use Code Manager endpoints to deploy code and query environment deployment status on your primary server and compilers without direct shell access.
Authentication
All Code Manager endpoint requests require
token-based authentication. For /deploys
endpoints, you can pass this token as
either an HTTP header or as a query parameter. For the /webhook
endpoint, you must attach
the entire token with the token
query parameter.
To generate an authentication token, from the command line, run puppet-access login
. This command
stores the token in ~/.puppetlabs/token
. To learn more about
authentication for Code Manager use, see
the related topic about requesting an authentication token.
Pass this token as either an X-Authentication
HTTP header or as the token
query parameter with your
request. If you pass the token as a query parameter, it might show
up in access logs.
For example, an HTTP header for the /deploys
endpoint looks something like:
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 --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"
See Usage notes for curl examples for information about forming curl commands.
$pe_headers = @{
"X-Authentication" = "AMi1Wlel2Ybd2Lqu-hdhHaLWCkfvgSgl8AUgKdwzixwe" ;
}
$pe_uri = "https://puppet.winops2019.automationdemos.com:8170/code-manager/v1/deploys"
$pe_codemgr_hash = [ordered]@{
environments = @("production")
}
# Generate JSON object from pe_codemgr_hash
$JSON = $pe_codemgr_hash | convertto-json -compress
Invoke-RestMethod -SkipCertificateCheck -ContentType "application/json" -uri $pe_uri -Method POST -Body $JSON -Headers $pe_headers
Passing the token with the token
query
parameter might look like:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8170/code-manager/v1/webhook?type=github&token=$(puppet-access show)"
data='{"environments": ["production"], "wait": true}'
curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"
# Common Data
$token = "AMi1Wlel2Ybd2Lqu-hdhHaLWCkfvgSgl8AUgKdwzixwe"
$pe_uri = "https://puppet.winops2019.automationdemos.com:8170/code-manager"
# Example 1 - deploys
$pe_headers = @{
"X-Authentication" = "$token" ;
}
$pe_codemgr_hash = [ordered]@{
environments = @("production")
}
# Generate JSON object from pe_codemgr_hash
$JSON = $pe_codemgr_hash | convertto-json -compress
$pe_ex1_uri = "$pe_uri/v1/deploys"
Invoke-RestMethod -SkipCertificateCheck -ContentType "application/json" -uri $pe_ex1_uri -Method POST -Body $JSON -Headers $pe_headers
# Example 2 - Web hook
$pe_ex2_uri = "$pe_uri/v1/webhook?token=$token&type=github"
Write-Output "PE Example 2 URI: $pe_ex2_uri"
Invoke-RestMethod -SkipCertificateCheck -uri $pe_ex2_uri -Method POST -ContentType "application/json"
POST /v1/deploys
Use the Code Manager/deploys
endpoint to queue code deployments.
Request format
POST /deploys
request must be a JSON
object that includes the authentication token and a URL containing: - The name of the primary server, such as
primary.example.com
- The Code Manager port, such as 8170.
- The endpoint.
- The
"environments"
key, with or without the"wait"
key. - The
"deploy-all"
key, with or without the"wait"
key.
Key | Definition | Values |
---|---|---|
"environments"
|
Specifies the environments for which to queue code deployments. If not
specified, the "deploy-all" key must be
specified. |
Accepts an array of strings specifying environments. |
"deploy-all"
|
Specifies whether Code Manager deploys all environments or not. If specified |
true , false
|
"deploy-modules" |
Specifies whether Code Manager deploys modules
from the Puppetfile. If specified
true or
not specified, Code Manager deploys modules. If
specified false , modules aren't
deployed.
Note: To ensure environments are populated before use,
modules are deployed on the first deployment of an environment, even
if you pass
"deploy-modules": false .
|
true , false
|
"modules" |
Specifies the modules to be deployed to the selected environments. | Accepts a comma- and space-separated list of modules to deploy. |
"wait"
|
Specifies whether Code Manager must wait for all deploys to finish or error before it returns a response. If specified Specify together with the |
true , false
|
"dry-run"
|
Tests the Code Manager connection to each of the configured remotes and attempts to fetch a list of environments from each, reporting any connection errors. Specify together with the |
true , false
|
"environments"
key with 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"
See Usage notes for curl examples for information about forming curl commands.
To deploy all configured environments and return only the queuing results, pass the
"deploy-all"
key without 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='{"deploy-all": true}'
curl --header "$type_header" --header "$auth_header" --cacert "$cacert" --request POST "$uri" --data "$data"
Response format
The POST /deploys
response contains a list of objects,
each containing data about a queued or deployed environment.
If the request did not include a "wait"
key, the
response returns each environment's name and status.
If the "wait"
key was included in the request, the
response returns information about each deployment. This information includes a deploy-signature
, which is the commit SHA of the control repo
that Code Manager used to deploy the environment. The output
also includes two other SHAs that indicate that file sync is aware that the environment
has been deployed to the code staging directory.
The response shows any deployment failures, even after they have successfully deployed. The failures remain in the response until cleaned up by garbage collection.
Key | Description | Value |
---|---|---|
"environment"
|
The name of the environment queued or deployed. | A string specifying the name of an environment. |
"id"
|
Identifies the queue order of the code deploy request. | An integer generated by Code Manager. |
"status"
|
The status of the code deployment for that environment. |
Can be one of the following:
|
"deploy-signature"
|
The commit SHA of the control repo that Code Manager used to deploy code in that environment. | A Git SHA. |
"file-sync"
|
Commit SHAs used internally by file sync to identify the code synced to the code staging directory |
Git SHAs for the "environment-commit" and "code-commit" keys. |
/deploys
request without the "wait"
key, the response shows only "new"
or "queued"
status, because this
response is returned as soon as Code Manager accepts the
request.[
{
"environment": "production",
"id": 1,
"status": "queued"
},
{
"environment": "testing",
"id": 2,
"status": "queued"
}
]
If you pass the "wait"
key with your request, Code Manager doesn't return any response until the environment
deployments have either failed or completed. For example:
[
{
"deploy-signature":"482f8d3adc76b5197306c5d4c8aa32aa8315694b",
"file-sync":{
"environment-commit":"6939889b679fdb1449545c44f26aa06174d25c21",
"code-commit":"ce5f7158615759151f77391c7b2b8b497aaebce1"},
"environment":"production",
"id":3,Code Manager
"status":"complete"
}
]
Error responses
If any deployments fail, the response includes an error object for each failed
environment. Code Manager returns deployment results only if
you passed the "wait"
key; otherwise, it returns queue
information.
Key | Definition | Value |
---|---|---|
"environment"
|
The name of the environment queued or deployed. | A string specifying the name of an environment. |
"error"
|
Information about the deployment failure. | Contains keys with error details. |
"corrected-name"
|
The name of the environment. | A string specifying the name. |
"kind"
|
The kind of error encountered. | An error type. |
"msg"
|
The error message. | An error message. |
"id"
|
Identifies the queue order of the code deploy request. | An integer generated by Code Manager. |
"status"
|
The status of the requested code deployment. | For errors, status is "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"
},
"id": 52,
"status": "failed"
}
POST /v1/webhook
Use the Code Manager /webhook
endpoint to trigger code
deploys based on your control repo updates.
Request format
The POST /webhook
request consists of a specially
formatted URL that specifies the webhook type, an optional branch prefix, and a PE authentication token.
You must pass the authentication token with the token
query parameter. To use a GitHub webhook with the Puppet signed certificate, you must disable SSL
verification.
In your URL, include:
- The name of the primary server (for example,
primary.example.com
) - The Code Manager port (for example, 8170)
- The endpoint (
/v1/webhook
) - The
type
parameter with a valid value, such asgitlab
. -
The
prefix
parameter and value. - The
token
parameter with the complete token.
Parameter | Definition | Values |
---|---|---|
type
|
Required. Specifies what type of POST body to expect. |
|
prefix
|
Optional. Specifies a prefix to use in translating branch names to environments. | A string specifying a branch prefix. |
token
|
Specifies the PE authorization token to
use. Required unless you disable webhook_authentication in Code Manager configuration. |
The complete authentication token. |
For example, a GitHub webhook might look like this:
https://primary.example.com:8170/code-manager/v1/webhook?type=github&token=$TOKEN
prefix
parameter
specifed might look like:
https://primary.example.com/code-manager/v1/webhook?type=stash&prefix=dev&token=$TOKEN
You
must attach the complete authentication token to the request. A GitHub request with the entire token attached might look
like this:https://primary.example.com:8170/code-manager/v1/webhook?type=github&token=eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkZXBsb3kiLCJpYXQiOjE0NDY2NjQ1OTAsImV4cCI6MTQ3ODI4Njk5MCwic3ViIjp7ImlkIjoiZWNmOTJlYzYtMjg1Zi00NzExLWI0MDktMzFmMGYzMGIzOGUwIiwibG9naW4iOiJkZXBsb3kifX0.OdEIA-HGRC0r2J87Pj2sDsyz-EMK-7sZalBTswy2e3uSv1Z6ulXaIQQd69PQnSSBExQotExDgXZInyQa_le2gwTo4smjUaBd6_lnPYr6GJ4hjB4-fT8dNnVuvZaE5WPkKt-sNJKJwE9LiEd4W42aCYfse1KNgPuXR5m77SRsUy86ymthVPKHqqexEyuS7LGeQJvyQE1qEejSdbiLg6znlJXhglWic6ZEpHcYBrFFE4aNwuOYXM4yIL803yIMviBwXRtt9HxbtUBZ8D4ag14ELMefQTlqrKvepKXd29oJG06FwkKcWV9PWiQ0Q-NrE17oxrrNkU0ZxioUgDeqGycwvNIaMazztM9NyD-dWmZc4dKJsqm0su0CRkMSWcYPPaeIcsYFI7XSaeC65N4RLIKhUfwIxxE-uODEhcl3mTr9rwZGnVMu3WrY7t6wlbDM9FomPejGM2aJoZ05PinAIYvX3oH5QJ9fam0pVLb-mI3bvkKm2wKAgpc4Dh1ut9sqLWkG8-AwMA4r_oEvLwFzf8clzk34zNyPG7BvlnPle99HjQues690L-fknSdFiXyRZeRThvZop0SWJzvUSR49etmk-OxnMbQE4tCBWZr_khEG5jUDzeKt3PIiXdxmUaaEPHzo6Vl9XIY5
Response format
When you trigger your webhook by pushing changes to your control repository, you can see the response in your Git provider interface. Code Manager does not give a command line response to typical webhook usage.
If you hit the webhook endpoint directly using a curl command with a properly formatted
request, valid authentication token, and a valid value for the "type"
parameter, Code Manager returns a {"status":"OK"}
response, whether or not code successfully
deployed.
Error responses
When you trigger your webhook by pushing changes to your control repository, you can see any errors in your Git provider interface. Code Manager does not give a command line response to typical webhook usage.
"type"
value or no "type"
value, you get an error response such
as:{"kind":"puppetlabs.code-manager/unrecognized-webhook-type","msg":"Unrecognized webhook type: 'githubby'","details":"Currently supported valid webhook types include: github gitlab stash tfs-git bitbucket"}
GET /v1/deploys/status
The Code Manager
/deploys/status
endpoint returns the status of all code deployments that Code Manager is processing for each environment. You can specify an
id
query parameter to return the status of a particular
deployment.
Request format
The body of the GET /deploys/status
request must include
the authentication token and a URL containing:
- The name of the primary server, such as
primary.example.com
. - The Code Manager port, such as 8170.
- The endpoint.
To return the status of all code deployments:
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 --insecure --header "$type_header" --header "$auth_header" --header "$type_header" "$uri"
To return the status of a specified code deployment:
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=1"
curl --insecure --header "$type_header" --header "$auth_header" --header "$type_header" "$uri"
See Usage notes for curl examples for information about forming curl commands.
Response format
The /deploys/status
endpoint responds with a list of all
code deployment requests that Code Manager is processing.
The response contains three sections:
-
"deploys-status"
: Lists the status for each code deployment that Code Manager is processing, including failed deployments. Deployments can be"new"
,"queued"
,"deploying"
, or"failed"
. Environments that have been successfully deployed to either the code staging or live code directories are displayed in the"file-sync-storage-status"
or"file-sync-client-status"
sections, respectively. -
"file-sync-storage-status"
: Lists all environments that Code Manager has successfully deployed to the code staging directory, but not yet synced to the live code directory. -
"file-sync-client-status"
: Lists status for 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 its live code directory.
The response can contain the following keys:
Key | Definition | Values |
---|---|---|
"queued"
|
The environment is queued for deployment. | For each deployment:
|
"deploying"
|
The environment is in the process of being deployed. | For each deployment:
|
"new"
|
Code Manager has accepted a request to deploy the environment, but has not yet queued it. | For each deployment:
|
"failed"
|
The code deployment for the environment has failed. |
For each deployment:
|
"deployed"
|
Lists information for each deployed environment. | For each deployment:
|
"all-synced"
|
Whether all requested code deployments have been synced to the live code directories on their respective servers. |
true , false
|
"file-sync-clients"
|
List of all servers that Code Manager is deploying code to. | For each deployment listed:
|
{
"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":[
]
},
"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"
}
]
}
}
}
}
The /deploys/status?id
endpoint responds with
details about a specified code deployment.
The response contains three sections:
-
"environment"
or"project"
: Type of entity being deployed. -
"status"
: Status of the deployment, including"queued"
,"deploying"
,"new"
,"failed"
,"syncing"
, or"synced"
. -
"queued-at"
: Timestamp specifying when the deployment was first queued.
{
"environment": "production",
"id": 1,
"status": "deploying",
"queued-at": "2018-05-10T21:44:25.000Z"
}
Error responses
If code deployment fails, the "deploys-status"
section
of the response provides an "error"
key for the
environment with the failure. The "error"
key contains
information about the failure.
Deployment failures can remain in the response even after the environment in question is
successfully deployed. Old failures are removed from the "deploys-status"
response during garbage collection.
Key | Definition | Value |
---|---|---|
"environment"
|
The name of the environment queued or deployed. | A string specifying the name of an environment. |
"error"
|
Information about the deployment failure. | Contains keys with error details. |
"corrected-name"
|
The name of the environment. | A string specifying the name. |
"kind"
|
The kind of error encountered. | An error type. |
"msg"
|
The error message. | An error message. |
"queued-at"
|
The date and time when the environment was queued. | A date and time stamp. |
For example, with a failure, the "deploys-status"
response section might look something like:
[
{
"deploys-status": {
"deploying": [],
"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"
}
],
"new": [],
"queued": []
},
...
}
]