Jenkins : Polling for changes

There are three methods that are relevant when Hudson is determining if there has been a change in the SCM:

  • public boolean supportsPolling()
  • public boolean requiresWorkspaceForPolling()
  • before Hudson 1.346: public boolean pollChanges(AbstractProject, Launcher, FilePath, TaskListener)
  • after Hudson 1.346: public PollingResult compareRemoteRevisionWith(AbstractProject, Launcher, FilePath, TaskListener, SCMRevisionState)
  • after Hudson 1.346: public SCMRevisionState calcRevisionsFromBuild(AbstractBuild, Launcher, TaskListener)

supportsPolling

This methods determines if the SCM plugin can be used for polling. Default method returns true.

requiresWorkspaceForPolling

This method should return true if the SCM requires a workspace for polling. What to return depends on the SCM that the plugin is using. For instance the ClearCase plugin requires that a build has been performed before it can poll for changes, whereas Team Foundation Server does not require a workspace to poll for changes. Default method returns true.

pollChanges (<1.346)

This method does the actual polling and should return true or false if there are any changes in the repository. The polling should be as quick as possible and does not need to output any other result than a boolean.

To determine the date to get changes from, use the AbstractProject.getLastBuild().getTimestamp() to get a Calendar object.

compareRemoteRevisionWith (>=1.346)

This method does the actual polling and returns a PollingResult. The change attribute of the PollingResult the significance of the changes deteced by this poll.

Value of 'change' (enum)

Description

PollingResult.NO_CHANGES

The were no changes since the last built.

PollingResult.INSIGNIFICANT

There were changes since last build, but they are not significant enough to warrant a new build, e.g. because some SCMs allow certain commits to be marked as excluded.

PollingResult.SIGNIFICANT

There are changes between states that warrant a new build.

PollingResult.INCOMPARABLE

The state as of baseline is so different from the current state that they are incomparable, for example, the workspace and the remote repository point to two unrelated repositories because the configuration has changed. This forces Jenkins to schedule a build right away. PollingResult.BUILD_NOW is basically an alias to {{PollingResult.}}INCOMPARABLE

calcRevisionsFromBuild (>=1.346)

Calculate the state of the workspace of the given build. The returned object is then fed into compareRemoteRevisionWith as the baseline SCMRevisionState to determine if the build is necessary, and is added to the build as an Action for later retrieval.