Merge branch '331738-debian-upload-docs' into 'master'

Debian package registry documentation

See merge request gitlab-org/gitlab!64649

doc/api/api_resources.md

@@ -34,6 +34,7 @@ The following API resources are available in the project context:
 | [Dependencies](dependencies.md) **(ULTIMATE)**                      | `/projects/:id/dependencies`                                                                                                                                                                          |
 | [Deploy keys](deploy_keys.md)                                       | `/projects/:id/deploy_keys` (also available standalone)                                                                                                                                               |
 | [Freeze Periods](freeze_periods.md)                                 | `/projects/:id/freeze_periods`                                                                                                                                                                        |
+| [Debian distributions](packages/debian_project_distributions.md)             | `/projects/:id/debian_distributions` (also available for groups)                                                                                                                                      |
 | [Deployments](deployments.md)                                       | `/projects/:id/deployments`                                                                                                                                                                           |
 | [Discussions](discussions.md) (threaded comments)                   | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) |
 | [Environments](environments.md)                                     | `/projects/:id/environments`                                                                                                                                                                          |
@@ -99,6 +100,7 @@ The following API resources are available in the group context:
 |:-----------------------------------------------------------------|:---------------------------------------------------------------------------------|
 | [Access requests](access_requests.md)                            | `/groups/:id/access_requests/` (also available for projects)                     |
 | [Custom attributes](custom_attributes.md)                        | `/groups/:id/custom_attributes` (also available for projects and users)          |
+| [Debian distributions](packages/debian_group_distributions.md)   | `/groups/:id/-/packages/debian` (also available for projects)                |
 | [Discussions](discussions.md) (threaded comments) **(ULTIMATE)** | `/groups/:id/epics/.../discussions` (also available for projects)                |
 | [Epic issues](epic_issues.md) **(ULTIMATE)**                     | `/groups/:id/epics/.../issues`                                                   |
 | [Epic links](epic_links.md) **(ULTIMATE)**                       | `/groups/:id/epics/.../epics`                                                    |

doc/api/packages/debian.md

+---
+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.

doc/api/packages/debian_group_distributions.md

+---
+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 group distributions API **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) in GitLab 14.0.
+
+See the [Debian package registry documentation](../../user/packages/debian_repository/index.md)
+for more information about working with Debian packages.
+
+## Enable Debian repository feature
+
+Debian repository support is gated behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can opt to enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:debian_packages)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:debian_packages)
+```
+
+## List all Debian distributions in a group
+
+Lists Debian distributions in the given group.
+
+```plaintext
+GET /groups/:id/debian_distributions
+```
+
+| Attribute  | Type            | Required | Description |
+| ---------- | --------------- | -------- | ----------- |
+| `id`       | integer/string  | yes      | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding). |
+| `codename` | string          | no       | Filter with specific `codename`. |
+| `suite`    | string          | no       | Filter with specific `suite`. |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "codename": "unstable",
+    "suite": null,
+    "origin": null,
+    "label": null,
+    "version": null,
+    "description": null,
+    "valid_time_duration_seconds": null,
+    "components": [
+      "main"
+    ],
+    "architectures": [
+      "all",
+      "amd64"
+    ]
+  }
+]
+```
+
+## Single Debian group distribution
+
+Gets a single Debian group distribution.
+
+```plaintext
+GET /groups/:id/debian_distributions/:codename
+```
+
+| Attribute  | Type           | Required | Description |
+| ---------- | -------------- | -------- | ----------- |
+| `id`       | integer/string | yes      | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename` | integer        | yes      | The `codename` of a distribution. |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions/unstable"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "codename": "unstable",
+  "suite": null,
+  "origin": null,
+  "label": null,
+  "version": null,
+  "description": null,
+  "valid_time_duration_seconds": null,
+  "components": [
+    "main"
+  ],
+  "architectures": [
+    "all",
+    "amd64"
+  ]
+}
+```
+
+## Create a Debian group distribution
+
+Creates a Debian group distribution.
+
+```plaintext
+POST /groups/:id/debian_distributions
+```
+
+| Attribute                     | Type           | Required | Description |
+| ----------------------------- | -------------- | -------- | ----------- |
+| `id`                          | integer/string | yes      | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename`                    | string         | yes      | The codename of a Debian distribution. |
+| `suite`                       | string         | no       | The suite of the new Debian distribution. |
+| `origin`                      | string         | no       | The origin of the new Debian distribution. |
+| `label`                       | string         | no       | The label of the new Debian distribution. |
+| `version`                     | string         | no       | The version of the new Debian distribution. |
+| `description`                 | string         | no       | The description of the new Debian distribution. |
+| `valid_time_duration_seconds` | integer        | no       | The valid time duration (in seconds) of the new Debian distribution. |
+| `components`                  | architectures  | no       | The new Debian distribution's list of components. |
+| `architectures`               | architectures  | no       | The new Debian distribution's list of architectures. |
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions?codename=unstable"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "codename": "unstable",
+  "suite": null,
+  "origin": null,
+  "label": null,
+  "version": null,
+  "description": null,
+  "valid_time_duration_seconds": null,
+  "components": [
+    "main"
+  ],
+  "architectures": [
+    "all",
+    "amd64"
+  ]
+}
+```
+
+## Update a Debian group distribution
+
+Updates a Debian group distribution.
+
+```plaintext
+PUT /groups/:id/debian_distributions/:codename
+```
+
+| Attribute                     | Type           | Required | Description |
+| ----------------------------- | -------------- | -------- | ----------- |
+| `id`                          | integer/string | yes      | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename`                    | string         | yes      | The Debian distribution's new codename.  |
+| `suite`                       | string         | no       | The Debian distribution's new suite. |
+| `origin`                      | string         | no       | The Debian distribution's new origin. |
+| `label`                       | string         | no       | The Debian distribution's new label. |
+| `version`                     | string         | no       | The Debian distribution's new version. |
+| `description`                 | string         | no       | The Debian distribution's new description. |
+| `valid_time_duration_seconds` | integer        | no       | The Debian distribution's new valid time duration (in seconds). |
+| `components`                  | architectures  | no       | The Debian distribution's new list of components. |
+| `architectures`               | architectures  | no       | The Debian distribution's new list of architectures. |
+
+```shell
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions/unstable?suite=new-suite&valid_time_duration_seconds=604800"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "codename": "unstable",
+  "suite": "new-suite",
+  "origin": null,
+  "label": null,
+  "version": null,
+  "description": null,
+  "valid_time_duration_seconds": 604800,
+  "components": [
+    "main"
+  ],
+  "architectures": [
+    "all",
+    "amd64"
+  ]
+}
+```
+
+## Delete a Debian group distribution
+
+Deletes a Debian group distribution.
+
+```plaintext
+DELETE /groups/:id/debian_distributions/:codename
+```
+
+| Attribute  | Type           | Required | Description |
+| ---------- | -------------- | -------- | ----------- |
+| `id`       | integer/string | yes      | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename` | integer        | yes      | The codename of the Debian distribution. |
+
+```shell
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions/unstable"
+```

