Triggering Code Manager with custom scripts
Custom scripts are a good way to trigger deployments if you have requirements such as existing continuous integration systems, privately hosted Git repositories, or custom notifications.
Alternatively, a webhook provides a simpler way to trigger deployments automatically.
To create a script that triggers Code Manager to deploy your environments, you can use either the puppet-code
command or a curl
statement that hits the endpoints. We recommend the
puppet-code
command.
Either way, after you have composed your script, you can trigger deployment of new code into your environments. Commit new code, push it to your control repo, and run your script to trigger Code Manager to deploy your code.
All of these instructions assume that you have enabled and configured Code Manager.
Deploying environments with the puppet-code
command
The puppet-code
command allows you to trigger environment deployments from the
command line. You can use this command in your custom scripts.
For example, to deploy all environments and then return deployment results with commit SHAs for each of your environments, incorporate this command into your script:
puppet-code deploy --all --wait
Deploying environments with a curl command
To trigger Code Manager code
deployments with a custom script, compose a curl
command to hit the Code Manager/deploys
endpoint.
To deploy environments with a curl
command in your custom script, compose a curl
command to hit the /v1/deploys
endpoint.
Specify either the "deploy-all"
key, to deploy all configured environments, or the
"environments"
key, to
deploy a specified list of environments. By default, Code Manager
returns queuing results immediately after accepting the deployment request.
If you prefer to get complete deployment results after Code Manager finishes processing the deployments, specify the optional "wait"
key with your request. In deployments that are geographically dispersed
or have a large number of environments, completing code deployment can take up to several
minutes.
For complete information about Code Manager endpoints, request formats, and responses, see the Code Manager API documentation.
You must include a custom URL for Code Manager and a PE authentication token in any request to a Code Manager endpoint.
Creating a custom URL for Code Manager scripts
curl
command in a custom
script, you’ll need a custom Code Manager URL. This URL is
composed of: - Your primary server name (for example,
primary.example.com
) - The Code Manager port (for example, 8170)
- The endpoint you want to hit (for example,
/code-manager/v1/deploys/
) - The authentication token you generated earlier (
token=<TOKEN>
)
curl
command might
look something like this:
https://primary.example.com:8170/code-manager/v1/deploys&token=<TOKEN>
Attaching an authentication token
You must attach a PE authentication token to any request to Code Manager endpoints. You can either:
- Specify the path to the token with
puppet-access show
in the body of your request. For example: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.
- Attach the entire token to your Code Manager URL using the
token
query parameter. For example:https://$(puppet config print server):8170/code-manager/v1/webhook?type=github&token=<TOKEN>
If you are using a curl
command to hit the /webhook
endpoint directly, you must attach the entire
token.
Checking deployment status with a curl commmand
You can check the status of a deployment by hitting the
status
endpoint.
To use a curl
command in your custom script, compose a
curl
command to hit the status endpoint. You must incorporate a
custom URL for Code Manager in the script.