Triggering Code Manager with a webhook

To deploy your code, you can trigger Code Manager by hitting a web endpoint, either through a webhook or a custom script. Webhooks are the simplest way to trigger Code Manager.

Code Manager supports webhooks for GitHub, Bitbucket Server (formerly Stash), Bitbucket, and Team Foundation Server. The webhook must only be used by the control repository. It can't be used by any other repository (for example, other internal component module repositories).
Important: Code Manager webhooks are not compatible with Continuous Delivery for PE. If your organization uses Continuous Delivery for PE, you must use a method other than webhooks to deploy environments.
Tip: Triggering Code Manager with custom scripts is a good alternative to webhooks if you have requirements such as existing continuous integration systems (including Continuous Delivery for Puppet Enterprise (PE)), privately hosted Git repos, or custom notifications.

Create a Code Manager webhook

To set up the webhook to trigger environment deployments, you must create a custom URL, and then set up the webhook with your Git host.

Create a custom URL

Create a custom URL to allow communication between your Git host and Code Manager.

Code Manager supports webhooks for GitHub, Bitbucket Server (formerly Stash), Bitbucket, GitLab (Push events only), and Team Foundation Server (TFS).
Important: If you want to use a GitHub webhook with the Puppet signed cert, you must disable SSL verification.
The custom webhook URL must use these elements:
Element Description Example
Name Your primary server's DNS name puppet.example.com
Port The port used by Code Manager 8170
Endpoint The Code Manager webhook endpoint /code-manager/v1/webhook/
Parameters Required and optional Code Manager webhook query parameters type=github&token=<TOKEN>
The minimum possible valid webhook URL format is:
https://<NAME>:<PORT>/code-manager/v1/webhook?type=<TYPE>
The token parameter is required unless you disabled authenticate_webhook. With the token parameter, the valid URL format is:
https://<NAME>:<PORT>/code-manager/v1/webhook?type=<TYPE>&token=<TOKEN>
If your source configuration requires the prefix parameter, the valid URL format is:
https://<NAME>:<PORT>/code-manager/v1/webhook?type=<TYPE>&prefix=<PREFIX>&token=<TOKEN>
For example, the following URLs are for a GitHub webhook and a Bitbucket Server webhook:
https://puppet.example.com:8170/code-manager/v1/webhook?type=github&token=<TOKEN>
https://puppet.example.com:8170/code-manager/v1/webhook?type=bitbucket-server&prefix=dev&token=<TOKEN>
Tip: After you Set up the Code Manager webhook on your Git host, you can use this URL to call the POST /v1/webhook endpoint.

Code Manager webhook query parameters

You can use these query parameters in your the Code Manager webhook URL.

Parameter Description Value
type Required. Specifies the type of POST body to expect. Specify the value corresponding with your Git host:
  • GitHub: type=github
  • GitLab: type=gitlab
  • Bitbucket Server version 5.4 or later (formerly Stash): type=bitbucket-server
  • Bitbucket: type=bitbucket
  • Team Foundation Server (resource version 1.0 is supported): type=tfs-git
prefix Conditionally required. Specifies a prefix for converting branch names to environment names.
Important: Required if you used prefixing when Configuring sources. If your sources use prefixing and you do not specify this parameter, Code Manager can't correctly locate or deploy environments, or translate branch names to valid environment names.
 prefix=<PREFIX>
token Conditionally required. Specifies the entire PE authorization token to use for code deployments. To get a token, you can Request an authentication token for deployments.
Important: Required unless you disabled authenticate_webhook in your Code Manager configuration.
 token=<TOKEN>

Set up the Code Manager webhook on your Git host

In your Git server’s webhook form, enter your custom URL as the payload URL.

The content type for Code Manager webhooks is JSON.

The specific steps for setting up a webhook depends on your Git host. Refer to your Git host's documentation for instructions.

For example, in a GitHub repo, click Settings > Webhooks & services, enter the payload URL, and enter application/json as the content type.

Tip: On Bitbucket Server, the server configuration menu has settings for both Hooks and Webhooks. Use the Webhooks configuration for your Code Manager webhook. Make sure you're using Bitbucket Server version 5.4 or later and the latest fix version of PE.

After setting up your webhook, you've finished setting up Code Manager. From now on, when you commit new code and push it to your control repo, the webhook triggers Code Manager to deploy your code. You can also use the POST /v1/webhook endpoint to manually trigger your webhook.

Troubleshoot a Code Manager webhook

To troubleshoot your webhook, you can review your Git host's logs. Refer to your Git host's documentation for information about their logs and their suggestions for resolving common webhook issues.

Deployments triggered by a webhook in Stash/Bitbucket, GitLab, or GitHub are governed by authentication and hit the POST /v1/webhook endpoint for each service type.

If you are using a GitLab version older than 8.5.0, Code Manager's webhook authentication doesn't work because of the length of the authentication token. To use the webhook with GitLab, either disable authentication or update GitLab. If you disable webhook authentication, it is disabled only for the POST /v1/webhook endpoint. It is not possible to disable authentication for the POST /v1/deploys or GET /v1/deploys/status endpoints.

To troubleshoot webhook issues, follow the instructions for Triggering Code Manager with a webhook while monitoring the Puppet Server log. To monitor the logs, open a separate terminal window and run:
tail -f /var/log/puppetlabs/puppetserver/puppetserver.log

Watch the log closely for errors and information messages when you trigger the webhook. The puppetserver.log file is the only location these errors appear. If you cannot determine the problem with your webhook this way, manually deploy to the POST /v1/deploys endpoint while monitoring the console-services.log file, as described in Troubleshooting Code Manager.

For other Code Manager issues, refer to Troubleshooting Code Manager.