diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 12:55:51 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 12:55:51 +0300 |
commit | e8d2c2579383897a1dd7f9debd359abe8ae8373d (patch) | |
tree | c42be41678c2586d49a75cabce89322082698334 /doc/api/packages | |
parent | fc845b37ec3a90aaa719975f607740c22ba6a113 (diff) |
Add latest changes from gitlab-org/gitlab@14-1-stable-eev14.1.0-rc42
Diffstat (limited to 'doc/api/packages')
-rw-r--r-- | doc/api/packages/debian.md | 151 | ||||
-rw-r--r-- | doc/api/packages/debian_group_distributions.md | 222 | ||||
-rw-r--r-- | doc/api/packages/debian_project_distributions.md | 222 | ||||
-rw-r--r-- | doc/api/packages/helm.md | 96 | ||||
-rw-r--r-- | doc/api/packages/nuget.md | 29 | ||||
-rw-r--r-- | doc/api/packages/pypi.md | 2 |
6 files changed, 721 insertions, 1 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. diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md new file mode 100644 index 00000000000..ba61bf49e01 --- /dev/null +++ b/doc/api/packages/debian_group_distributions.md @@ -0,0 +1,222 @@ +--- +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" +``` diff --git a/doc/api/packages/debian_project_distributions.md b/doc/api/packages/debian_project_distributions.md new file mode 100644 index 00000000000..aad5558dcba --- /dev/null +++ b/doc/api/packages/debian_project_distributions.md @@ -0,0 +1,222 @@ +--- +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" +``` diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md new file mode 100644 index 00000000000..a76fa9d3755 --- /dev/null +++ b/doc/api/packages/helm.md @@ -0,0 +1,96 @@ +--- +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 +--- + +# Helm API + +This is the API documentation for [Helm](../../user/packages/helm_repository/index.md). + +WARNING: +This API is used by the Helm-related package clients such as [Helm](https://helm.sh/) +and [`helm-push`](https://github.com/chartmuseum/helm-push/#readme), +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 Helm packages from the GitLab +Package Registry, see the [Helm registry documentation](../../user/packages/helm_repository/index.md). + +NOTE: +These endpoints do not adhere to the standard API authentication methods. +See the [Helm registry documentation](../../user/packages/helm_repository/index.md) +for details on which headers and token types are supported. + +## Download a chart index + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62757) in GitLab 14.1. + +Download a chart index: + +```plaintext +GET projects/:id/packages/helm/:channel/index.yaml +``` + +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `channel` | string | yes | Helm repository channel. | + +```shell +curl --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml +``` + +Write the output to a file: + +```shell +curl --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml \ + --remote-name +``` + +## Download a chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61014) in GitLab 14.0. + +Download a chart: + +```plaintext +GET projects/:id/packages/helm/:channel/charts/:file_name.tgz +``` + +| Attribute | Type | Required | Description | +| ----------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `channel` | string | yes | Helm repository channel. | +| `file_name` | string | yes | Chart file name. | + +```shell +curl --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/charts/mychart.tgz \ + --remote-name +``` + +## Upload a chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64814) in GitLab 14.1. + +Upload a chart: + +```plaintext +POST projects/:id/packages/helm/api/:channel/charts +``` + +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `channel` | string | yes | Helm repository channel. | +| `chart` | file | yes | Chart (as `multipart/form-data`). | + +```shell +curl --request POST \ + --form 'chart=@mychart.tgz' \ + --user <username>:<personal_access_token> \ + https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts +``` diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index bbcb2cb9bc4..d19e2dfa65b 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -102,6 +102,30 @@ curl --request PUT \ "https://gitlab.example.com/api/v4/projects/1/packages/nuget" ``` +## Upload a symbol package file + +> Introduced in GitLab 12.8. + +Upload a NuGet symbol package file (`.snupkg`): + +```plaintext +PUT projects/:id/packages/nuget/symbolpackage +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the project. | +| `package_name` | string | yes | The name of the package. | +| `package_version` | string | yes | The version of the package. | +| `package_filename`| string | yes | The name of the file. | + +```shell +curl --request PUT \ + --upload-file path/to/mynugetpkg.1.3.0.17.snupkg \ + --user <username>:<personal_access_token> \ + "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolpackage" +``` + ## Route prefix For the remaining routes, there are two sets of identical routes that each make requests in @@ -193,6 +217,11 @@ Example response: "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget", "@type": "PackagePublish/2.0.0", "comment": "Push and delete (or unlist) packages." + }, + { + "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolpackage", + "@type": "SymbolPackagePublish/4.9.0", + "comment": "Push symbol packages." } ] } diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index 77ba028c447..dd301e9fab8 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This is the API documentation for [PyPI Packages](../../user/packages/pypi_repository/index.md). WARNING: -This API is used by the [PyPI package manager client](https://pypi.apache.org/) +This API is used by the [PyPI package manager client](https://pypi.org/) and is generally not meant for manual consumption. For instructions on how to upload and install PyPI packages from the GitLab |