Triggering Code Manager with a Webhook

A newer version is available; see the version menu above for details.

To deploy your code, you’ll need to trigger Code Manager by hitting a web endpoint. You can do this either through a webhook or a custom script. Either way, you’ll also need to set up authentication and create a custom URL.

The webhook, described on this page, is the simplest way to trigger Code Manager. Custom scripts are a good alternative if you have requirements such as existing continuous integration systems, privately hosted Git repos, or custom notifications. See Creating custom scripts for information about writing a script to trigger Code Manager.

Code Manager supports webhooks for GitHub, Bitbucket Server (formerly Stash), Bitbucket, and Team Foundation Server.

Create a Webhook

To set up the webhook to trigger Code Manager to deploy your environments:

  1. Generate an authentication token for authentication and authorization.
  2. Create a custom URL that triggers Code Manager.
  3. Set up the webhook.

Generate an Authentication Token

Code Manager needs an authentication token to use for both authentication and authorization. This token allows Code Manager to securely deploy the requested environment.

To generate a token for Code Manager:

  1. Create a deployment user role and user.
  2. Request an authentication token for the deployment user. This step requires that you have already configured the Puppet Access command line tool.

Note to GitLab users: Because GitLab has a character limit on webhooks, adding the token to the webhook won’t work on GitLab. Instead of using a token, you should instead turn off authentication by customizing your Code Manager configuration in Hiera with the authenticate_webhook parameter.

Create a deployment role and user

Before you request an authentication token, you must assign a user the correct permissions with role-based access control (RBAC). We recommend that you create a dedicated deployment user for Code Manager use. You can find detailed instructions for creating users and user roles in the RBAC documentation.

To create the deployment user and user role:

  1. Create a new role named “Deploy Environments”.
  2. Assign this role the following permissions:
    • Add the Puppet Environment type.
      • Set Permissions for this type to Deploy code.
      • Set Object for this type to All.
    • Add the Tokens type.
      • Set Permissions for this type to Override default expiry.
  3. Create a deployment user.
  4. Add the deployment user to the Deploy Environments role.

Next, request the token.

Request an authentication token

To request this token, you must have already configured the Puppet Access command line tool.

Note that by default, authentication tokens have a five-minute lifetime. With the Override default expiry permission set, you can change the lifetime to a duration better suited for a long-running, automated process.

Generate the authentication token using the puppet-access command:

  1. On the command line on the master, run puppet-access login --service-url https://<HOSTNAME OF PUPPET ENTERPRISE CONSOLE>:4433/rbac-api --lifetime 180d.

  2. Enter the username and password of the deployment user when prompted.

The generated token is stored in a file for later use. The default location for storing the token is ~/.puppetlabs/token. To view the token, run puppet-access show.

In the next step, you’ll attach this token to a custom URL for your Code Manager trigger.

Create a custom URL

To trigger Code Manager, you’ll need a custom URL composed of:

  • The name of the Puppet master server (for example,
  • The Code Manager port (for example, 8170)
  • The endpoint (/code-manager/v1/webhook/)
  • Any relevant query parameters (for example, type=github)
  • The authentication token you generated earlier (token=<TOKEN>)

Webhook endpoint

The webhook endpoint triggers environment deployments that are based on version control system webhooks from the control repo. Pass the authentication token with the token query parameter. To use the Github webhook with the Puppet signed cert, disable SSL verification.

Code Manager supports webhooks for GitHub, Bitbucket Server (formerly Stash), Bitbucket, and Team Foundation Server (TFS).

Query parameters

  • type: Required. Specifies which type of post body to expect. Accepts:
    • github: GitHub
    • stash: Bitbucket Server (Stash)
    • bitbucket: Bitbucket
    • tfs-git: Team Foundation Server (resource version 1.0 is supported)
  • prefix: Specifies a prefix for converting branch names to environments.
  • token: Specifies the entire PE authorization token.

So, a URL for a GitHub webhook might look like this:<TOKEN>

The URL for a Stash webhook might look something like this:<TOKEN>

With the complete token attached, a GitHub URL looks something like this:

Set up the webhook

Enter the URL you created above into your Git server’s webhook form as the payload URL. Exactly how you do this varies, depending on where your Git repos are hosted. For example, in your Github repo, click on Settings > Webhooks & services to enter the URL. Set the content type to JSON.

Next Steps

At this point, your Code Manager setup is complete. Code Manager is ready to deploy your new code into your environments. Commit new code and push it to your control repo. The webhook triggers Code Manager and your code is deployed.

↑ Back to top