GitLab Package Registry Parameter

Pick a package version from a GitLab Package Registry when you start a build — Maven, npm, generic, and other package types via the Packages API.

Pipeline symbol: gitLabPackage

Screenshots

Configure the parameter

Point the job at a GitLab project, set the package name, and verify access with Test connection.

Build with Parameters

Versions load on demand when you open the build form; choose a version and run the job.

Why this plugin

Lists versions via GitLab Packages API (/projects/:id/packages), not a Docker registry or OCI/ORAS API.
Targets a specific package name (Maven path, npm scope, generic name, …).
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
Image Tag Parameter	Container tags from a Docker Registry API. This plugin lists Package Registry versions.
Quay Tag Parameter	Quay container tags. This plugin is GitLab Packages.
ORAS Parameters	OCI / ORAS artifact refs. This plugin returns package version strings from GitLab.
GitLab Plugin	MRs, webhooks, SCM. This plugin is only a build-parameter dropdown.

Quick start

Add a Jenkins credential (Username with password or Secret text / PAT). Listing packages needs read_api.
In the job: This project is parameterized → Add Parameter → GitLab Package Registry Version.
Set Name, GitLab Repo URL, Package name; optionally pick credentials and click Test connection.
Open Build with Parameters, wait for the dropdown to load, select a version, build.

Pipeline example

Generate from Pipeline Syntax → Sample Step properties: Set job properties → parameterized job → GitLab Package Registry Version.

Required: name, repoUrl, packageName. Other fields are optional.

properties([
  parameters([
    gitLabPackage(
      name: 'PKG_VERSION',
      repoUrl: 'https://gitlab.example/group/project.git',
      packageName: 'com/example/nginx-module',
      credentialsId: 'gitlab_token',
      defaultVersion: 'none'
    )
  ])
])

Replace gitlab.example with your GitLab host.

More templates: examples/PipelineSyntax.gitLabPackage.groovy, examples/Jenkinsfile.packages.plugin

Requirements

Jenkins 2.541.3 or newer (see pom.xml)
Optional credentials as above (read_api for private projects)

Configuration fields

Field	Description
`name`	Required. Environment variable name (e.g. `PKG_VERSION`)
`repoUrl`	Required. Project URL (`http://` or `https://`)
`packageName`	Required. Package name in Package Registry (Maven path, npm scoped, generic, …)
`description`	Optional help text on the Build with Parameters page
`credentialsId`	Optional. Empty = public project; token needs `read_api`
`defaultVersion`	Optional preselected value; added to the list if missing
`exclude` / `regex`	Optional Java regex to drop / keep versions
`perPage`	Values per API page (1–100, default 50)
`maxPages`	Max pages to fetch (1–50, default 2)
`maxRows`	Max values in the dropdown (1–500, default 30)
`sortMode`	`NONE` / `ASC` / `DESC` / `*_SMART`
`connectTimeoutMs` / `readTimeoutMs`	HTTP timeouts for build-time fetch (Test connection uses defaults)

GitLab Packages API notes

List: GET /api/v4/projects/:id/packages?package_name=…&per_page=&page=&order_by=version&sort=desc
GitLab’s package_name filter is fuzzy; this plugin keeps only exact name matches
Test connection probes the project and /packages?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.