diff options
Diffstat (limited to 'doc/development/packages.md')
| -rw-r--r-- | doc/development/packages.md | 60 |
1 files changed, 28 insertions, 32 deletions
diff --git a/doc/development/packages.md b/doc/development/packages.md index 2476c876b77..e8c326da974 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -6,20 +6,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Packages -This document guides you through adding another [package management system](../administration/packages/index.md) support to GitLab. +This document guides you through adding support to GitLab for a new a [package management system](../administration/packages/index.md). -See already supported package types in [Packages documentation](../administration/packages/index.md) +See the already supported formats in the [Packages & Registries documentation](../user/packages/index.md) -Since GitLab packages' UI is pretty generic, it is possible to add basic new -package system support with solely backend changes. This guide is superficial and does -not cover the way the code should be written. However, you can find a good example -by looking at the following merge requests: +It is possible to add a new format with only backend changes. +This guide is superficial and does not cover the way the code should be written. +However, you can find a good example by looking at the following merge requests: -- [npm registry support](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8673). -- [Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6607). -- [Composer repository for PHP dependencies](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22415). -- [Terraform modules registry](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834). -- [Instance-level endpoint for Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8757). +- [npm registry support](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8673) +- [Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6607) +- [Instance-level API for Maven repository](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8757) +- [NuGet group-level API](https://gitlab.com/gitlab-org/gitlab/-/issues/36423) ## General information @@ -60,26 +58,13 @@ project are visible. Alternatively, a group-level endpoint may be used to allow within a given group. Lastly, an instance-level endpoint can be used to allow visibility to all packages within an entire GitLab instance. -Using group and project level endpoints allows for more flexibility in package naming, however, more remotes -have to be managed. Using instance level endpoints requires [stricter naming conventions](#naming-conventions). +As an MVC, we recommend beginning with a project-level endpoint. A typical iteration plan for remote hierarchies is to go from: -The current state of existing package registries availability is: +- Publish and install in a project +- Install from a group +- Publish and install in an Instance (this is for Self-Managed customers) -| Repository Type | Project Level | Group Level | Instance Level | -|------------------|---------------|-------------|----------------| -| Maven | Yes | Yes | Yes | -| Conan | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) | Yes | -| npm | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36853) | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36853) | -| NuGet | Yes | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/36425) | -| PyPI | Yes | No | No | -| Go | Yes | No - [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213900) | No - [open-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213902) | -| Composer | Yes | Yes | No | -| Generic | Yes | No | No | - -NOTE: -npm is currently a hybrid of the instance level and group level. -It is using the top-level group or namespace as the defining portion of the name -(for example, `@my-group-name/my-package-name`). +Using instance-level endpoints requires [stricter naming conventions](#naming-conventions). NOTE: Composer package naming scope is Instance Level. @@ -116,8 +101,8 @@ Packages can be configured to use object storage, therefore your code must suppo The way new package systems are integrated in GitLab is using an [MVC](https://about.gitlab.com/handbook/values/#minimum-viable-change-mvc). Therefore, the first iteration should support the bare minimum user actions: -- Authentication -- Uploading a package +- Authentication with a GitLab job, personal access, project access, or deploy token +- Uploading a package and displaying basic metadata in the user interface - Pulling a package - Required actions @@ -137,7 +122,7 @@ There are usually 2 phases for the MVC: When implementing a new package manager, it is tempting to create one large merge request containing all of the necessary endpoints and services necessary to support basic usage. Instead, put the -API endpoints behind a [feature flag](feature_flags/development.md) and +API endpoints behind a [feature flag](feature_flags/index.md) and submit each endpoint or behavior (download, upload, etc) in a different merge request to shorten the review process. @@ -242,6 +227,17 @@ create the package record. Workhorse provides a variety of file metadata such as For testing purposes, you may want to [enable object storage](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/object_storage.md) in your local development environment. +#### File size limits + +Files uploaded to the GitLab Package Registry are [limited by format](../administration/instance_limits.md#package-registry-limits). +On GitLab.com, these are typically set to 5GB to help prevent timeout issues and abuse. + +When a new package type is added to the `Packages::Package` model, a size limit must be added +similar to [this example](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52639/diffs#382f879fb09b0212e3cedd99e6c46e2083867216), +or the [related test](https://gitlab.com/gitlab-org/gitlab/-/blob/fe4ba43766781371cebfacd78364a1de762917cd/spec/models/packages/package_spec.rb#L761) +must be updated if file size limits do not apply. The only reason a size limit does not apply is if +the package format does not upload and store package files. + #### Rate Limits on GitLab.com Package manager clients can make rapid requests that exceed the |