{jenkins-plugin-info:git-parameter}

Adds ability to choose branches, tags or revisions from git repository configured in project.


Plugin Info

This plugin allows you to assign git branch, tag, pull request or revision number as parameter in your  builds.

Important!
There is no need to set up anything special in plugin settings.
This plugin will read GIT SCM configuration from your projects.
This plugin used directly the Git Plugin and Git Client Plugin.

Basic configuration

Project configuration

Build with Parameters form

Example pipeline script

Important! version 0.9.4 or later

Branch type - Basic usage

// Using git without checkout 
pipeline {
  agent any
  parameters {
    gitParameter branchFilter: 'origin/(.*)', defaultValue: 'master', name: 'BRANCH', type: 'PT_BRANCH'
  }
  stages {
    stage('Example') {
      steps {
        git branch: "${params.BRANCH}", url: 'https://github.com/jenkinsci/git-parameter-plugin.git'
      }
    }
  }
}
properties([
    parameters([
        gitParameter(branch: '',
                     branchFilter: 'origin/(.*)',
                     defaultValue: 'master',
                     description: '',
                     name: 'BRANCH',
                     quickFilterEnabled: false,
                     selectedValue: 'NONE',
                     sortMode: 'NONE',
                     tagFilter: '*',
                     type: 'PT_BRANCH')
    ])
])
node {
    git branch: "${params.BRANCH}", url: 'https://github.com/jenkinsci/git-parameter-plugin.git'
}


Important settings:

Parameter type

Important: If you need use other type (other then branch) parameter, you must use git within checkout 

Tag type

// Using git within checkout 
pipeline {
    agent any
    parameters {
        gitParameter name: 'TAG', 
                     type: 'PT_TAG',
                     defaultValue: 'master'
    }
    stages {
        stage('Example') {
            steps {
                checkout([$class: 'GitSCM', 
                          branches: [[name: "${params.TAG}"]], 
                          doGenerateSubmoduleConfigurations: false, 
                          extensions: [], 
                          gitTool: 'Default', 
                          submoduleCfg: [], 
                          userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-parameter-plugin.git']]
                        ])
            }
        }
    }
}

Branch Tag type

pipeline {
    agent any
    parameters {
        gitParameter name: 'BRANCH_TAG', 
                     type: 'PT_BRANCH_TAG',
                     defaultValue: 'master'
    }
    stages {
        stage('Example') {
            steps {
                checkout([$class: 'GitSCM', 
                          branches: [[name: "${params.BRANCH_TAG}"]], 
                          doGenerateSubmoduleConfigurations: false, 
                          extensions: [], 
                          gitTool: 'Default', 
                          submoduleCfg: [], 
                          userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-parameter-plugin.git']]
                        ])
            }
        }
    }
}

Revision type

pipeline {
    agent any
    parameters {
        gitParameter name: 'REVISION', 
                     type: 'PT_REVISION',
                     defaultValue: 'master'
    }
    stages {
        stage('Example') {
            steps {
                checkout([$class: 'GitSCM', 
                          branches: [[name: "${params.REVISION}"]], 
                          doGenerateSubmoduleConfigurations: false, 
                          extensions: [], 
                          gitTool: 'Default', 
                          submoduleCfg: [], 
                          userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-parameter-plugin.git']]
                        ])
            }
        }
    }
}

Pull Requst type

pipeline {
    agent any
    parameters {
        gitParameter name: 'PULL_REQUESTS', 
                     type: 'PT_PULL_REQUEST',
                     defaultValue: '1',
                     sortMode: 'DESCENDING_SMART'
    }
    stages {
        stage('Example') {
            steps {
                checkout([$class: 'GitSCM', 
                branches: [[name: "pr/${params.PULL_REQUESTS}/head"]], 
                doGenerateSubmoduleConfigurations: false, 
                extensions: [], 
                gitTool: 'Default', 
                submoduleCfg: [], 
                userRemoteConfigs: [[refspec: '+refs/pull/*:refs/remotes/origin/pr/*', url: 'https://github.com/jenkinsci/git-parameter-plugin.git']]])
            }
        }
    }
}

Options:

Parameter Type

type: 'PT_TAG' or 'PT_BRANCH' or 'PT_BRANCH_TAG' or 'PT_REVISION' or 'PT_PULL_REQUEST'

Explains about PT_TAG or PT_BRANCH or PT_BRANCH_TAG:

Plugin using git ls-remote command to get remote tags or branches, this solution was implemented in .  This has been done for performance reasons. The plugin does not have to featch the repository before getting information


In code plugin useing  getRemoteReferences from GitClient, look implementation in CliGitAPIImpl 


package org.jenkinsci.plugins.gitclient
//...


public interface GitClient {
//...
	Map<String, ObjectId> getRemoteReferences(String remoteRepoUrl, String pattern, boolean headsOnly, boolean tagsOnly) throws GitException, InterruptedException;
//...
}


Branch

branch


Branch Filter

branchFilter


Tag Filter

tagFilter


Sort Mode

sortMode: 'NONE' or 'ASCENDING_SMART' or 'DESCENDING_SMART' or 'ASCENDING' or 'DESCENDING'


You can select the following sorting options for tags/revision/branches/branches_or_tags/pull requests

For the smart variants the compare treats a sequence of digits as a single character. Contributed by Graeme Hill.

Default Value

defaultValue

In release 0.9.9 or later good to set a default value, because this value is using in the initial build (in Pipeline).
Default value is returned when some error occurred on getting data.

Selected Value

selectedValue: 'NONE' or 'TOP' or 'DEFAULT'


Use repository

useRepository


Remember: You don't set a git repository into the plugin, this plugin using git repositories which are defined in project in SCM section!

If in the task are defined multiple repositories, this option specifies which the repository is taken into account on getting data.
If the option is not defined, is taken a first defined repository.
This option is a regular expression, which is compared to the 'Repository URL'.

You can define the multiple SCM for few way, you can use Multiple SCMs Plugin, specified many 'Repository URL' in one SCM  or define them in pipeline.

Consider an example based on two repositories:


pipeline {
    agent any
    parameters {
        gitParameter branchFilter: 'origin.*/(.*)', defaultValue: 'master', name: 'BRANCH_A', type: 'PT_BRANCH', useRepository: '.*exampleA.git'
        gitParameter branchFilter: 'origin.*/(.*)', defaultValue: 'master', name: 'BRANCH_B', type: 'PT_BRANCH', useRepository: '.*exampleB.git'
        
    }
    stages {
        stage('Example') {
            steps {
                git branch: "${params.BRANCH_A}", url: 'https://github.com/klimas7/exampleA.git'
                git branch: "${params.BRANCH_B}", url: 'https://github.com/klimas7/exampleB.git'
            }
        }
    }
}

After initial run you get 

Example when 'Use repository' is not set:

pipeline {
    agent any
    parameters {
        gitParameter branchFilter: 'origin.*/(.*)', defaultValue: 'master', name: 'BRANCH', type: 'PT_BRANCH'
    }
    stages {
        stage('Example') {
            steps {
                git url: 'https://github.com/klimas7/exampleA.git'
                git url: 'https://github.com/klimas7/exampleB.git'
            }
        }
    }
}

 After initial run you get 

Quick Filter

quickFilterEnabled


List Size

listSize


Global configuration

Release 0.9.9 or later


Error handling

Release 0.9.9 or later

If an error occurred while retrieving data, the default value is returned.
Additional information is provided below, along with the cause of the error.

Examples:

This error will occurred when repository is not configured or 'Use repository' option no match with any repository.

This error will occurred when repository not exists or URL is wrong.

This error will occurred when is no ssh command on Jenkins master.

Releases schedule

?

Changelog

17/06/2019 Version 0.9.11

16/02/2019 Version 0.9.9

09/10/2018 Version 0.9.6

17/09/2018 Version 0.9.5

16/08/2018 Version 0.9.4

20/06/2018 Version 0.9.3

16/04/2018 Version 0.9.2

18/02/2018 Version 0.9.1

02/11/2017 Version 0.9.0

04/09/2017 Version 0.8.1

02/06/2017 Version 0.8.0

23/01/2017 Version 0.7.2

11/27/2016 Version 0.7.1

09/12/2016 Version 0.7.0

08/06/2016 Version 0.6.2

07/19/2016 Version 0.6.1

07/06/2016 Version 0.6.0

05/03/2016 Version 0.5.1

04/02/2016 Version 0.5.0

1. User interface

2. Refactor/fix/feature

01/16/2015 Version 0.4.0

05/14/14 Version 0.3.2

User visible changes are:

Changes relevant to developer

02/21/12 Version 0.2

11/01/11 Version 0.1



Adds ability to choose branches, tags or revisions from git repositories configured in project.