Skip to content

GitLab

GitLab Package Registry administration (FREE SELF)

GitLab Packages allows organizations to use GitLab as a private repository for a variety of common package managers. Users are able to build and publish packages, which can be easily consumed as a dependency in downstream projects.

The Packages feature allows GitLab to act as a repository and 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

Enabling the Packages feature

NOTE: After the Packages feature is enabled, the repositories are available for all new projects by default. To enable it for existing projects, users explicitly do so in the project's settings.

To enable the Packages feature:

Omnibus GitLab installations

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

    gitlab_rails['packages_enabled'] = true

  2. Save the file and reconfigure GitLab for the changes to take effect.

Installations from source

  1. After the installation is complete, you configure the packages section in config/gitlab.yml. Set to true to enable it:

    packages:
  enabled: true

  2. Restart GitLab for the changes to take effect.

Helm Chart installations

  1. After the installation is complete, you configure the packages section in global.appConfig.packages. Set to true to enable it:

    packages:
  enabled: true

  2. Restart GitLab for the changes to take effect.

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.

Changing the storage path

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

Changing the local storage path

The packages for Omnibus GitLab installations are stored under /var/opt/gitlab/gitlab-rails/shared/packages/ and for source installations under shared/packages/ (relative to the Git home directory). To change the local storage path:

Omnibus GitLab installations

  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 for the changes to take effect.

Installations from source

  1. Edit the packages section in config/gitlab.yml:

    packages:
  enabled: true
  storage_path: shared/packages

  2. Save the file and restart GitLab for the changes to take effect.

Using object storage

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

Read more about using object storage with GitLab.

NOTE: We recommend using the consolidated object storage settings. The following instructions apply to the original configuration format.

Omnibus GitLab installations

  1. Edit /etc/gitlab/gitlab.rb and add the following lines (uncomment where necessary):

    gitlab_rails['packages_enabled'] = true
gitlab_rails['packages_object_store_enabled'] = true
gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
gitlab_rails['packages_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
gitlab_rails['packages_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true).
gitlab_rails['packages_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
gitlab_rails['packages_object_store_connection'] = {
  ##
  ## If the provider is AWS S3, uncomment the following
  ##
  #'provider' => 'AWS',
  #'region' => 'eu-west-1',
  #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
  #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
  ## If an IAM profile is being used with AWS, omit the aws_access_key_id and aws_secret_access_key and uncomment
  #'use_iam_profile' => true,
  ##
  ## If the provider is other than AWS (an S3-compatible one), uncomment the following
  ##
  #'host' => 's3.amazonaws.com',
  #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
  #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
  #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
}

  2. Save the file and reconfigure GitLab for the changes to take effect.

Installations from source

  1. Edit the packages section in config/gitlab.yml (uncomment where necessary):

    packages:
  enabled: true
  ##
  ## The location where build packages are stored (default: shared/packages).
  ##
  # storage_path: shared/packages
  object_store:
    enabled: false
    remote_directory: packages  # The bucket name.
    # direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
    # background_upload: true   # Temporary option to limit automatic upload (Default: true).
    # proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
    connection:
    ##
    ## If the provider is AWS S3, use the following:
    ##
      provider: AWS
      region: us-east-1
      aws_access_key_id: AWS_ACCESS_KEY_ID
      aws_secret_access_key: AWS_SECRET_ACCESS_KEY
      ##
      ## If the provider is other than AWS (an S3-compatible one), comment out the previous 4 lines and use the following instead:
      ##
      #  host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
      #  aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
      #  endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
      #  path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.

  2. Save the file and restart GitLab for the changes to take effect.

Migrating 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.

For Omnibus GitLab:

sudo gitlab-rake "gitlab:packages:migrate"

For installations from source:

RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:packages:migrate

You can optionally track progress and verify that all packages migrated successfully using the PostgreSQL console:

  • sudo gitlab-rails dbconsole for Omnibus GitLab instances.
  • sudo -u git -H psql -d gitlabhq_production for source-installed instances.

Verify objectstg below (where file_store = '2') has count of all packages:

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

Verify that there are no files on disk in the packages folder:

sudo find /var/opt/gitlab/gitlab-rails/shared/packages -type f | grep -v tmp | wc -l