debian-mirror-gitlab/doc/development/packages.md

69 lines
2.9 KiB
Markdown
Raw Normal View History

2019-09-30 21:07:59 +05:30
# Packages **(PREMIUM)**
2019-07-31 22:56:46 +05:30
2019-09-04 21:01:54 +05:30
This document will guide you through adding another [package management system](../administration/packages.md) support to GitLab.
2019-07-31 22:56:46 +05:30
2019-09-04 21:01:54 +05:30
See already supported package types in [Packages documentation](../administration/packages.md)
2019-07-31 22:56:46 +05:30
Since GitLab packages' UI is pretty generic, it is possible to add new
2019-09-30 21:07:59 +05:30
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:
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
- [NPM registry support](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/8673).
2019-07-31 22:56:46 +05:30
- [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:
2019-09-30 21:07:59 +05:30
- Every package belongs to a project.
2019-07-31 22:56:46 +05:30
- 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
2019-09-30 21:07:59 +05:30
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:
2019-07-31 22:56:46 +05:30
- 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
2019-09-30 21:07:59 +05:30
for uploading and downloading them. For example:
2019-07-31 22:56:46 +05:30
```
GET https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/
PUT https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/
```
2019-09-30 21:07:59 +05:30
Group-level and instance-level endpoints are good to have but are optional.
2019-07-31 22:56:46 +05:30
NOTE: **Note:**
2019-09-30 21:07:59 +05:30
To avoid name conflict for instance-level endpoints we use
2019-09-04 21:01:54 +05:30
[the package naming convention](../user/project/packages/npm_registry.md#package-naming-convention)
2019-07-31 22:56:46 +05:30
## Configuration
2019-09-30 21:07:59 +05:30
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.
2019-07-31 22:56:46 +05:30
2019-09-30 21:07:59 +05:30
Packages can be configured to use object storage, therefore your code must support it.
2019-07-31 22:56:46 +05:30
## 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.
2019-09-30 21:07:59 +05:30
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
2019-07-31 22:56:46 +05:30
and `Packages::MavenMetadatum` model as example for package specific data.