diff options
author | Marcel Amirault <ravlen@gmail.com> | 2019-05-05 16:57:21 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2019-05-05 16:57:21 +0300 |
commit | 0207468401e41dcea537fa2d48f395a5fa7b3300 (patch) | |
tree | 5c7fb2dee472bb57bce8e64bd3105cdf0af75ea4 /doc/development/packages.md | |
parent | 6f54ced40dadf268b6d1525c413f9ce52930f1fe (diff) |
Docs: Merge EE doc/development to CE
Diffstat (limited to 'doc/development/packages.md')
-rw-r--r-- | doc/development/packages.md | 68 |
1 files changed, 68 insertions, 0 deletions
diff --git a/doc/development/packages.md b/doc/development/packages.md new file mode 100644 index 00000000000..a3b891d7834 --- /dev/null +++ b/doc/development/packages.md @@ -0,0 +1,68 @@ +# Packages **[PREMIUM]** + +This document will guide you through adding another [package management system](https://docs.gitlab.com/ee/administration/packages.html) support to GitLab. + +See already supported package types in [Packages documentation](https://docs.gitlab.com/ee/administration/packages.html) + +Since GitLab packages' UI is pretty generic, it is possible to add new +package system support by 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 existing merge requests with Maven and NPM support: + +- [NPM registry support](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8673). +- [Maven repository](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6607). +- [Instance level endpoint for Maven repository](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8757) + +## General information + +The existing database model requires the following: + +- Every package belongs to a project. +- Every package file belongs to a package. +- A package can have one or more package files. +- The package model is based on storing information about the package and its version. + +## API endpoints + +Package systems work with GitLab via API. For example `ee/lib/api/npm_packages.rb` +implements API endpoints to work with NPM clients. So, the first thing to do is to +add a new `ee/lib/api/your_name_packages.rb` file with API endpoints that are +necessary to make the package system client to work. Usually that means having +endpoints like: + +- GET package information. +- GET package file content. +- PUT upload package. + +Since the packages belong to a project, it's expected to have project-level endpoint +for uploading and downloading them. For example: + +``` +GET https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/ +PUT https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/ +``` + +Group-level and instance-level endpoints are good to have but are optional. + +NOTE: **Note:** +To avoid name conflict for instance-level endpoints we use +[the package naming convention](https://docs.gitlab.com/ee/user/project/packages/npm_registry.html#package-naming-convention) + +## Configuration + +GitLab has a `packages` section in its configuration file (`gitlab.rb`). +It applies to all package systems supported by GitLab. Usually you don't need +to add anything there. + +Packages can be configured to use object storage, therefore your code must support it. + +## Database + +The current database model allows you to store a name and a version for each package. +Every time you upload a new package, you can either create a new record of `Package` +or add files to existing record. `PackageFile` should be able to store all file-related +information like the file `name`, `side`, `sha1`, etc. + +If there is specific data necessary to be stored for only one package system support, +consider creating a separate metadata model. See `packages_maven_metadata` table +and `Packages::MavenMetadatum` model as example for package specific data. |