Section | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||
|
Table of Contents | ||
---|---|---|
|
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.
...
Build wrapper | Git 'Additonal behaviour' |
---|---|
Additional behaviours → “Use pretested integration” -> Configure Integration branch and repository
...
- 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
...
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:
And a publisher to delete on success:
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 | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
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 | ||||
---|---|---|---|---|
| ||||
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() } } } } |
...
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 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 | ||||||
---|---|---|---|---|---|---|
| ||||||
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: 'githubpipCredentials', url: 'https://github.com/praqma-test/pretested-integration-plugin-test-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!
...