ElectricSentry

7 minute readAutomation

ElectricSentry is the CloudBees CD/RO engine for continuous integration, integrating with Source Control Management (SCM) systems. ElectricSentry is installed automatically with CloudBees CD/RO and is contained in a CloudBees CD/RO plugin named ECSCM. When ElectricSentry detects a new or modified source file check-in, it launches a user-defined procedure to build and test the latest version of source files. Using a few simple properties, the entire process is controlled by the user who determines when ElectricSentry is active and which projects and branches are monitored and built.

While you can interact with ElectricSentry directly, you may want to use the Continuous Integration Dashboard, the front-end user interface for ElectricSentry, which provides a visual display of your builds, and automates the configuration process for your branch, project, or procedure so you can start using continuous integration schedules quickly.

This Help topic describes using ElectricSentry directly, and not the Continuous Integration Dashboard, which has its own Help topic for dashboard use. To get started with the "dashboard", select the Home > Continuous Integration tab.

How ElectricSentry works

ElectricSentry finds procedures the user wants to monitor by scanning for a special type of CloudBees CD/RO schedule. From the schedule, ElectricSentry retrieves the name of the procedure to run, along with values to use as actual parameters when the procedure runs.

ElectricSentry can run at a regular interval you determine. When it runs, ElectricSentry scans all CloudBees CD/RO projects, looking for schedules configured for use with ElectricSentry. When it finds one, ElectricSentry checks to see if there is already a job running based on that schedule and will not start a second job for the same schedule until the previous job completes.

Next, ElectricSentry queries the SCM system to see if new check-ins have occurred since the last attempted build. If the most recent check-in is different from the last attempted build, ElectricSentry then checks a "quiet period" by comparing the current time to the check-in time. If the user-configured time interval has elapsed since the most recent check-in, ElectricSentry runs the procedure to start a new job.

Finally, ElectricSentry deletes previous runs of itself, so only the most recent run appears in the jobs list. If using the Continuous Integration Dashboard, this is slightly different—you will see the previous 10 builds that ran.

Configuring ElectricSentry

ElectricSentry does not require any specific configuration, but it does allow fine tuning for some key settings. To change any setting, you must be logged into CloudBees CD/RO and then navigate to the CloudBees project.

Quiet time

When setting up a continuous integration system, it is common to require an inactivity period before starting a build. This time period allows developers to make multiple, coordinated check-ins to ensure a build does not start with only some of the changes—assuming all changes are checked-in within the specified inactivity time period. This time period also gives developers an opportunity to "back-out" a change if they realize it is not correct.

With ElectricSentry, the inactivity time period can be configured globally for all projects or individually for a single project. The global setup is stored in the ECSCM-SentryMonitor schedule in the CloudBees project, using a property named ElectricSentrySettings/QuietTimeMinutes. You can set this property to the number of minutes you prefer for the quiet time prior to starting a build. If you remove this property, ElectricSentry will use a five-minute default time.

Resource

The ECSCM plugin contains a procedure named ElectricSentry. This procedure has a parameter named `sentryResource ` that determines where ElectricSentry will run. The parameter defaults to a resource named local , which is created by the CloudBees CD/RO installer. The local resource is configured to run on the machine named localhost , which refers to the machine where the CloudBees CD/RO server is running.

You may need to change the resource where ElectricSentry runs, if for example, the server machine is not configured to run your SCM tools. You can change this configuration by modifying the ECSCM-SentryMonitor schedule to specify a different resource in the `sentryResource ` parameter.

To do this:

  1. Go to the Projects page.

  2. Select the CloudBees project name to go to the Project Details page.

  3. Click the Schedules subtab.

  4. Select the ECSCM-SentryMonitor schedule.

  5. Change the sentryResource field to the name of the resource (or the resource pool name) where you want ElectricSentry to run.

  6. Click OK to save your new information.

Polling frequency

ElectricSentry is set to look for new check-ins every five minutes. If you want ElectricSentry to check more or less often, open the ECSCM-SentryMonitor schedule in the CloudBees project. Change the number of minutes to speed up or slow down the ElectricSentry polling frequency entry.

Time-of-day and day-of-week

The initial setting allows ElectricSentry to run between 7 am and 11 pm every day of the week, but you can change this time period to monitor check-ins at different hours. The time period should cover the most likely hours developers would be checking-in changes, then frees the resources (after the last job started by ElectricSentry finishes) to run overnight builds. You can modify the ECSCM-SentryMonitor schedule to change the hours or days ElectricSentry monitors check-ins.

Configuring a build for continuous integration

You can control which projects and branches ElectricSentry monitors for continuous integration by creating a schedule that runs a procedure and by adding ElectricSentry settings. These tasks are made easier using the Continuous Integration Dashboard.

