Git Parameter

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 default value because initial build must get this information
• Using git should be set a branchFilter as *origin/(.\*)* (origin is a remote server name)

Parameter type

• PT_TAG
• PT_BRANCH
• PT_BRANCH_TAG
• PT_REVISION
• PT_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:

• https://github.com/klimas7/exampleA.git
• https://github.com/klimas7/exampleB.git

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:

1. This error occur when the repository is not configured or 'Use repository' option not match with any repository.
2. This error occur when the repository is not exists or URL is wrong.
3. This error occur when there are no ssh command on Jenkins master.

Contribute

• You may checkout/clone this project and build it by simply calling mvn clean install in the root of the checkout. Test your changes by going to your Jenkins-CI site and import the generated target/git-parameter.hpi by going to your base URL + jenkins/pluginManager/advanced. There you find an option to upload a plugin.

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/git-parameter#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 the legacy CHANGELOG