Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
borderfalse
Column
width50%
Wiki Markup
{jenkins-plugin-info:pluginId=pretested-integration|jiraComponent=pretested-integration}
Column
width20%

Developed by

Sponsored by members of the

Column
width30%
 

Table of Contents
maxLevel3

Introduction

Excerpt

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)

...

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.

...

Manually created jobs

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

...

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

    
Build wrapperGit 'Additonal behaviour'

Image Added

Image Added


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

 

[INSERT IMAGE OF THIS]

 

Who should upgrade and who should not

...

  • For more background information and discussions 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: 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.

Changes in Jenkinsfile (for users of pipeline with Jenkinsfile)

The default behaviour of the pretested integration plugin is to run `jenkinsfile` that is located on the branch that is being integrated, so if branch `ready/457-uses-gradle-instead-of-maven` if being processed by the plugin, it is the file located on that branch that will be executed, not the one on the integration branch.

Conflicts

There can be cases where users have edited the jenkins file, and that can result in a merge conflict. The pretested integration plugin does not handle merge conflict in a Jenkinsfile, so to update the Jenkins file, another strategy must be applied.

1. Change the Jenkins file and merge it to the integration branch (`master`) locally in a separate commit
2. Push it to remote master
3. Delivering the other changes on a ready branch, which also has the updates to the jenkinsfile

If `master` (in the case above) is also being build by a job, that can result in a failing build if the new Jenkinsfile is using resources not yet available. This will however be fixed the moment the `ready`-branch have been integrated.

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

...

  • If last build failed, thus the integration failed, for a non-persistent error (disk problem, licensing problem ...) rebuilding the job can succeed if no other build have been executed since last time.

  • 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.

 Failed and ‘Nothing to do’ statuses when merging

...

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.

...

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

 

The simple Git workflow

Get your repository up to date:

...

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

  • 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.

This is how the default configuration should look like:

Image Added

And a publisher to delete on success:

Image Added

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.

...

Code Block
java
java
job("pretested-integration-plugin_our-integration-job") {
  scm {
     git {
          remote {
              name("origin")
              url("git@github.comhttps:Praqma/pretested-integration-plugin.//your.repo.com.git")              
          }
          branch("*/ready/**")
          extensions {
              pretestedIntegration("SQUASHED","master","origin")
          }
      }
   }
  publishers {
    pretestedIntegrationPublisher()
  }
}

...

 Scripted pipeline

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

Declarative pipeline

Example integrating the plugin repository itself using our recommended default configuration
Code Block
java
java
pipeline {
   agent any
   stages {
       stage("checkout") {
           steps {
               checkout([$class: 'GitSCM', branches: [[name: '*/ready/**']], doGenerateSubmoduleConfigurations: false, extensions: [[$class: 'CleanBeforeCheckout'], pretestedIntegration(gitIntegrationStrategy: accumulatedsquash(), integrationBranch: 'master', repoName: 'origin')], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'pipCredentials', url: '%URLhttps://your.repo.com.git']]])
           }
       }
       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 as part of the branch source. Instead you need to configure the pipeline to ignore default checkout and perform the checkout in a step, where you do add the pretestedIntegration extension. Like so:

Code Block
languagegroovy
titleMultibranch Declarative Example
linenumberstrue
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: 'pipCredentials', url: 'https://your.repo.com.git']]])
           }
       }
       stage("publish") {
           steps {
               pretestedIntegrationPublisher()
           }
       }
   }
}

Usage scenarios

As a developer using CLI

See this link:  Link to usage with the CLI

As a developer using Eclipse

Follwo the guide Using Eclipse

Issues

See Github issues for current backlog and know issues.

Changes

Version 3.1.0

  • Fixed an issue that caused build to continue, even though integration failed in the SCM step.
  • Added option to shorten the merge commit message for the Accumulated commit strategy. 
  • Minor correction to output in console.

Version 3.0.1

  • Identical to 3.0.0 we just changed version number to not include git SHA as it breaks compatibility with Jenkins Docker install-plugins.sh script and is not fully semver compliant.

Version 3.0.0 incl. betas - Not backwards compatible!

...