Configuring triggers

8 minute readExtensibility

Event-based triggers support continuous integration (CI) models by automatically running pipelines, procedures, and releases based on external events. Trigger support in CloudBees CD/RO allows you to integrate with external tools such as source control management (SCM) systems. For example, you can configure a Git repository to automatically trigger a release upon code check-in.

Once configured, you can view all triggers in the system on the Triggers page. From the CloudBees CD/RO main menu, select DevOps Essentials  Triggers.

To locate a trigger in the list, you can use the search field or filter by project, object, or tag.

As of v10.8, webhook triggers configured and scheduled before v10.1 have been deleted. Polling 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

    • Source code synchronization run

      A service account is required for webhook triggers.
  • Polling triggers: An internal trigger is periodically sent to an external Git 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

    • Source code synchronization run

      Polling triggers are 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:

  • For each event trigger:

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

    2. Create a repository webhook: If not automatically configured when the trigger was created, explicitly configure the corresponding webhook in the GitHub or Bitbucket repository.

Creating a service account

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.

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

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:

  1. From the CloudBees navigation, select CloudBees CD/RO.

  2. From the CloudBees CD/RO main menu, navigate to Administration  Configurations  Service accounts. The Service Accounts dashboard displays.

  3. Select Add service account. The New Service Account dialog displays.

  4. 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.

  5. Continue configuring service account settings. Refer to : Modifying service account attributes.

Modifying service account attributes

Select the three-dots three-dots 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 Configuring CloudBees CD/RO 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.

Configuring 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:

  1. 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.

  2. 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 EC-GitHub or EC-Bitbucket corresponding to the SCM tool you use for source control.

    Trigger Type

    Select Webhook.

    Credential type

    • Use Secret token (GitHub triggers, only) 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.

  3. Select Next. The Select Service Account dialog displays.

  4. Select a previously-created service account.

  5. Select Next. A summary of run-time details for the object displays.

  6. Select OK. The Webhook Trigger Successfully Created dialog displays.

  7. 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 Creating 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.

  8. If creating the repository webhook explicitly, note the secret URL on this page: you use it when you Creating a repository webhook.

  9. Select OK to finish.

Creating a repository webhook

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

Creating a repository webhook in 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 Configuring a webhook trigger.

  1. Go to the settings page of your repository or organization.

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

    github webhook 1
    Figure 1. GitHub webhook configuration
  3. Enter these values:

    • Payload URL: The webhook endpoint you generated when configuring 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?

  4. Select Active and then select Add webhook.

  5. Confirm the repository webhook is correctly configured.

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

Creating a repository webhook in Bitbucket

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

  1. Go to the settings page of your repository.

  2. Select Webhooks, then Add Webhook.

    Configuring a webhook in Bitbucket
    Figure 2. Bitbucket webhook configuration
  3. Enter these values:

    • Title: The title of this webhook.

    • Payload URL: The webhook endpoint you generated when configuring a webhook trigger above.

    • Status: Select Active.

    • Triggers: Select Push.

  4. Select Save.

  5. Confirm the repository webhook is correctly configured.

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

Creating a repository configuration

Polling triggers

The Git plugin allows you to 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.

Polling triggers are supported for Git only.

Enabling the PollingTriggers system schedule

The polling schedule is managed by the PollingTriggers scheduler, located in the Electric Cloud project. You must enable the PollingTriggers system schedule to check Git repository polling triggers.

In CloudBees CD/RO 10.1, the ECSCM-SentryMonitor scheduler was replaced by the PollingTriggers scheduler. If upgrading from CloudBees CD/RO 10.0 or earlier to 10.1 or later, there is no automatic migration path. You must enable the PollingTriggers system schedule, remove the old triggers, and manually create new triggers. For more information, refer to Schedule and trigger changes in CloudBees CD/RO 10.1.

To enable the PollingTriggers system schedule:

  1. Navigate to DevOps Essentials  Platform Home page.

  2. From the Projects tab, select Electric Cloud.

  3. Select the Schedules tab and enable PollingTriggers.

Adding a polling trigger

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

To add and configure a polling trigger:

  1. 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.

  2. Enter the following information:

    Field name Description

    Trigger Name

    User-defined name for this trigger object.

    Plugin

    Select EC-Git.

    Trigger Type

    Select Polling.

    Configuration Name

    (required)

    Git repository URL

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

    Monitor

    Specifies what to monitor: 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.

  3. Select Next. A summary of run-time details for the object displays.

  4. Select OK.

API access

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

Deleting a trigger

You can delete triggers in the system on the Triggers page.

To delete a trigger:

  1. From the CloudBees CD/RO main menu, select DevOps Essentials  Triggers.

  2. Select the three vertical dots menu for the trigger you want to delete, and then select Delete. A confirmation dialog box displays.

  3. Select Delete.

To delete multiple triggers:

  1. From the CloudBees CD/RO main menu, select DevOps Essentials  Triggers.

  2. Select the triggers you want to delete, and then select Delete triggers. A confirmation dialog box displays.

  3. Select Delete.