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!
Works with version 0.9.4 or greater
Branch type - Basic usage
- Declarative Pipeline
// 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'
}
}
}
}
- Scripted Pipeline
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:
- It should be set a
defaultvalue because initial build must get this information - Using
gitshould be set abranchFilteras*origin/(.\*)*(origin is a remote server name)
Parameter type
PT_TAGPT_BRANCHPT_BRANCH_TAGPT_REVISIONPT_PULL_REQUEST
Important! If you need to 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 Request 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
Name using in pipeline
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 JENKINS-40232.
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
Name using in pipeline
branch
Branch Filter
Name using in pipeline
branchFilter
Tag Filter
Name using in pipeline
tagFilter
Sort Mode
Name using in pipeline
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
- none
- descending
- ascending
- ascending smart
- descending smart
For the smart variants the compare treats a sequence of digits as a single character. Contributed by Graeme Hill.
Default Value
Name using in pipeline
defaultValue
In release 0.9.9 or later it is good to set a default value, because this value is using the initial build (in Pipeline).
Default value is returned when some error occurred on getting data.
Selected Value
Name using in pipeline
selectedValue: 'NONE' or 'TOP' or 'DEFAULT'
Use repository
Name using in pipeline
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: Complex example
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: 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'
dir('dir-for-exampleB') {
git url: 'https://github.com/klimas7/exampleB.git'
}
}
}
}
}
After initial run you get
Quick Filter
quickFilterEnabled
List Size
listSize
Global configuration
Important!
Works with version 0.9.9 or greater
Error handling
Important!
Works with version 0.9.9 or greater
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 occur when the repository is not configured or 'Use repository' option not match with any repository.
- This error occur when the repository is not exists or URL is wrong.
- This error occur when there are no ssh command on Jenkins master.
Contribute
-
Visit https://jenkins.io/doc/developer/publishing/ for "information about developing Jenkins-Plugins"
-
You may checkout/clone this project and build it by simply calling
mvn clean installin the root of the checkout. Test your changes by going to your Jenkins-CI site and import the generatedtarget/git-parameter.hpiby going to your base URL +jenkins/pluginManager/advanced. There you find an option to upload a plugin. -
The Jenkins-CI of this plugin can be seen at DEV@cloud.
Pull Request Policy
If you want to add some changes for this plugin:
Add the issue in jenkins JIRA to the component git-parameter-plugin
Describe there why you need change the plugin.
TODO
-
Add a new method
listRemoteTags(URL)to git-client-plugin to use. Will speed up listing tags and avoids cloning/fetching the content. -
Fix the pending issues from
- Even though the GIT SCM module has the ability to provide "credentials" (SSH key) for the repository, the git-parameter plugin doesn't seem to use them. "Issue lukanus":lukanus#14
-
Allow translations by converting all html stuff to jelly
-
Add explanation when configuring the sort mode
-
Allow regular expressions when sorting.
-
Better testing. How to we test the configuration dialog? How do we test whether correct tags are listed when a user triggers a build?
Development history
This plugin was offered to the community by lukanus (Łukasz Miłkowski lukanus@uaznia.net) end of 2011. He was active till February 2012.
In May 2014 ngiger (Niklaus Giger niklaus.giger) decided to maintain this plugin and bring in the various improvements made by others.
March 2016 klimas7 (Boguslaw Klimas) he began to the care and maintenance of the plugin.. We will see ... :)
Changelog
For recent versions, see GitHub Releases
For versions 0.9.11 and older, see CHANGELOG.md