Source Control Management (SCM) configurations

CloudBees CD/RO bundles and supports a number of source control types. After creating a source control configuration, your entry appears in the table on the Source Control Configurations page. To view this page, select Administration  Source Control.

Click the Create Configuration link to configure your source control system.
CloudBees has tested numerous SCM versions and where possible, all SCM integrations were created in a generic manner to avoid SCM release-specific differences. In most cases, CloudBees supports any version of Perforce, ClearCase, Subversion, AccuRev, CM Synergy, Borland’s StarTeam, and many others.

Select the Administration > Plugins tab to go to the Plugin Manager page to the current list of available SCM plugins. If you do not see the SCM you need, it may be available in the Plugin Catalog—select the View Catalog tab.

Create a procedure

Navigate to your project and create a procedure that checks out sources from your SCM system and then runs your build process. we recommend having the procedure take a ”branch name” parameter, then use this single procedure to build multiple branches of the same project.

Create a schedule

In your project, create a schedule that calls the procedure and specifies parameters to call the procedure. On the Project Details web page, select the Schedules tab and click the CI Configuration link to go to the New CI Configuration page. Enter a name for the new schedule and choose the SCM Configuration you want to use. For more information on this page, click the Help link in the upper-right corner of the screen. If you set up your procedure with a parameter for a branch, create one schedule for each branch you want to monitor.

Optional —running ElectricSentry on multiple resources

ElectricSentry normally runs as a single procedure executing queries against all SCM systems configured by ElectricSentry "trigger schedules." Because all queries are executed in a single step, these queries are executed by the same CloudBees CD/RO resource. This process works very well for many companies, but for some large enterprise companies this process is not adequate.

You can benefit from using ElectricSentry on multiple resources if any of the following items apply to your organization:

  • Connectivity—No one single resource has access to all SCM systems in your organization.

  • Security/Authentication —Specific resources may contain Authentication tickets required for access to certain parts of your SCM depots, and no single resource contains all of these tickets.

  • Scalability—You may need too many trigger schedules to monitor in a single execution interval, which can cause unnecessarily long execution times for ElectricSentry jobs.

  • Scheduling—ElectricSentry is most useful during the work day when developers are adding new code check-ins. At night, it is common to redeploy resources to do nightly builds. If ElectricSentry runs on a central resource that serves development teams in multiple time zones, there is no way to schedule independent Sentry operation for different time zones.

Overview

The solution to all of these issues [above] is to run multiple ElectricSentry instances concurrently.

  • Each Sentry instance can choose its own resource and its own operation schedule.

  • Each instance can be restricted to monitoring schedules for one or more CloudBees CD/RO projects.

  • Also, you can create a global instance to monitor all projects not monitored by a restricted instance.

Each ElectricSentry instance is implemented by reusing the ElectricSentry procedure in the ECSCM plugin. This procedure has two parameters, sentryResource and projectList, that allow you to specify the configuration for different instances.

Each instance will have its own copy of the SentryMonitor schedule—one for each resource where you want ElectricSentry to run.

The default configuration has no projects specified in the "projectList" parameter—this is called the global instance. The global instance monitors all projects not explicitly monitored by any other instance. If a global instance is your only instance, it will monitor all projects.

Configuring ElectricSentry to use multiple resources

When CloudBees CD/RO is installed, it creates a project called CloudBees that contains ElectricSentry’s Sentry Monitor schedules. By default, all steps will run on the resource named local and all projects will be monitored. To use multiple resources, you need to create new schedules in the CloudBees project, creating new ElectricSentry instances.

  1. Navigate to the CloudBees project and select it.

  2. Select the Schedules tab.

  3. Disable the schedule named ECSCM-SentryMonitor.

  4. Click the Copy link next to the ECSCM-SentryMonitor schedule— repeat for each new ElectricSentry instance you want to create.

  5. Re-enable the schedule named ECSCM-SentryMonitor.

  6. Navigate to one of the new schedules you created and select it to edit it—change the name from ECSCM-SentryMonitor copy n to something more meaningful, for example, "ECSCM-SentryMonitor for ABC team."

  7. In the Parameters section: projectList box—enter the project names you need to monitor—one project name per line. sentryResource box—enter the resource or pool name where you want this ElectricSentry instance to run.

  8. In the Frequency section: Adjust the "time of day" and "days of the week" settings to schedule this ElectricSentry instance to run.

  9. In the Advanced section, click the Enabled check box.

  10. Click the Save button.

  11. Repeat steps 6-10 for each new schedule that you create.

  12. In the Advanced section, click the Enabled check box. Click the Save button.

If you are setting up ElectricSentry to run in a different time zone, make sure you set the Time Zone field for the location where ElectricSentry will run.