Event-based triggers

Event-based triggers provide the ability to automatically run pipelines, procedures, and releases based on external events, supporting continuous integration models. Trigger support in CloudBees CD/RO allows users to integrate with external tools such as source control management systems. For example, a Git repository can be configured to automatically trigger a release upon code check-in.

This page describes trigger configuration and operation as of CloudBees CD/RO v10.1. Triggers configured and scheduled prior to v10.1 continue to work, but they are not available from the UI to review or run.

CloudBees CD/RO supports these event-based triggers:

Webhook triggers: An inbound, asynchronous GitHub or BitBucket event that triggers an action. Webhook triggers support these actions:
- Pipeline run
- Release run
- Procedure run
Polling triggers: An internal trigger is periodically sent to an external GitHub repository to determine if an event such as a code check-in has happened. And, if so, an action is initiated. Polling triggers support these actions:
- Pipeline run
- Release run
- Procedure run
  
  Polling triggers supported for Git, only.

Webhook triggers

The GitHub and Bitbucket repositories send a post call to CloudBees CD/RO at a preconfigured endpoint, which processes the payload to run the target object.

In summary, here is what you need in order to trigger on webhooks:

One-time setup:
- Create a service account: CloudBees CD/RO account to broker webhook interactions.
For each event trigger:
1. Configure a webhook trigger: In the CloudBees CD/RO server, configure the the event trigger on the desired object.
2. Create a repository webhook: If not automatically configured when the trigger was created, explicitely configure the corresponding webhook in the GitHub or Bitbucket source code repository.

Configure a webhook trigger

You configure a webhook trigger at the time you run an object. Once configured, it is armed and ready to receive the webhook payload from GitHub.

Navigate to the object on which you want to set the trigger, and select Triggers from the green Run button dropdown list. The object`s trigger list displays.

Add a new trigger by selecting the Add + button or edit an existing trigger by selecting the Edit button. Enter the following information:

Field name

Description

Trigger Name

A user-defined name for this trigger object.

Plugin

Select EC-GitHub or EC-Bitbucket corresponding to the SCM tool you use for source control.

Trigger Type

This is automatically selected for you based on the SCM tool.

Secret

(GitHub triggers, only) A secret you create, which is used when creating the webhook in the source repository.

Repositories

A newline-separted 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 repositiory, 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 repository 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. The list of triggers displays for the runtime object.

Create a repository webhook

GitHub

The steps in this section take place in your GitHub source code repository—you must have write privileges on the repository. Before starting, make sure you have the CloudBees CD/RO webhook endpoint and the webhook secret, both created in Configure a webhook trigger.

To begin, go to the settings page of your repository or organization.

Select Webhooks, then Add Webhook. The webhook configuration page displays.

Figure 1. GitHub webhook configuration
Enter these values:
- Payload URL: The webhook endpoint you generated during Configure a webhook trigger.
- Content type: Select application/json.
- Secret: This is the secret used to validate the webhook payload from GitHub.
- Choose Which events you would like to trigger this webhook?
Select Active and click Add webhook.
Confirm the repository webhook is correctly configured.

GitHub sends an initial ping request to the registered payload URL. These are listed under Recent Deliveries.

Bitbucket

The steps in this section take place in your Bitbucket source code repository—you mush have write privileges on the repository. Before starting, make sure you have the CloudBees CD/RO webhook endpoint, created in Configure a webhook trigger above.

To begin, go to the settings page of your repository.

Select Webhooks, then Add Webhook.

Figure 2. Bitbucket webhook configuration

Enter these values:
- Title: The title of this webhook.
- Payload URL: The webhook endpoint you generated during Configure a webhook trigger above.
- Status: Select Active.
- Triggers: Select Push.
Select Save.

Confirm the repository webhook is correctly configured.

GitHub sends an initial ping request to the registered payload URL. These are listed under Recent Deliveries.

Create a repository configuration

For GitHub configurations, refer to GitHub—plugin configurations.
For Bitbucket configurations, refer to Bitbucket—plugin configurations.

Polling triggers

Configure CloudBees CD/RO to poll the specified Git source control repository for updates at a preconfigured schedule. If an update is detected, the runtime object is run. Once the trigger is configured, it is armed and ready to poll for the specified event.

Configure a polling trigger

Navigate to the object on which you want to set the trigger, and select Triggers from the green Run button dropdown list. The object`s trigger list displays.

Add a new trigger by selecting the Add + button or edit an existing trigger by selecting the Edit button. Enter the following information:

Field name

Description

Trigger Name

User-defined name for this trigger object.

Plugin

Select EC-Git.

Trigger Type

This is automatically selected as Polling for you.

Configuration Name

(required) * Use a pre-configured repository configuration from the Configuration Name dropdown list. * Create a new configuration. Refer to Create a repository configuration.

Git repository URL

(required) A repository URL, for example, git://server/repo.git, https://github.com/github/testrepo.git.

Monitor

Specifies what to monitored: Branch or Tags

Git branch name

The name of the Git branch to watch for changes, for example, main, dev.

Run Schedule even if another instance is running

Quiet Time Minutes

The number of minutes no check-in-activity is required before launching the procedure.

Select Next. A summary of run-time details for the object displays.
Select OK. The Triggers dialog displays showing current list of triggers.

Create a service account

Service accounts are for webhooks triggers, only.

A service account brokers all the webhook interactions between the GitHub repo and the pipeline webhook trigger. Its principle purpose is to hold the webhook session ID. A session associated with the service account is valid up to six months, by default, so it is an ideal way to manage a long-lasting webhook session.

You must have access rights to create a service account. Contact your CloudBees CD/RO site administrator for assistance.

You create a service account from CloudBees CD/RO.

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.
Click the New button: the New Service Account dialog displays.

Figure 3. Service account dialog
Enter the service account name in the Name field. Best practice is to choose a name that represents the connection, such as GitHub. Click OK to save the new account.

API access

These API resources are available to programatically create and manage event-based triggers:

To create and manage webhook service accounts, see Service accounts for webhooks.
To create and manage triggers, see Trigger.