{jenkins-plugin-info:pluginId=pretested-integration|jiraComponent=pretested-integration}

Developed by

Sponsored by members of the

 

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 and maintained by the Continuous Delivery Alliance members (earlier named Josra)

The plugin relies on the SCM plugin to establish the workspace and then takes over to do the integration in the local workspace of the job. Finally the job makes the decision whether to like and push the result or hate and discard it.

Features

Major version 3 incompatible with earlier version

Starting with version 3.0.0 we have changed the plugin to work as a Git Plugin extension, so you will find under Additional behaviors in your Git SCM configuration.
Earlier it was a build wrapper which was configured in the “Prepare an environment for this build”

The change was necessary in order to support the new Pipeline job types and requires you to migrate your job configuration.

Migration guide from 2.x to 3.x

Job DSL

If you’re using Job DSL to generate your jobs this is an easy fix. Just update your Job DSL script with the new syntax, which is show in the JobDSL example section below.

Manual created jobs

If you’re creating your jobs manually, you’ll need to manually reconfigure your jobs.

When updating the plugin your current configuration will not show so you need to know how your jobs was configured and make the analogue configuration as Git Plugin extension.

Example below in the pictures.

The names of the fields have not changed and the strategies remain unchanged as well.

Build wrapperGit 'Additonal behaviour'


Additional behaviours → “Use pretested integration” -> Configure Integration branch and repository

Who should upgrade and who should not

Plugin limitations

There is one requirement: You should only try to integrate changes from one repository pr. job.

So see this as a limitation, but it actually a design decision as we will never be able to guarantee an atomic integration of two DVCS repositories as one process.

Beside this the Pretested Integration plugin works with most known job types :

There can be more repositories in your job - only one under integration.

When you use Git SCM with more than 1 repository configured it is absolutely required that you ensure that the remote name is unique pr. repository as we only allow integration of 1 git repo per job. Call them by the saying repository name or simply just origin1, origin2 ...

For Pipeline you also need to make sure you only perform 1 integration in the course of the flow, you can have multiple checkouts, but only one of your repositories can have pretested integration happening, otherwise we cannot reliably determine which branch to delete upon the success of the job.

References

Support and contact

If you find issues or have questions please contact us using Github issues here https://github.com/Praqma/pretested-integration-plugin/issues

Comments and discussions on this page is not noticed.

Plugin configuration

Tips for matrix job configuration

When you use the Matrix Job type, the merge is performed for each child job in your matrix and even thought the Pretested Integration Plugin post-build step is added we make sure it is only executed once in the parent job. This ensures that we only attempt to remove the branch once during a Matrix build after all childs have completed and have completed successfully.

We assume that your integration process using Pretested Integration Plugin is serialized so only one of this kind of job pr. project is building at the time. Else you're not sure the child jobs are integrating and verifying the same changes.

Manual building

In general you are not able to use 'Build now' with a Pretested Integration Plugin job configuration. The Pretested Integration Plugin is first in action when a "workspace" is handed over from the Git Plugin it will when manually building 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:

Failed and ‘Nothing to do’ statuses when merging

The ‘Nothing to do’ build status is added to your build description in the following scenarios

Failed builds can happen if there is a merge conflict which cannot be solved by a merge. In this scenario it is up to the user to merge the integration branch into their own development branch to fix their issues and deliver it again.

How Pretested Integration uses credentials

The Pretested Integration plugin will re-use the credentials for configured for the SCM that performed the merge. That means that if you've properly configured credentials in your git plugin, that is, credentials with write acces to your repository no further configuration is required. 

The recommended 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:

 

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.

Integration flow

Below is a simplified diagram of what Pretested Integration actually does once you've pushed your branch to integrate.
At the start, HEAD is at the integration branch, ready to merge in your branch.
In the end the merge result is verified and, if successful, pushed.

Help and error messages

We tried to gather some common errors and problems seen, together with some suggested solutions but not much have been contributed. See Help and error messages

Scripted job examples

The following are examples on how to script jobs using this plugin. Refer to either the pipeline script generator in Jenkins or Job DSL API viewer for all the details.

Job DSL

Example integrating the plugin repository itself using our recommended default configuration
job("pretested-integration-plugin_our-integration-job") {
  scm {
     git {
          remote {
              name("origin")
              url("git@github.com:Praqma/pretested-integration-plugin.git")
          }
          extensions {
              pretestedIntegration("SQUASHED","master","origin")
          }
      }
   }
  publishers {
    pretestedIntegrationPublisher()
  }
}

 Scriptet pipeline

 Example integrating the plugin repository itself using our recommended default configuration
node {
    checkout([$class: 'GitSCM', branches: [[name: '*/ready/**']], doGenerateSubmoduleConfigurations: false, extensions: [pretestedIntegration(gitIntegrationStrategy: squash(), integrationBranch: 'master', repoName: 'origin')], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'pipCredentials', url: 'your.repo.com.git']]])
    pretestedIntegrationPublisher()
        echo "Ohoy we've got success!"
}

Declarative pipeline

Example integrating the plugin repository itself using our recommended default configuration
pipeline {
   agent any
   stages {
       stage("checkout") {
           steps {
               checkout([$class: 'GitSCM', branches: [[name: '*/ready/**']], doGenerateSubmoduleConfigurations: false, extensions: [pretestedIntegration(gitIntegrationStrategy: accumulated(), integrationBranch: 'master', repoName: 'origin')], submoduleCfg: [], userRemoteConfigs: [[url: '%URL']]])
           }
       }
       stage("publish") {
           steps {
               pretestedIntegrationPublisher()
           }
       }
   }
}

Multibranch Pipeline Project

When configuring the plugin with multibranch projects the configuration is a little different. When you create your Multibranch Project you do not put the Pretested Integration extension in the SCM configuration. The workflow is a littel different here, instead you need to configure the pipeline to ignore default checkout and perform the checkout in a step. Like so:

pipeline {
   agent any
   options { skipDefaultCheckout() }
   stages {
       stage("checkout") {
           steps {
		checkout([$class: 'GitSCM', branches: [[name: '*/ready/**']], doGenerateSubmoduleConfigurations: false, extensions: [[$class: 'CleanBeforeCheckout'], pretestedIntegration(gitIntegrationStrategy: squash(), integrationBranch: 'master', repoName: 'origin')], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'github', url: 'https://github.com/praqma-test/pretested-integration-plugin-test-repo.git']]])
           }
       }
       stage("publish") {
           steps {
               pretestedIntegrationPublisher()
           }
       }
   }
}

Issues

See Github issues for current backlog and know issues.

Changes

Version 3.0.0 incl. betas - Not backwards compatible!

The overall changes in 3.0.0 all have to do with making the plugin pipeline compatible. No changes to the behaviour of the plugin are in this new release.

Version 2.4.1

Version 2.4.0

Version 2.3.4

Version 2.3.3

Version 2.3.2

Version 2.3.1

Version 2.3.0

Version 2.2.3

Version 2.2.1

Version 2.2.0

Version 2.1.2

Version 2.1.1

Version 2.1.0

Version 2.0

Version 1.1

Version 1.0