GitLab package registry administration

Tier: Free, Premium, Ultimate Offering: Self-managed

To use GitLab as a private repository for a variety of common package managers, use the package registry. You can build and publish packages, which can be consumed as dependencies in downstream projects.

Supported formats

The package registry supports the following formats:

Package type GitLab version
Composer 13.2+
Conan 12.6+
Go 13.1+
Maven 11.3+
npm 11.7+
NuGet 12.8+
PyPI 12.10+
Generic packages 13.5+
Helm Charts 14.1+

Accepting contributions

The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This development documentation guides you through the process.

Format Status
Chef #36889
CocoaPods #36890
Conda #36891
CRAN #36892
Debian Draft: Merge request
Opkg #36894
P2 #36895
Puppet #36897
RPM #5932
RubyGems #803
SBT #36898
Terraform Draft: Merge request
Vagrant #36899

Rate limits

When downloading packages as dependencies in downstream projects, many requests are made through the Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you can define specific rate limits for the Packages API. For more details, see package registry rate limits.

Enable or disable the package registry

The package registry is enabled by default. To disable it:

Linux package (Omnibus)

  1. Edit /etc/gitlab/gitlab.rb: 

    # Change to true to enable packages - enabled by default if not defined
gitlab_rails['packages_enabled'] = false

  2. Save the file and reconfigure GitLab: 

    sudo gitlab-ctl reconfigure
Helm chart (Kubernetes)

  1. Export the Helm values: 

    helm get values gitlab > gitlab_values.yaml

  2. Edit gitlab_values.yaml: 

    global:
  appConfig:
    packages:
      enabled: false

  3. Save the file and apply the new values: 

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker

  1. Edit docker-compose.yml: 

    version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['packages_enabled'] = false

  2. Save the file and restart GitLab: 

    docker compose up -d
Self-compiled (source)

  1. Edit /home/git/gitlab/config/gitlab.yml: 

    production: &base
  packages:
    enabled: false

  2. Save the file and restart GitLab: 

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

Change the storage path

By default, the packages are stored locally, but you can change the default local location or even use object storage.

Change the local storage path

By default, the packages are stored in a local path, relative to the GitLab installation:

  • Linux package (Omnibus): /var/opt/gitlab/gitlab-rails/shared/packages/
  • Self-compiled (source): /home/git/gitlab/shared/packages/

To change the local storage path:

Linux package (Omnibus)

  1. Edit /etc/gitlab/gitlab.rb and add the following line: 

    gitlab_rails['packages_storage_path'] = "/mnt/packages"

  2. Save the file and reconfigure GitLab: 

    sudo gitlab-ctl reconfigure
Self-compiled (source)

  1. Edit /home/git/gitlab/config/gitlab.yml: 

    production: &base
  packages:
    enabled: true
    storage_path: /mnt/packages

  2. Save the file and restart GitLab: 

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

If you already had packages stored in the old storage path, move everything from the old to the new location to ensure existing packages stay accessible: 

mv /var/opt/gitlab/gitlab-rails/shared/packages/* /mnt/packages/

Docker and Kubernetes do not use local storage.

  • For the Helm chart (Kubernetes): Use object storage instead.
  • For Docker: The /var/opt/gitlab/ directory is already mounted in a directory on the host. There’s no need to change the local storage path inside the container.

Use object storage

Instead of relying on the local storage, you can use an object storage to store packages.

For more information, see how to use the consolidated object storage settings.

Migrate local packages to object storage

After configuring the object storage, use the following task to migrate existing packages from the local storage to the remote storage. The processing is done in a background worker and requires no downtime.

  1. Migrate the packages.

    Linux package (Omnibus)
    sudo gitlab-rake "gitlab:packages:migrate"
    Self-compiled (source)
    RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:packages:migrate

  2. Track the progress and verify that all packages migrated successfully using the PostgreSQL console.

    Linux package (Omnibus) 14.1 and earlier
    sudo gitlab-rails dbconsole
    Linux package (Omnibus) 14.2 and later
    sudo gitlab-rails dbconsole --database main
    Self-compiled (source)
    RAILS_ENV=production sudo -u git -H psql -d gitlabhq_production

  3. Verify that all packages migrated to object storage with the following SQL query. The number of objectstg should be the same as total: 

    gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM packages_package_files;

total | filesystem | objectstg
------+------------+-----------
 34   |          0 |        34

  4. Finally, verify that there are no files on disk in the packages directory:

    Linux package (Omnibus)
    sudo find /var/opt/gitlab/gitlab-rails/shared/packages -type f | grep -v tmp | wc -l
    Self-compiled (source)
    sudo -u git find /home/git/gitlab/shared/packages -type f | grep -v tmp | wc -l