This section describes the basic architecture of an SCM plugin.
This page was out-of-date, but is being updated! The pollChanges API has been deprecated in favor of a new API that can track multiple changes coming in while a build is waiting in the quiet period. You can find more info in the SCM javadoc hudson.scm.SCM and see Subversion Plugin for a sample implementation https://svn.jenkins-ci.org/trunk/hudson/plugins/subversion.
The SCM class
All SCM plugins are subclasses of hudson.scm.SCM. This class has a few methods that an SCM implementation will want to override:
- public PollingResult compareRemoteRevisionWith(Job<?,?> project, Launcher launcher, FilePath workspace, TaskListener listener, SCMRevisionState baseline) throws IOException, InterruptedException
- public void checkout(Run<?,?> build, Launcher launcher, FilePath workspace, TaskListener listener, File changelogFile, SCMRevisionState baseline) throws IOException, InterruptedException
- public SCMRevisionState calcRevisionsFromBuild(Run<?,?> build, FilePath workspace, Launcher launcher, TaskListener listener) throws IOException, InterruptedException
createChangeLogParser which is abstract and has to be overridden:
- public abstract ChangeLogParser createChangeLogParser()
The basic means of interaction between the plugin and the rest of hudson are the
checkout methods, which are used, respectively, to poll the SCM for changes and to check out updated files. The
createChangeLogParser method is supposed to return something that can parse an XML file with change set information.
Create the configuration options as normal fields, by adding fields to the SCM class they will be persisted when Hudson is stopped and started. If you have a field that should not be persisted to XML it should be marked as
The following sections describe the methods of the SCM class in more detail.
Create a constructor that takes non-transient fields, and add the annotation
@DataBoundConstructor to it. Using the annotation helps the Stapler class to find which constructor that should be used when automatically copying values from a web form to a class.
compareRemoteRevisionWith method is expected to return if there has been any changes on the SCM repository or not in the form of a
PollingResult object. It is up to the plug-in developer to create a new
SCMRevisionState from the remote repository, and compare this with the baseline
SCMRevisionState to determine whether there are changes (which lets Jenkins know it should checkout and build or not). It is also up to the developer to extend the
SCMRevisionState class with details specific to the SCM system, and to provide a way to compare objects of this class. This example shows what a very basic
compareRemoteRevisionsWith might look like if
SCMRevisionState is extended by class
MyCustomRevisionState which has method
isNewerThan for comparing two
checkout method is expected to check out modified files into the project workspace. As a checkout is generally the first step for a build, the
build object is made available. Also, the former SCMRevisionState,
baseline is made available.
calcRevisionsFromBuild is designed to generate the
SCMRevisionState, there is also the option of having
checkout generate this state and having
null. This is particularly useful if the generation of the
SCMRevisionState overlaps with the checkout process and you want to optimize performance.
calcRevisionsFromBuild to return null, and add your SCMRevisionState to
Since you have access to your build, you can even add build parameters to your build during checkout. This is useful if you want to pass some information (like a version number) acquired during the polling process to a build job.
This method is called after
checkout and generates and returns a SCMRevisionState, presumably based on the state of the workspace. Alternatively, this method can be set to return
null and checkout can add SCMRevisionState to the build as an action.
checkout method should, besides checking out the modified files, write a
changelog.xml file that contains the changes for a certain build. The
changelog.xml file is specific for each SCM implementation, and the
createChangeLogParser returns a parser that can parse the file and return a
ChangeLogSet. See below section for more information.
Returns the ScmDescriptor<?> for the SCM object. The ScmDescriptor is used to create new instances of the SCM. For more information see next section.
The Descriptor class
The relationship of Descriptor and SCM (the describable) is akin to class and object. What this means is that the descriptor is used to create instances of the describable. Usually the Descriptor is an internal class in the SCM class named
DescriptorImpl. The Descriptor should also contain the global configuration options as fields, just like the SCM class contains the configurations options for a job. The
@Extension annotation tells Jenkins to register the descriptor.
Methods that will be overriden
public String getDisplayName()
public boolean configure(StaplerRequest req) throws FormException
Returns the name of the SCM, this is the name that will show up next to CVS and Subversion when configuring a job.
The method is invoked when the global configuration page is submitted. In the method the data in the web form should be copied to the Descriptor's fields. To persist the fields to the global configuration XML file, the
save() method must be called. Data is defined in the
The jelly files for the Descriptor go into the
src/main/resources/hudson/plugins/$plugin-name/$PluginScm/ folder where
$plugin-name is the name of your plugin and
$PluginScm is the plugin's SCM class implementation. For the Team Foundation Server plugin this path is
/src/main/resources/hudson/plugins/tfs/TfsScm. The jelly files are the configuration view for the SCM class.
Contains global configuration that is displayed in system configuration page. Typical configuration parameters that is going to be used by all Hudson jobs, for example the path to the SCM tool.
tfs.tfExecutable will be populated with the string from
DescriptorImpl.getTfExecutable(). The method should return "tfs" by default.
tfs.tfsExecutable will also validate the entered tool path through
checkUrl. When the user has entered a path (and moves the focus away from field) Hudson will call
DescriptorImpl.doExectuableCheck to validate that the path can be found.
Contains configuration for one Hudson job. Typical configuration parameters that used in a job, such as server URL, etc. The fields in the jelly file should correspond to the fields in the SCM class.
As with the Descriptor the web form fields are populate from the SCM object through properties, the value for "tfs.server" is retrieved from the
tfs.project field is mandatory and will display an error text below it if the field is empty. The error text is defined by the
checkUrl attribute, and can be also used to validate numbers. The
checkUrl can be used for more advanced validating such as testing the server if it exists and needs credentials.
HTML Help files
For each entry in a jelly file that has a
help attribute Hudson will display a help icon to the right. When the icon is clicked the named HTML page will be inlined just below the entry field. The HTML page must reside in the