Registry proxy (optional)

You probably don't need this

glpkg works fully without a proxy: every package comes from a GitLab group (--group) or from the ecosystem's own registry (--external). Read this page only if your organization runs a registry proxy and tells you to use it.

What it is

A registry proxy is an HTTP endpoint that serves a GitLab group's packages on your behalf, in place of GitLab's own registry endpoint. Your organization provides the URL. You might use one to give machines without a GitLab token access to internal packages, or to route package traffic through a single endpoint.

With a proxy there is a third package source, next to gitlab and external:

Source	Meaning	How to choose it
proxy	The configured proxy, for a GitLab group	--group <group> --source proxy

Supported ecosystems

npm and generic packages only. PyPI, Go and NuGet packages cannot use the proxy; use --group (GitLab) or --external for them.

Set up

glpkg config proxy:set <url>
glpkg config proxy:status            # URL and enabled state
glpkg config proxy:status --check    # also test that the proxy responds

Command	Description
glpkg config proxy:set <url>	Set the proxy URL
glpkg config proxy:enable	Mark the proxy as enabled (requires a URL)
glpkg config proxy:disable	Mark the proxy as disabled
glpkg config proxy:status [--check]	Show the URL and enabled state; --check tests that the proxy responds

The settings are stored in ~/.config/glpkg/proxy-config.json (url and enabled).

proxy:enable does not switch any package to the proxy. A package uses the proxy only when you choose it with --source proxy or it is recorded that way in glpkg.lock.json.

Install through the proxy

--source proxy goes together with --group:

# npm
glpkg install @your-org/utils --group your-org --source proxy

# generic
glpkg install @your-org/[email protected] --generic --group your-org --source proxy -o ./vendor

# record without installing
glpkg lock set @your-org/a @your-org/b --group your-org --source proxy

For npm, glpkg points the package's scope at the proxy URL in its temporary npm config instead of the GitLab group registry.

--source accepts gitlab (the default) or proxy, and requires --group.

In glpkg.lock.json

The package is recorded with source: proxy and its group (path and numeric ID). A whole-project glpkg install then uses the proxy for it without any flag, as long as a proxy URL is configured on that machine.

To switch a package back to GitLab, record it again:

glpkg lock set @your-org/utils --group your-org

Errors

Message	Fix
Source proxy requires a proxy URL. Set one with: glpkg config proxy:set <url>	Set the URL. Also shown by a whole-project install when the lock records a proxy source but this machine has no proxy URL.
--source proxy requires a proxy URL. Set one with: glpkg config proxy:set <url>	Same, for generic installs
The proxy source is npm-only; use --group <group> (gitlab) or --external for <ecosystem>	Shown by install --pypi/--go/--nuget. Use --group or --external.
The proxy source is npm/generic-only	Shown by lock set --pypi/--go/--nuget. Use --group or --external.
--source requires --group <group>	Add --group
--source applies to --group only (not --external)	Remove --source or use --group
Invalid --source '<value>' (expected gitlab or proxy)	Use gitlab or proxy