diff options
Diffstat (limited to 'doc/api/packages/debian.md')
-rw-r--r-- | doc/api/packages/debian.md | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md new file mode 100644 index 00000000000..cd97bd609df --- /dev/null +++ b/doc/api/packages/debian.md @@ -0,0 +1,151 @@ +--- +stage: Package +group: Package +info: 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 +--- + +# Debian API + +This is the API documentation for [Debian](../../user/packages/debian_repository/index.md). + +WARNING: +This API is used by the Debian related package clients such as [dput](https://manpages.debian.org/stable/dput-ng/dput.1.en.html) +and [apt-get](https://manpages.debian.org/stable/apt/apt-get.8.en.html), +and is generally not meant for manual consumption. This API is under development and is not ready +for production use due to limited functionality. + +For instructions on how to upload and install Debian packages from the GitLab +package registry, see the [Debian registry documentation](../../user/packages/debian_repository/index.md). + +NOTE: +These endpoints do not adhere to the standard API authentication methods. +See the [Debian registry documentation](../../user/packages/debian_repository/index.md) +for details on which headers and token types are supported. + +## Enable the Debian API + +The Debian API for GitLab is behind a feature flag that is disabled by default. GitLab +administrators with access to the GitLab Rails console can enable this API for your instance. + +To enable it: + +```ruby +Feature.enable(:debian_packages) +``` + +To disable it: + +```ruby +Feature.disable(:debian_packages) +``` + +## Upload a package file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62028) in GitLab 14.0. + +Upload a Debian package file: + +```plaintext +PUT projects/:id/packages/debian/:file_name +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `file_name` | string | yes | The name of the Debian package file. | + +```shell +curl --request PUT \ + --upload-file path/to/mypkg.deb \ + --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/mypkg.deb" +``` + +## Route prefix + +The remaining endpoints described are two sets of identical routes that each make requests in +different scopes: + +- Use the project-level prefix to make requests in a single project's scope. +- Use the group-level prefix to make requests in a single group's scope. + +The examples in this document all use the project-level prefix. + +### Project-level + +```plaintext + /projects/:id/packages/debian` +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The project ID or full project path. | + +### Group-level + +```plaintext + /groups/:id/-/packages/debian` +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The project ID or full group path. | + +## Download a distribution Release file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64067) in GitLab 14.1. + +Download a Debian package file. + +```plaintext +GET <route-prefix>/dists/*distribution/Release +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `distribution` | string | yes | The codename or suite of the Debian distribution. | + +```shell +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/Release" +``` + +Write the output to a file: + +```shell +curl --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/Release" \ + --remote-name +``` + +This writes the downloaded file to `Release` in the current directory. + +## Download a signed distribution Release file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64067) in GitLab 14.1. + +Download a Debian package file. + +Signed releases are [not supported](https://gitlab.com/groups/gitlab-org/-/epics/6057#note_582697034). +Therefore, this endpoint downloads the unsigned release file. + +```plaintext +GET <route-prefix>/dists/*distribution/InRelease +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `distribution` | string | yes | The codename or suite of the Debian distribution. | + +```shell +curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/InRelease" +``` + +Write the output to a file: + +```shell +curl --header "Private-Token: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/packages/debian/dists/my-distro/InRelease" \ + --remote-name +``` + +This writes the downloaded file to `InRelease` in the current directory. |