1---
2stage: Package
3group: Package
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5---
6
7# GitLab Package Registry administration **(FREE SELF)**
8
9GitLab Packages allows organizations to use GitLab as a private repository
10for a variety of common package managers. Users are able to build and publish
11packages, which can be easily consumed as a dependency in downstream projects.
12
13The Packages feature allows GitLab to act as a repository for the following:
14
15The Package Registry supports the following formats:
16
17| Package type                                                      | GitLab version |
18|-------------------------------------------------------------------|----------------|
19| [Composer](../../user/packages/composer_repository/index.md)      | 13.2+          |
20| [Conan](../../user/packages/conan_repository/index.md)            | 12.6+          |
21| [Go](../../user/packages/go_proxy/index.md)                       | 13.1+          |
22| [Maven](../../user/packages/maven_repository/index.md)            | 11.3+          |
23| [npm](../../user/packages/npm_registry/index.md)                  | 11.7+          |
24| [NuGet](../../user/packages/nuget_repository/index.md)            | 12.8+          |
25| [PyPI](../../user/packages/pypi_repository/index.md)              | 12.10+         |
26| [Generic packages](../../user/packages/generic_packages/index.md) | 13.5+          |
27| [Helm Charts](../../user/packages/helm_repository/index.md)       | 14.1+          |
28
29## Accepting contributions
30
31The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md)
32guides you through the process.
33
34<!-- vale gitlab.Spelling = NO -->
35
36| Format | Status |
37| ------ | ------ |
38| Chef      | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) |
39| CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) |
40| Conda     | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) |
41| CRAN      | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) |
42| Debian    | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50438) |
43| Opkg      | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) |
44| P2        | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) |
45| Puppet    | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) |
46| RPM       | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) |
47| RubyGems  | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) |
48| SBT       | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) |
49| Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) |
50| Vagrant   | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) |
51
52<!-- vale gitlab.Spelling = YES -->
53
54## Enabling the Packages feature
55
56NOTE:
57After the Packages feature is enabled, the repositories are available
58for all new projects by default. To enable it for existing projects, users
59explicitly do so in the project's settings.
60
61To enable the Packages feature:
62
63**Omnibus GitLab installations**
64
651. Edit `/etc/gitlab/gitlab.rb` and add the following line:
66
67   ```ruby
68   gitlab_rails['packages_enabled'] = true
69   ```
70
711. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
72
73**Installations from source**
74
751. After the installation is complete, you configure the `packages`
76   section in `config/gitlab.yml`. Set to `true` to enable it:
77
78   ```yaml
79   packages:
80     enabled: true
81   ```
82
831. [Restart GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
84
85**Helm Chart installations**
86
871. After the installation is complete, you configure the `packages`
88   section in `global.appConfig.packages`. Set to `true` to enable it:
89
90   ```yaml
91   packages:
92     enabled: true
93   ```
94
951. [Restart GitLab](../restart_gitlab.md#helm-chart-installations) for the changes to take effect.
96
97## Rate limits
98
99When downloading packages as dependencies in downstream projects, many requests are made through the
100Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you
101can define specific rate limits for the Packages API. For more details, see [Package Registry Rate Limits](../../user/admin_area/settings/package_registry_rate_limits.md).
102
103## Changing the storage path
104
105By default, the packages are stored locally, but you can change the default
106local location or even use object storage.
107
108### Changing the local storage path
109
110The packages for Omnibus GitLab installations are stored under
111`/var/opt/gitlab/gitlab-rails/shared/packages/` and for source
112installations under `shared/packages/` (relative to the Git home directory).
113To change the local storage path:
114
115**Omnibus GitLab installations**
116
1171. Edit `/etc/gitlab/gitlab.rb` and add the following line:
118
119   ```ruby
120   gitlab_rails['packages_storage_path'] = "/mnt/packages"
121   ```
122
1231. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure)
124   for the changes to take effect.
125
126**Installations from source**
127
1281. Edit the `packages` section in `config/gitlab.yml`:
129
130   ```yaml
131   packages:
132     enabled: true
133     storage_path: shared/packages
134   ```
135
1361. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
137
138### Using object storage
139
140Instead of relying on the local storage, you can use an object storage to
141store packages.
142
143[Read more about using object storage with GitLab](../object_storage.md).
144
145NOTE:
146We recommend using the [consolidated object storage settings](../object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original configuration format.
147
148**Omnibus GitLab installations**
149
1501. Edit `/etc/gitlab/gitlab.rb` and add the following lines (uncomment where
151   necessary):
152
153   ```ruby
154   gitlab_rails['packages_enabled'] = true
155   gitlab_rails['packages_object_store_enabled'] = true
156   gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
157   gitlab_rails['packages_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
158   gitlab_rails['packages_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true).
159   gitlab_rails['packages_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
160   gitlab_rails['packages_object_store_connection'] = {
161     ##
162     ## If the provider is AWS S3, uncomment the following
163     ##
164     #'provider' => 'AWS',
165     #'region' => 'eu-west-1',
166     #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
167     #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
168     ## If an IAM profile is being used with AWS, omit the aws_access_key_id and aws_secret_access_key and uncomment
169     #'use_iam_profile' => true,
170     ##
171     ## If the provider is other than AWS (an S3-compatible one), uncomment the following
172     ##
173     #'host' => 's3.amazonaws.com',
174     #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
175     #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
176     #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
177   }
178   ```
179
1801. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure)
181   for the changes to take effect.
182
183**Installations from source**
184
1851. Edit the `packages` section in `config/gitlab.yml` (uncomment where necessary):
186
187   ```yaml
188   packages:
189     enabled: true
190     ##
191     ## The location where build packages are stored (default: shared/packages).
192     ##
193     # storage_path: shared/packages
194     object_store:
195       enabled: false
196       remote_directory: packages  # The bucket name.
197       # direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
198       # background_upload: true   # Temporary option to limit automatic upload (Default: true).
199       # proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
200       connection:
201       ##
202       ## If the provider is AWS S3, use the following:
203       ##
204         provider: AWS
205         region: us-east-1
206         aws_access_key_id: AWS_ACCESS_KEY_ID
207         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
208         ##
209         ## If the provider is other than AWS (an S3-compatible one), comment out the previous 4 lines and use the following instead:
210         ##
211         #  host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
212         #  aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
213         #  endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
214         #  path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
215   ```
216
2171. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
218
219### Migrating local packages to object storage
220
221After [configuring the object storage](#using-object-storage), use the following task to
222migrate existing packages from the local storage to the remote storage.
223The processing is done in a background worker and requires **no downtime**.
224
225For Omnibus GitLab:
226
227```shell
228sudo gitlab-rake "gitlab:packages:migrate"
229```
230
231For installations from source:
232
233```shell
234RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:packages:migrate
235```
236
237You can optionally track progress and verify that all packages migrated successfully using the
238[PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database):
239
240- `sudo gitlab-rails dbconsole` for Omnibus GitLab instances.
241- `sudo -u git -H psql -d gitlabhq_production` for source-installed instances.
242
243Verify `objectstg` below (where `store=2`) has count of all packages:
244
245```shell
246gitlabhq_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;
247
248total | filesystem | objectstg
249------+------------+-----------
250 34   |          0 |        34
251```
252
253Verify that there are no files on disk in the `packages` folder:
254
255```shell
256sudo find /var/opt/gitlab/gitlab-rails/shared/packages -type f | grep -v tmp | wc -l
257```
258