Pretested Integration Plugin

Introduction

The Pretested Integration Plugin offers a branchy approach to pretested integration (also known as pre-tested commits), which upholds the invariant; that for a specific branch, known as the integration branch, all commits have been verified.
This plugin is developed by Praqma and sponsored by Atmel - It's maintained in the scope of Joint Open Source Roadmap Alliance (JOSRA).

The plugin rely on the SCM plugin to establish the workspace and then takes over to do the integration. Last the job make the decision whether to like and commit the result or hate and discard it. To get a comprehensive introduction to how the plugin relies on the SCM plugin please read the blog post at the JOSRA: Pretested Integration Plugin.

References

• For more background information and a discussion on the different merge strategies available please read the blog post at the JOSRA: Pretested Integration Plugin.
• For a Paper on how to implement at complete flow of automated continuous delivery - including pretested integration read the white paper: CoDe:U Git Flow - a Continuous Delivery Approach (PDF) or blog post: An Automated Git Branching Flow
• To follow the roadmap for this plugin see the Trello board.
• Developer oriented documentation is found in the repository readme.

Support and contact

Please send us an email on support@praqma.net if you have a request or question regarding the plugin.

If you find an error or have feature requests, use the Jenkins issue tracker.

Comments and discussions on this page might not always be noticed.

The recommend setup and git workflow

Here is a simple git workflow where you can work on a features branch, and when ready push to a ready-branch. The Pretested Integration plugin, if configured as described will then pick up your changes, merge them and verify them. If verified they are integrated on the integration branch. The ready branch are automatically deleted if integration was successful.

Recommendation:

• Use one repository in your job configuration - the integration repository. Avoid using several repositories - model your dependencies in other (better) ways.
• Use master as integration branch (destination).
• Use ready/** as specifier for ready branches - only branches matching this expression will trigger the build

The simple plugin configuration

To configure the plugin to pick up ready branches, verify them and deliver them to the integration branch use the following configuration:

Now you only need to configure your definition of done - the verification. How should the job verify the commits? It can be compile and measure compiler warning, build and run unit tests and check that coverage do not drop.

The simple Git workflow

Get your repository up to date:

git fetch --prune

git checkout master

git pull origin master

Create a feature- or development- or... branch

git checkout -b feat_1337-improved-login-screen

...work, stage and commit changes.

Then push changes to a ready branch, which is basically just a branch following a naming conventions for branches matching ready/**.

git push origin feat_1337-improved-login-screen:ready/feat_1337-improved-login-screen

The change will be picked up by the plugin if configured as shown in next section.

• You can then delete your local branch and continue with a new feature or development branch.
• You are free to push to any branch name not matching the ready branch naming convention without triggering an integration build.

Help and error messages

*NOT YET DONE - work in progress* (We have gathered some common errors and problems seen, together with some suggested solutions - Help and error messages)

Manual building

In general you are not able to use 'Build now' with a pretested integration job configuration. The Pretested Integration Plugin is first in action when a "workspace" is handed over from the Git Plugin (or Multiple SCMs Plugin), and typically those will serve the last build revision again. If that succeeded last time, the revision is deleted after the integration and retrying the integration fails.

Some successful and failing cases using manual builds are:

• If last build failed, thus the integration failed, for a non-persistent error (slave problem, licensing problem ...) rebuilding the job can succeed if no other build have been executed since last time.
• Rebuilding after a successful build will typically fail, if the build is rebuilding the same revision again. That revision doesn't not exist as it is deleted after a successful integration in last build.
• If you have done a job configuration change, and need to trigger the job to test the configuration you typically need to make a commit that triggers the job. Push a commit to a ready branch, or wait for one.
• There is a work around, that often enables you to build manually: Make the job parametrized with BRANCH_TO_BUILD and use that variable in the 'branch specifier'. Make BRANCH_TO_BUILD have the default ready-branch specifier, so if not given the job works as if there were no parameters. If you now build the job manually, you can type in a branch to build.

You are welcome to contribute with ideas and use-cases for manual build and support for it on the roadmap in the Trello board.

Using multiple repository configurations

The plugin is designed to work on only one repository - as in you can only integrate on one repository pr. Jenkins job, but your Jenkins job can be used with multiple repositories for eg. checking out several repositories into a given folder structure you need for building the software. Though we consider this a work-around for not having the right dependency management, it can be done. You have the choice of using the Git Plugin or the Multiple SCMs Plugin, but need to follow the configuration examples below.

Requirements if using multiple repository jobs

Every repository should be explicitly and uniquely named* in the git repository configuration under 'Advanced'. Then use this as integration repository in the prested integration configuration

Example with multiple git repositories

Basically the same setup needs to be applied if using the Multiple SCMs plugin, but you can benefit from additional behaviours like checking each git repository out to a subdirectory if needed. Still every git repository must be explicitly and uniquely named.

Acknowledgement

Code contributions were initially made by Computer Science students at University of Copenhagen as part of a study project

Ronni Elken Lindsgaard
Alexander Winther Uldall
Esben Skaarup
Andreas Frisch

Issues

Changes

Version 2.2.0

• JENKINS-25445 Support for checkout to subdirectories.
• JENKINS-24754, JENKINS-25544, JENKINS-25546 Support for using the Multiple SCMs Plugin.
• JENKINS-25886 Requiring explicitly named remotes if using Multiple SCMs Plugin
• JENKINS-25960 Fixed problem with resolving correct git scm and remotes, if using Multiple SCMs Plugin
• JENKINS-25959 Post-build step, publish the changes to remote, is blocked if trying to delete 'master'-branch (using it as ready-branch)
• JENKINS-25618 Changed squashed merge strategy commit message, to include all the squashed commits individual messages.
• JENKINS-25873 Changed to using custom version number for this plugin, by adding git SHAs

Version 2.1.2:

• Implemented logging tracing

Version 2.1.1:

• Bugfix for running on slaves (JENKINS-24844)

Version 2.1.0:

• Protected master branch (Plugin tries to delete origin/master JENKINS-24286)
• Re-using last commit message in accumulated strategy (Improve commit message JENKINS-24285)
• Removed the "origin" from the description (JENKINS-24284)
• When squashing commits, now using author from tip of branch (JENKINS-24443)
• Additional tests added as well

Version 2.0:

• Git integration is now supported

Version 1.1:

• Dependency of Mercurial plugin set to 1.39 due to previous failure to trigger on merge commits
• Removed UI elements that should not have been there

Version 1.0:

• Release of the first stable versionI