Git Bisect

Git bisect is a tool for running binary searches over a git repository. If you want to read more about git bisect, you can do it here.

This plugin helps with running git-bisect automatically in Jenkins.

• Table Of Contents
  • Pre-Requirements
  • How to use this plugin
    • Nightly Polling Jobs
    • Manual Bisections
• Example Configuration
  • Bisect Project
  • Tester Project
• Parameters
• Running in a pipeline

You need to:

• Be able to determine for each commit whether it's broken or not - in a single jenkins job
  • If your build is separated to two projects - build & test, you can use a pipeline and use that pipeline as a single build
• Use Git SCM or be able to run arbitrary git commands in the workspace

There are two modes for running the plugin:

This is useful for nightly build failures. The plugin can help you find the specific commit that broke the build since the last time it ran. To use it you an add a post-build action to your build. You will also need to configure the git branch specifier to use a parameter.

This is a more customizable variation of the plugin that allows you to run a long-running bisection process; 

It is meant to be used for cases where a bug was introduced sometime ago; You know how to test, and you know at least one good revision where the bug did not exist. This variation of the plugin is also aimed to fit long builds that might be unstable or to find bugs that reproduce in an inconsistent manner.

To set it up, you need to have 2 Projects, one is for testing the bug ("Tester Project") and the other is for running the bisection ("Bisect Project")

Bisect Project

1. GitSCM
   • Define it using the same git repository
   • Must not be a shallow copy
2. Job Type
   • Can be either FreeStyleProject or a Pipeline Project
   • Use gitbisect in Pipeline projects.
3. Parameterized Build
   • Any parameters defined will bubble down to the Tester Project

Tester Project

1. GitSCM
   • be able to checkout a revision using a parameter:
   
2. Job Type
   • Can be either FreeStyleProject or a Pipeline Project
3. Parameterized Build
   • Must support a revision parameter. The default name is 'REVISION'. It's configurable in the "Git Bisect" Build Step in the Bisect Project

Used to specify a known good commit where the thing you are testing was working properly. 

Used to specify a revision where you know the thing you are testing stopped working.

The project that is used to test each commit. If this project fails, the revision will be marked as "bad". If this project succeeds, the revision will be marked "good".

The parameter name used to pass the revision to the Tester Project. Defaults to "REVISION", other common usage might be "COMMIT" or "VERSION". 

This parameter is used to distinguish between two different bisections. If the bisection stopped it can be resumed based on this identifier.  

Note:  This is used as a file name inside the Jenkins controller. You can interfere with the decisions this job makes, or add revisions to ignore by editing this file. It can be found under the project directory in Jenkins, for example - 

/var/jenkins/jobs/PROJECT_NAME/SEARCH_IDENTIFIER_1

This parameter can be used if you have a flaky test or a flaky build system. The revision won't be defined as 'bad' until it had failed this number of times. (Defaults to 0)

This parameter can be used if you are looking for a flaky test. For example, you are looking for a commit that causes your build to fail 1 out of 5 times. So you want to increase this number accordingly. (Defaults to 1)

If this is unchecked, the test job will only run once every build. This gives you time to investigate between each run. (Defaults to true)

On some systems, git might not be defined in PATH or it's aliased to a different command. You can tell the job where to find it.

Running in a pipeline currently works, but it's harder to configure.

Make sure that before the gitbisect command is used, a "checkout" or "git" command is present to set the repository.

Report issues and enhancements in the Jenkins issue tracker. Use the git-bisect-plugin component in the JENKINS project.

Refer to our contribution guidelines.