September 10, 2014

Continuous Integration with New Perforce Server Plugin for Jenkins

Continuous Delivery
Integration

Overview of Jenkins and Perforce Server Plugins

Jenkins is a very popular Continuous Integration (CI) tool that is used by many Perforce customers to automate and manage their builds. Jenkins is an open architecture and has hundreds of different plugins written for it by the community. The most prominent plugins are the source code management (SCM) providers that extract projects from a Perforce Server or Git.

There has long been a Perforce Server plugin around written by the community called “Perforce Plugin”. Recently we created our own plugin, “P4 Plugin for Jenkins” to support new features like shelving that is needed, for example, by Perforce Swarm.

P4 Plugin for Jenkins

The new P4 Plugin for Jenkins is written using P4Java, the 100% native Java interface to the Perforce Server. Using P4Java instead of wrapping the P4 CLI makes it much easier to create Jenkins slave configurations. Jenkins itself will take care of copying the P4 Plugin for Jenkins to the slave. No pre-installation of the P4 executable to any slave is necessary.

The most important feature of the new plugin is the ability to run builds both on Perforce streams and shelves. Perforce users who adopted streams needed to perform automated builds using Jenkins. Adding the ability to build from a shelf makes it very easy for Perforce Swarm to run pre-commit builds.

Installation

P4 Plugin for Jenkins can be installed like any other Jenkins plugin from the ‘Manage Jenkins’ -> ‘Manage Plugins’ menu. Simply follow the instructions here. Alternatively you can download the source code from the Perforce Workshop and manually build and install the plugin yourself.

Usage

Credentials

To use P4 Plugin for Jenkins, you need to first define the user credentials. These credentials are then used when defining the build parameters to specify the connection to Perforce Server.

Use Credentials

You can either connect using a password or a valid Perforce ticket.

Use Credentials

Build configuration

Once the credentials are defined you can use these to configure a build.

Use Credentials

Choose Perforce Software as your Source Code Management and your Perforce credentials to define P4PORT and P4USER. There are different options for your workspace definition:

Use Credentials

You can create a manual workspace, use an existing workspace or create a workspace automatically based on a template or stream spec. More details can be found in the documentation.

Populate options

You can define different options on how to populate your workspace.

Use Credentials

If your build process leaves the workspace in a clean state you can simply specify “sync” to update your workspace for incremental builds. Otherwise instruct the plugin to clean any generated files before syncing, or clear out the complete workspace and start over again (which can take some time if your project is large – and therefore is not recommended).

Auto cleanup has two additional options:

Use Credentials

Uncheck DELETE if you want to keep generated artifacts (such as object files) in the workspace for incremental builds. Uncheck REPLACE if your build process modifies versioned files as part of the build and you want to preserve these changes between builds.

Connecting Swarm

You can connect Swarm to Jenkins for pre-commit reviews. To do this you need to define a project in Swarm first and tick the automated tests checkbox:

Use Credentials

In the text panel add the link to your Jenkins instance with a path to the corresponding Jenkins job for your project and a subpath of “review/build”. The arguments are “status”, “change” and “review” as well as “pass” and “fail” URLs, all of which will be filled in by Swarm.

As a result, whenever a review is posted for this project, a build will be initiated and the result posted in Swarm as a green (success) or red (failure) icon that links to the corresponding Jenkins page.

Use Credentials

With these tools in place you can build a whole workflow around code reviews, ensuring that your reviewers look at a valid change that builds and passes the tests.

Extending to Git

Perforce supports Git through Git Fusion, so it is possible to use the Perforce Server as your single source of truth. This simplifies your build configuration since you only need to maintain one SCM configuration in Jenkins. It is also possible to initiate code reviews in Swarm from Git (including automatic builds); check out the documentation here for details.

So grab P4 Plugin for Jenkins and get started.

Happy hacking!