Configure webhook triggers

CloudBees CD/RO can be configured to run objects based on changes or requests made in supported SCM repositories using webhook triggers. When changes or requests are made in the SCM repository, a post call is sent by the SCM provider to a preconfigured CloudBees CD/RO endpoint. CloudBees CD/RO processes the payloads of these calls to run target objects.

The following steps are needed to integrate CloudBees CD/RO triggers:

One-time setup:
- Create a service account: Reusable CloudBees CD/RO account to broker webhook interactions.

For each event trigger:

Configure a webhook trigger: In the CloudBees CD/RO server, configure the event trigger on the desired object.

Create a repository webhook: If not automatically configured when the trigger was created, explicitly configure the corresponding webhook in your supported Git-based SCM repository.

Webhooks are supported for the Git-based SCMs GitHub, GitLab, Bitbucket, and Bitbucket Data Center. The corresponding CloudBees CD/RO plugin must be installed in your CloudBees CD/RO instance to configure a webhook for it.

For more information on installing a plugin, refer to Install CloudBees CD/RO plugins.

Create a service account

Service accounts broker all webhook interactions between supported SCM repositories and the CloudBees CD/RO webhook trigger. Access tokens are used by the service account to link webhook triggers to third-party systems.

Service accounts are for webhook triggers only. You must have access rights to create a service account. Contact your CloudBees CD/RO site administrator for assistance.

Objects created when a service account runs a webhook trigger have the service account set as the object owner, and the owner name is serviceAccount:<serviceAccountName>. Because the service account does not inherit privileges from the Everyone group, all privileges for a service account must be specified explicitly. For example, to send email notifications when a pipeline has a service account as an owner, the service account must have the execute privilege configured for the related email configuration.

To create a service account:

From the CloudBees navigation, select CloudBees CD/RO.
From the CloudBees CD/RO main menu, navigate to Administration Configurations Service accounts. The Service Accounts dashboard displays.
Select Add service account. The New Service Account dialog displays.
Enter the service account Name and an optional Description. The best practice is to choose a name that represents the connection, such as GitHub. Select OK to save the new account.
Continue configuring service account settings. Refer to Modify service account attributes.

Modify service account attributes

Select the option menu to continue configuring the service account.

Modify service account name and description by selecting Details.
Select DSL Export to download the service account in a DSL file.
Modify associated properties and property sheets by selecting Properties. For more information, refer to Configure properties or property sheets.
Configure authentication credentials by selecting Access tokens.
Specify explicit permissions for service account by selecting Access Control.
Remove the service account by selecting Delete.

Configure a webhook trigger

You can configure a webhook trigger from the Triggers page or at the time you run an object. Once the trigger is configured, it is armed and ready for the specified event.

To configure a webhook trigger:

Create the trigger. There are two options:
- Option 1: From the CloudBees CD/RO main menu, select DevOps Essentials Triggers. Select Add trigger at the top right of the screen.
- Option 2: Navigate to the object on which you want to set the trigger, select Run, and then select Triggers. The object’s trigger list displays. Select Add + to add a new trigger or select Edit to edit an existing trigger.

Enter the following information:

Field name

Description

Trigger Name

A user-defined name for this trigger object.

Project

Name of project to be associated with the trigger object.

Description

Details about the trigger object.

Object

Select one of the following an object types: Release, Pipeline, Procedure, or Source code synchronization.

Object Name

Select the name of the release, pipeline, procedure, or source code synchronization.

Plugin

Select the corresponding plugin for your SCM provider:

EC-GitHub
GitLab
EC-Bitbucket
Bitbucket-DataCenter

The corresponding plugin must be installed in your CloudBees CD/RO instance for it to appear in the Plugin list.

For more information on installing a plugin, refer to Install CloudBees CD/RO plugins.

Trigger Type

Select Webhook.

Credential type

(GitHub and GitLab triggers only)

Use Secret token: A token which is used when creating the webhook in the source repository.
Use credential reference: A unique Credential Project and Credential Name used when creating the webhook in the source repository.

Repositories

A newline-separated list of repositories in the form organizationName/repositoryName or username/repositoryName. Examples: myorg/testrepo, myorg/testrepo1, `myorg/testrepo2.

Include Branches

A comma-separated list of branch names or patterns. Incoming events are discarded if they do not relate to one of the specified branches. Leave empty to process events for all branches except ones specified in the Exclude Branches parameter.

Exclude Branches

A comma-separated list of branch names or patterns. Incoming events are discarded when they relate to one of the specified branches. Leave empty to process events for all branches or the ones specified in the Include Branches parameter.

Process Push Events

Select this to run the trigger when the new commit appears in one of the monitored branches.

Process Pull Request Events

Select this to run the trigger when the pull request event occurs. Provide a list of comma-separated values. Run the trigger when one of the following actions has occurred: opened, edited, closed_merged, closed_discarded, assigned, unassigned, review_requested, review_request_removed, ready_for_review, labeled, unlabeled, synchronize, locked, unlocked, reopened.

Process Commit Status Events

(GitHub triggers, only) Select this to run the trigger when the commit status has been changed in one of the specified branches. Provide a comma-separated list of status names from the following: pending, success, failure, error.

Run Schedule even if another instance is running

Select as appropriate for your needs.

Quiet Time Minutes

The number of minutes check-in-activity must be quiescent before launching the object.

Select Next. The Select Service Account dialog displays.
Select a previously-created service account.
Select Next. A summary of run-time details for the object displays.
Select OK. The Webhook Trigger Successfully Created dialog displays.
To create the webhook automatically in the repository, select Use the plugin procedure to automatically set up this webhook.
1. Select the configuration to use:
  - Use a pre-configured repository configuration from the Configuration dropdown list.
  - Create a new configuration. Refer to Create a plugin configuration.
  - Supply credentials manually.
2. Select whether to Bypass SSL Validation. If selected, the repository API does not check the SSL endpoint when sending an event payload.
If creating the repository webhook explicitly, note the secret URL on this page: you use it when you Create a repository webhook.
Select OK to finish.

Create a repository webhook

Once you have set up the service account and configured a webhook trigger, you must create a repository webhook in the SCM.

You must configure the webhook in your source code repository and you must have write privileges for the repository. Before you start, ensure that you have the CloudBees CD/RO webhook endpoint that you created configuring a webhook trigger.

Go to the settings page of your repository or organization.
Follow the steps for your SCM provider:

Create a plugin configuration

Once you have created a repository webhook, you must create a plugin configuration.

For more information, refer to:

For GitHub configurations, refer to Create GitHub plugin configurations.
For GitLab configurations, refer to Create GitLab plugin configurations.
For Bitbucket configurations, refer to Create Bitbucket plugin configurations.
For Bitbucket Data Center configurations, refer to Create Bitbucket Data Center plugin configurations.