doc/api/packages/debian_project_distributions.md

+---
+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 project distributions API **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) in GitLab 14.0.
+
+See the [Debian package registry documentation](../../user/packages/debian_repository/index.md)
+for more information about working with Debian packages.
+
+## Enable Debian repository feature
+
+Debian repository support is gated behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can opt to enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:debian_packages)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:debian_packages)
+```
+
+## List all Debian distributions in a project
+
+Lists Debian distributions in the given project.
+
+```plaintext
+GET /projects/:id/debian_distributions
+```
+
+| Attribute  | Type           | Required | Description |
+| ---------- | -------------- | -------- | ----------- |
+| `id`       | integer/string | yes      | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). |
+| `codename` | string         | no       | Filter with a specific `codename`. |
+| `suite`    | string         | no       | Filter with a specific `suite`. |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 1,
+    "codename": "unstable",
+    "suite": null,
+    "origin": null,
+    "label": null,
+    "version": null,
+    "description": null,
+    "valid_time_duration_seconds": null,
+    "components": [
+      "main"
+    ],
+    "architectures": [
+      "all",
+      "amd64"
+    ]
+  }
+]
+```
+
+## Single Debian project distribution
+
+Gets a single Debian project distribution.
+
+```plaintext
+GET /projects/:id/debian_distributions/:codename
+```
+
+| Attribute  | Type           | Required | Description |
+| ---------- | -------------- | -------- | ----------- |
+| `id`       | integer/string | yes      | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename` | integer        | yes      | The `codename` of a distribution. |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions/unstable"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "codename": "unstable",
+  "suite": null,
+  "origin": null,
+  "label": null,
+  "version": null,
+  "description": null,
+  "valid_time_duration_seconds": null,
+  "components": [
+    "main"
+  ],
+  "architectures": [
+    "all",
+    "amd64"
+  ]
+}
+```
+
+## Create a Debian project distribution
+
+Creates a Debian project distribution.
+
+```plaintext
+POST /projects/:id/debian_distributions
+```
+
+| Attribute                     | Type           | Required | Description |
+| ----------------------------- | -------------- | -------- | ----------- |
+| `id`                          | integer/string | yes      | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename`                    | string         | yes      | The Debian distribution's codename.  |
+| `suite`                       | string         | no       | The new Debian distribution's suite. |
+| `origin`                      | string         | no       | The new Debian distribution's origin. |
+| `label`                       | string         | no       | The new Debian distribution's label. |
+| `version`                     | string         | no       | The new Debian distribution's version. |
+| `description`                 | string         | no       | The new Debian distribution's description. |
+| `valid_time_duration_seconds` | integer        | no       | The new Debian distribution's valid time duration (in seconds). |
+| `components`                  | architectures  | no       | The new Debian distribution's list of components. |
+| `architectures`               | architectures  | no       | The new Debian distribution's list of architectures. |
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions?codename=unstable"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "codename": "unstable",
+  "suite": null,
+  "origin": null,
+  "label": null,
+  "version": null,
+  "description": null,
+  "valid_time_duration_seconds": null,
+  "components": [
+    "main"
+  ],
+  "architectures": [
+    "all",
+    "amd64"
+  ]
+}
+```
+
+## Update a Debian project distribution
+
+Updates a Debian project distribution.
+
+```plaintext
+PUT /projects/:id/debian_distributions/:codename
+```
+
+| Attribute                     | Type           | Required | Description |
+| ----------------------------- | -------------- | -------- | ----------- |
+| `id`                          | integer/string | yes      | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename`                    | string         | yes      | The Debian distribution's codename. |
+| `suite`                       | string         | no       | The Debian distribution's new suite. |
+| `origin`                      | string         | no       | The Debian distribution's new origin. |
+| `label`                       | string         | no       | The Debian distribution's new label. |
+| `version`                     | string         | no       | The Debian distribution's new version. |
+| `description`                 | string         | no       | The Debian distribution's new description. |
+| `valid_time_duration_seconds` | integer        | no       | The Debian distribution's new valid time duration (in seconds). |
+| `components`                  | architectures  | no       | The Debian distribution's new list of components. |
+| `architectures`               | architectures  | no       | The Debian distribution's new list of architectures. |
+
+```shell
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions/unstable?suite=new-suite&valid_time_duration_seconds=604800"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "codename": "unstable",
+  "suite": "new-suite",
+  "origin": null,
+  "label": null,
+  "version": null,
+  "description": null,
+  "valid_time_duration_seconds": 604800,
+  "components": [
+    "main"
+  ],
+  "architectures": [
+    "all",
+    "amd64"
+  ]
+}
+```
+
+## Delete a Debian project distribution
+
+Deletes a Debian project distribution.
+
+```plaintext
+DELETE /projects/:id/debian_distributions/:codename
+```
+
+| Attribute  | Type           | Required | Description |
+| ---------- | -------------- | -------- | ----------- |
+| `id`       | integer/string | yes      | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `codename` | integer        | yes      | The Debian distribution's codename. |
+
+```shell
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions/unstable"
+```

doc/user/packages/debian_repository/index.md

+---
+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 packages in the Package Registry **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) in GitLab 14.1.
+
+WARNING:
+The Debian package registry for GitLab is under development and isn't ready for production use due to
+limited functionality.
+
+Publish Debian packages in your project's Package Registry. Then install the
+packages whenever you need to use them as a dependency.
+
+Project and Group packages are supported.
+
+For documentation of the specific API endpoints that Debian package manager
+clients use, see the [Debian API documentation](../../../api/packages/debian.md).
+
+## Enable Debian repository feature
+
+Debian repository support is still a work in progress. It's gated behind a feature flag that's
+**disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can opt to enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:debian_packages)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:debian_packages)
+```
+
+## Build a Debian package
+
+Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian.org/Packaging).
+
+## Create a Distribution
+
+On the project-level, Debian packages are published using *Debian Distributions*. To publish
+packages on the group level, create a distribution with the same `codename`.
+
+To create a project-level distribution:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=unstable
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "codename": "unstable",
+  "suite": null,
+  "origin": null,
+  "label": null,
+  "version": null,
+  "description": null,
+  "valid_time_duration_seconds": null,
+  "components": [
+    "main"
+  ],
+  "architectures": [
+    "all",
+    "amd64"
+  ]
+}
+```
+
+More information on Debian distribution APIs:
+
+- [Debian project distributions API](../../../api/packages/debian_project_distributions.md)
+- [Debian group distributions API](../../../api/packages/debian_group_distributions.md)
+
+## Publish a package
+
+Once built, several files are created:
+
+- `.deb` files: the binary packages
+- `.udeb` files: lightened .deb files, used for Debian-Installer (if needed)
+- `.tar.{gz,bz2,xz,...}` files: Source files
+- `.dsc` file: Source metadata, and list of source files (with hashes)
+- `.buildinfo` file: Used for Reproducible builds (optional)
+- `.changes` file: Upload metadata, and list of uploaded files (all the above)
+
+To upload these files, you can use `dput-ng >= 1.32` (Debian bullseye):
+
+```shell
+cat <<EOF > dput.cf
+[gitlab]
+method = https
+fqdn = <login>:<your_access_token>@gitlab.example.com
+incoming = /api/v4/projects/<project_id>/packages/debian
+EOF
+
+dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes
+```
+
+## Install a package
+
+The Debian package registry for GitLab is under development, and isn't ready for production use. You
+cannot install packages from the registry. However, you can download files directly from the UI.