Writing an SCM Plugin

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Introduction

This document is a how-to on writing an SCM plugin for Jenkins. It is based on my experiences writing the TFS Plugin.

Prerequisites

For the rest of this how-to, it is assumed that the plugin development environment has been set up according to the Plugin tutorial.

Determining configuration options

First you should investigate on what configuration parameters that the SCM should have and should not have. It is advisable to keep the number of configuration points as low as possible to be in line with the easiness as the rest of Jenkins. For the Team Foundation Server I have determined that the following configuration parameters are needed:

  • the server name/url

  • the name of the project

  • if the server is secured, credentials such as username, password and domain

  • cleanCopy, if the workspace should be emptied before every build

  • the name of the workspace

The global configuration page should configure:

  • a command line tool, that is used instead of TFS library. The command line tool field will have validation logic to make sure that Hudson can find it.

Determining change log elements

Secondly, you should determine what data you would like to store in the change log for each build. The change log should contain information such as the author, date, message. Team Foundation Server change sets contains the following information:

  • Revision

  • Author

  • Date and time

  • Comment

  • A list of files

  • Action (added, deleted, changed)

  • File name

  • Version

Sections

  • The SCM plugin architecture section covers how to create the base classes and jelly files that an SCM implementation requires.

  • The Remoting section covers how the plugin should interact with the SCM server, either through a command line tool or an API, so it can be distributed to agents.

  • The Polling for changes section covers how a plugin can poll for changes and what methods that should be implemented.

  • The Checking out files section covers what a plugin needs to do when checking out files at the beginning of a build.

  • The Change log section covers how the change log for a build should be handled, so it can be displayed in the Changes page.

  • The Repository browser section covers how to support web based repository browsers in a plugin.

  • The Tag support section covers how to tag a build using tag/label features in the SCM.

External examples

  • simple-scm-plugin: A simple SCM skeleton plugin you can build with Gradle or Maven. No real functionality, just a minimalistic skeleton.

References