GitLab Repository Refs Parameter

Pick a branch or tag from a GitLab project when you start a build — via GitLab’s Repository API, without git ls-remote on the controller.

Pipeline symbol: gitLabRefs

Screenshots

Configure the parameter

Point the job at a GitLab project, choose which refs to list (All / tags / branches), and verify access with Test connection.

Build with Parameters

Refs load on demand when you open the build form; choose a branch or tag and run the job.

Why this plugin

Lists refs via GitLab HTTP Repository API (branches / tags endpoints), not a local Git checkout.
refKind limits the list to all refs, tags only, or branches only.
Works with self-hosted GitLab and usual Jenkins credentials.
Lazy loading on Build with Parameters; Test connection on the config screen.

Not a duplicate of…

Plugin	Difference
Git Parameter / similar “pick a Git ref” plugins	Often use `git ls-remote` or another SCM view. This plugin calls GitLab’s project APIs with a project URL + token.
GitLab Plugin	MRs, webhooks, SCM. This plugin is only a build-parameter dropdown.
Image Tag / Quay / ORAS parameter plugins	Container or OCI artifacts. This plugin lists source-control refs (branches/tags).

Quick start

Add a Jenkins credential (Username with password or Secret text / PAT). Scopes: read_repository and/or read_api.
In the job: This project is parameterized → Add Parameter → GitLab Repository Ref.
Set Name, GitLab Repo URL, References (refKind); optionally pick credentials and click Test connection.
Open Build with Parameters, wait for the dropdown to load, select a ref, build.

Pipeline example

Generate from Pipeline Syntax → Sample Step properties: Set job properties → parameterized job → GitLab Repository Ref.

Required: name, repoUrl. Use refKind for ALL / TAGS / BRANCHES (default ALL).

properties([
  parameters([
    gitLabRefs(
      name: 'GIT_REF',
      repoUrl: 'https://gitlab.example/group/project.git',
      credentialsId: 'gitlab_token',
      refKind: 'ALL',
      defaultVersion: 'none'
    )
  ])
])

Replace gitlab.example with your GitLab host.

More templates: examples/PipelineSyntax.gitLabRefs.groovy, examples/Jenkinsfile.refs.plugin

Requirements

Jenkins 2.541.3 or newer (see pom.xml)
Optional credentials as above

Configuration fields

Field	Description
`name`	Required. Environment variable name (e.g. `GIT_REF`)
`repoUrl`	Required. Project URL (`http://` or `https://`)
`description`	Optional help text on the Build with Parameters page
`credentialsId`	Optional. Empty = public project
`refKind`	Optional: `ALL` (default) / `TAGS` / `BRANCHES`
`defaultVersion`	Optional preselected value; added to the list if missing
`exclude` / `regex`	Optional Java regex to drop / keep refs
`perPage` / `maxPages` / `maxRows`	Pagination and dropdown limit
`sortMode`	`NONE` / `ASC` / `DESC` / `*_SMART`
`connectTimeoutMs` / `readTimeoutMs`	HTTP timeouts for build-time fetch (Test connection uses defaults)

GitLab API notes

Branches: GET /api/v4/projects/:id/repository/branches
Tags: GET /api/v4/projects/:id/repository/tags
Test connection probes the project and /repository/branches?per_page=1

Security notes

Build-page AJAX sends only the parameter name (values come from the job’s stored definition).
For self-signed or internal GitLab, add your company CA to the Jenkins controller JDK truststore (do not disable TLS verification).
Loopback, link-local, and cloud metadata addresses are blocked. Private RFC1918 hosts are allowed for typical self-hosted GitLab.

License

MIT — see LICENSE.

Reporting security issues

See SECURITY.md.