diff options
Diffstat (limited to 'docs/content/doc/usage')
46 files changed, 1974 insertions, 1 deletions
diff --git a/docs/content/doc/usage/_index.en-us.md b/docs/content/doc/usage/_index.en-us.md new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/docs/content/doc/usage/_index.en-us.md diff --git a/docs/content/doc/usage/_index.zh-cn.md b/docs/content/doc/usage/_index.zh-cn.md new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/docs/content/doc/usage/_index.zh-cn.md diff --git a/docs/content/doc/usage/_index.zh-tw.md b/docs/content/doc/usage/_index.zh-tw.md new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/docs/content/doc/usage/_index.zh-tw.md diff --git a/docs/content/doc/usage/agit-support.en-us.md b/docs/content/doc/usage/agit-support.en-us.md index b005e1bd73..30e2879e89 100644 --- a/docs/content/doc/usage/agit-support.en-us.md +++ b/docs/content/doc/usage/agit-support.en-us.md @@ -5,6 +5,8 @@ slug: "agit-setup" weight: 12 toc: false draft: false +aliases: + - /en-us/agit-setup menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/authentication.en-us.md b/docs/content/doc/usage/authentication.en-us.md index 5478ee94f6..2b8cdd2964 100644 --- a/docs/content/doc/usage/authentication.en-us.md +++ b/docs/content/doc/usage/authentication.en-us.md @@ -5,6 +5,8 @@ slug: "authentication" weight: 10 toc: false draft: false +aliases: + - /en-us/authentication menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/authentication.zh-cn.md b/docs/content/doc/usage/authentication.zh-cn.md index 403c3f43ce..37ecc8bab1 100644 --- a/docs/content/doc/usage/authentication.zh-cn.md +++ b/docs/content/doc/usage/authentication.zh-cn.md @@ -5,6 +5,8 @@ slug: "authentication" weight: 10 toc: false draft: false +aliases: + - /zh-cn/authentication menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/authentication.zh-tw.md b/docs/content/doc/usage/authentication.zh-tw.md index 958c498fc6..75959802b1 100644 --- a/docs/content/doc/usage/authentication.zh-tw.md +++ b/docs/content/doc/usage/authentication.zh-tw.md @@ -5,6 +5,8 @@ slug: "authentication" weight: 10 toc: false draft: false +aliases: + - /zh-tw/authentication menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/clone-filter.en-us.md b/docs/content/doc/usage/clone-filter.en-us.md index 7d4ba2d9a8..8331c138bf 100644 --- a/docs/content/doc/usage/clone-filter.en-us.md +++ b/docs/content/doc/usage/clone-filter.en-us.md @@ -5,6 +5,8 @@ slug: "clone-filters" weight: 25 draft: false toc: false +aliases: + - /en-us/clone-filters menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/incoming-email.en-us.md b/docs/content/doc/usage/incoming-email.en-us.md index 867e9d8a69..205b3dd8ed 100644 --- a/docs/content/doc/usage/incoming-email.en-us.md +++ b/docs/content/doc/usage/incoming-email.en-us.md @@ -5,6 +5,8 @@ slug: "incoming-email" weight: 13 draft: false toc: false +aliases: + - /en-us/incoming-email menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/issue-pull-request-templates.en-us.md b/docs/content/doc/usage/issue-pull-request-templates.en-us.md index 107484689b..b48763cf8e 100644 --- a/docs/content/doc/usage/issue-pull-request-templates.en-us.md +++ b/docs/content/doc/usage/issue-pull-request-templates.en-us.md @@ -5,6 +5,8 @@ slug: "issue-pull-request-templates" weight: 15 toc: false draft: false +aliases: + - /en-us/issue-pull-request-templates menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md b/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md index 866378e2ac..135dcf8de8 100644 --- a/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md +++ b/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md @@ -5,6 +5,8 @@ slug: "issue-pull-request-templates" weight: 15 toc: true draft: false +aliases: + - /zh-cn/issue-pull-request-templates menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/labels.en-us.md b/docs/content/doc/usage/labels.en-us.md index 7c2494971f..bf60951d8c 100644 --- a/docs/content/doc/usage/labels.en-us.md +++ b/docs/content/doc/usage/labels.en-us.md @@ -5,6 +5,8 @@ slug: "labels" weight: 13 toc: false draft: false +aliases: + - /en-us/labels menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/linked-references.en-us.md b/docs/content/doc/usage/linked-references.en-us.md index 335d2654e3..8cd4ff7b1f 100644 --- a/docs/content/doc/usage/linked-references.en-us.md +++ b/docs/content/doc/usage/linked-references.en-us.md @@ -5,6 +5,8 @@ slug: "automatically-linked-references" weight: 15 toc: false draft: false +aliases: + - /en-us/automatically-linked-references menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/merge-message-templates.en-us.md b/docs/content/doc/usage/merge-message-templates.en-us.md index 70710b989e..751f07e13f 100644 --- a/docs/content/doc/usage/merge-message-templates.en-us.md +++ b/docs/content/doc/usage/merge-message-templates.en-us.md @@ -5,6 +5,8 @@ slug: "merge-message-templates" weight: 15 toc: false draft: false +aliases: + - /en-us/merge-message-templates menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/packages/_index.en-us.md b/docs/content/doc/usage/packages/_index.en-us.md new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/docs/content/doc/usage/packages/_index.en-us.md diff --git a/docs/content/doc/usage/packages/cargo.en-us.md b/docs/content/doc/usage/packages/cargo.en-us.md new file mode 100644 index 0000000000..a74384ccef --- /dev/null +++ b/docs/content/doc/usage/packages/cargo.en-us.md @@ -0,0 +1,110 @@ +--- +date: "2022-11-20T00:00:00+00:00" +title: "Cargo Packages Repository" +slug: "cargo" +weight: 5 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Cargo" + weight: 5 + identifier: "cargo" +--- + +# Cargo Packages Repository + +Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Cargo package registry, you need [Rust and Cargo](https://www.rust-lang.org/tools/install). + +Cargo stores informations about the available packages in a package index stored in a git repository. +This repository is needed to work with the registry. +The following section describes how to create it. + +## Index Repository + +Cargo stores informations about the available packages in a package index stored in a git repository. +In Gitea this repository has the special name `_cargo-index`. +After a package was uploaded, its metadata is automatically written to the index. +The content of this repository should not be manually modified. + +The user or organization package settings page allows to create the index repository along with the configuration file. +If needed this action will rewrite the configuration file. +This can be useful if for example the Gitea instance domain was changed. + +If the case arises where the packages stored in Gitea and the information in the index repository are out of sync, the settings page allows to rebuild the index repository. +This action iterates all packages in the registry and writes their information to the index. +If there are lot of packages this process may take some time. + +## Configuring the package registry + +To register the package registry the Cargo configuration must be updated. +Add the following text to the configuration file located in the current users home directory (for example `~/.cargo/config.toml`): + +``` +[registry] +default = "gitea" + +[registries.gitea] +index = "https://gitea.example.com/{owner}/_cargo-index.git" + +[net] +git-fetch-with-cli = true +``` + +| Parameter | Description | +| --------- | ----------- | +| `owner` | The owner of the package. | + +If the registry is private or you want to publish new packages, you have to configure your credentials. +Add the credentials section to the credentials file located in the current users home directory (for example `~/.cargo/credentials.toml`): + +``` +[registries.gitea] +token = "Bearer {token}" +``` + +| Parameter | Description | +| --------- | ----------- | +| `token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) | + +## Publish a package + +Publish a package by running the following command in your project: + +```shell +cargo publish +``` + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a package from the package registry, execute the following command: + +```shell +cargo add {package_name} +``` + +| Parameter | Description | +| -------------- | ----------- | +| `package_name` | The package name. | + +## Supported commands + +``` +cargo publish +cargo add +cargo install +cargo yank +cargo unyank +cargo search +``` diff --git a/docs/content/doc/usage/packages/chef.en-us.md b/docs/content/doc/usage/packages/chef.en-us.md new file mode 100644 index 0000000000..dc5ca21e98 --- /dev/null +++ b/docs/content/doc/usage/packages/chef.en-us.md @@ -0,0 +1,97 @@ +--- +date: "2023-01-20T00:00:00+00:00" +title: "Chef Packages Repository" +slug: "chef" +weight: 5 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Chef" + weight: 5 + identifier: "chef" +--- + +# Chef Packages Repository + +Publish [Chef](https://chef.io/) cookbooks for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Chef package registry, you have to use [`knife`](https://docs.chef.io/workstation/knife/). + +## Authentication + +The Chef package registry does not use an username:password authentication but signed requests with a private:public key pair. +Visit the package owner settings page to create the necessary key pair. +Only the public key is stored inside Gitea. if you loose access to the private key you must re-generate the key pair. +[Configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the downloaded private key with your Gitea username as `client_name`. + +## Configure the package registry + +To [configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the Gitea package registry add the url to the `~/.chef/config.rb` file. + +``` +knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef' +``` + +| Parameter | Description | +| --------- | ----------- | +| `owner` | The owner of the package. | + +## Publish a package + +To publish a Chef package execute the following command: + +```shell +knife supermarket share {package_name} +``` + +| Parameter | Description | +| -------------- | ----------- | +| `package_name` | The package name. | + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a package from the package registry, execute the following command: + +```shell +knife supermarket install {package_name} +``` + +Optional you can specify the package version: + +```shell +knife supermarket install {package_name} {package_version} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `package_name` | The package name. | +| `package_version` | The package version. | + +## Delete a package + +If you want to remove a package from the registry, execute the following command: + +```shell +knife supermarket unshare {package_name} +``` + +Optional you can specify the package version: + +```shell +knife supermarket unshare {package_name}/versions/{package_version} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `package_name` | The package name. | +| `package_version` | The package version. | diff --git a/docs/content/doc/usage/packages/composer.en-us.md b/docs/content/doc/usage/packages/composer.en-us.md new file mode 100644 index 0000000000..16c367eb2c --- /dev/null +++ b/docs/content/doc/usage/packages/composer.en-us.md @@ -0,0 +1,123 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Composer Packages Repository" +slug: "composer" +weight: 10 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Composer" + weight: 10 + identifier: "composer" +--- + +# Composer Packages Repository + +Publish [Composer](https://getcomposer.org/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Composer package registry, you can use [Composer](https://getcomposer.org/download/) to consume and a HTTP upload client like `curl` to publish packages. + +## Publish a package + +To publish a Composer package perform a HTTP PUT operation with the package content in the request body. +The package content must be the zipped PHP project with the `composer.json` file. +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +``` +PUT https://gitea.example.com/api/packages/{owner}/composer +``` + +| Parameter | Description | +| ---------- | ----------- | +| `owner` | The owner of the package. | + +If the `composer.json` file does not contain a `version` property, you must provide it as a query parameter: + +``` +PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z} +``` + +Example request using HTTP Basic authentication: + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/project.zip \ + https://gitea.example.com/api/packages/testuser/composer +``` + +Or specify the package version as query parameter: + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/project.zip \ + https://gitea.example.com/api/packages/testuser/composer?version=1.0.3 +``` + +If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. + +The server responds with the following HTTP Status codes. + +| HTTP Status Code | Meaning | +| ----------------- | ------- | +| `201 Created` | The package has been published. | +| `400 Bad Request` | The package name and/or version are invalid or a package with the same name and version already exist. | + +## Configuring the package registry + +To register the package registry you need to add it to the Composer `config.json` file (which can usually be found under `<user-home-dir>/.composer/config.json`): + +```json +{ + "repositories": [{ + "type": "composer", + "url": "https://gitea.example.com/api/packages/{owner}/composer" + } + ] +} +``` + +To access the package registry using credentials, you must specify them in the `auth.json` file as follows: + +```json +{ + "http-basic": { + "gitea.example.com": { + "username": "{username}", + "password": "{password}" + } + } +} +``` + +| Parameter | Description | +| ---------- | ----------- | +| `owner` | The owner of the package. | +| `username` | Your Gitea username. | +| `password` | Your Gitea password or a personal access token. | + +## Install a package + +To install a package from the package registry, execute the following command: + +```shell +composer require {package_name} +``` + +Optional you can specify the package version: + +```shell +composer require {package_name}:{package_version} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `package_name` | The package name. | +| `package_version` | The package version. | diff --git a/docs/content/doc/usage/packages/conan.en-us.md b/docs/content/doc/usage/packages/conan.en-us.md new file mode 100644 index 0000000000..8c8fe4e262 --- /dev/null +++ b/docs/content/doc/usage/packages/conan.en-us.md @@ -0,0 +1,102 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Conan Packages Repository" +slug: "conan" +weight: 20 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Conan" + weight: 20 + identifier: "conan" +--- + +# Conan Packages Repository + +Publish [Conan](https://conan.io/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Conan package registry, you need to use the [conan](https://conan.io/downloads.html) command line tool to consume and publish packages. + +## Configuring the package registry + +To register the package registry you need to configure a new Conan remote: + +```shell +conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan +conan user --remote {remote} --password {password} {username} +``` + +| Parameter | Description | +| -----------| ----------- | +| `remote` | The remote name. | +| `username` | Your Gitea username. | +| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | +| `owner` | The owner of the package. | + +For example: + +```shell +conan remote add gitea https://gitea.example.com/api/packages/testuser/conan +conan user --remote gitea --password password123 testuser +``` + +## Publish a package + +Publish a Conan package by running the following command: + +```shell +conan upload --remote={remote} {recipe} +``` + +| Parameter | Description | +| ----------| ----------- | +| `remote` | The remote name. | +| `recipe` | The recipe to upload. | + +For example: + +```shell +conan upload --remote=gitea ConanPackage/1.2@gitea/final +``` + +The Gitea Conan package registry has full [revision](https://docs.conan.io/en/latest/versioning/revisions.html) support. + +## Install a package + +To install a Conan package from the package registry, execute the following command: + +```shell +conan install --remote={remote} {recipe} +``` + +| Parameter | Description | +| ----------| ----------- | +| `remote` | The remote name. | +| `recipe` | The recipe to download. | + +For example: + +```shell +conan install --remote=gitea ConanPackage/1.2@gitea/final +``` + +## Supported commands + +``` +conan install +conan get +conan info +conan search +conan upload +conan user +conan download +conan remove +``` diff --git a/docs/content/doc/usage/packages/conda.en-us.md b/docs/content/doc/usage/packages/conda.en-us.md new file mode 100644 index 0000000000..c9a852239f --- /dev/null +++ b/docs/content/doc/usage/packages/conda.en-us.md @@ -0,0 +1,86 @@ +--- +date: "2022-12-28T00:00:00+00:00" +title: "Conda Packages Repository" +slug: "conda" +weight: 25 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Conda" + weight: 25 + identifier: "conda" +--- + +# Conda Packages Repository + +Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Conda package registry, you need to use [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html). + +## Configuring the package registry + +To register the package registry and provide credentials, edit your `.condarc` file: + +```yaml +channel_alias: https://gitea.example.com/api/packages/{owner}/conda +channels: + - https://gitea.example.com/api/packages/{owner}/conda +default_channels: + - https://gitea.example.com/api/packages/{owner}/conda +``` + +| Placeholder | Description | +| ------------ | ----------- | +| `owner` | The owner of the package. | + +See the [official documentation](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html) for explanations of the individual settings. + +If you need to provide credentials, you may embed them as part of the channel url (`https://user:password@gitea.example.com/...`). + +## Publish a package + +To publish a package, perform a HTTP PUT operation with the package content in the request body. + +``` +PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename} +``` + +| Placeholder | Description | +| ------------ | ----------- | +| `owner` | The owner of the package. | +| `channel` | The [channel](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html) of the package. (optional) | +| `filename` | The name of the file. | + +Example request using HTTP Basic authentication: + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/package-1.0.conda \ + https://gitea.example.com/api/packages/testuser/conda/package-1.0.conda +``` + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a package from the package registry, execute one of the following commands: + +```shell +conda install {package_name} +conda install {package_name}={package_version} +conda install -c {channel} {package_name} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `package_name` | The package name. | +| `package_version` | The package version. | +| `channel` | The channel of the package. (optional) | diff --git a/docs/content/doc/usage/packages/container.en-us.md b/docs/content/doc/usage/packages/container.en-us.md new file mode 100644 index 0000000000..457e6fb1a4 --- /dev/null +++ b/docs/content/doc/usage/packages/container.en-us.md @@ -0,0 +1,94 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Container Registry" +slug: "container" +weight: 30 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Container Registry" + weight: 30 + identifier: "container" +--- + +# Container Registry + +Publish [Open Container Initiative](https://opencontainers.org/) compliant images for your user or organization. +The container registry follows the OCI specs and supports all compatible images like [Docker](https://www.docker.com/) and [Helm Charts](https://helm.sh/). + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Container registry, you can use the tools for your specific image type. +The following examples use the `docker` client. + +## Login to the container registry + +To push an image or if the image is in a private registry, you have to authenticate: + +```shell +docker login gitea.example.com +``` + +If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. + +## Image naming convention + +Images must follow this naming convention: + +`{registry}/{owner}/{image}` + +For example, these are all valid image names for the owner `testuser`: + +`gitea.example.com/testuser/myimage` + +`gitea.example.com/testuser/my-image` + +`gitea.example.com/testuser/my/image` + +**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. + +## Push an image + +Push an image by executing the following command: + +```shell +docker push gitea.example.com/{owner}/{image}:{tag} +``` + +| Parameter | Description | +| ----------| ----------- | +| `owner` | The owner of the image. | +| `image` | The name of the image. | +| `tag` | The tag of the image. | + +For example: + +```shell +docker push gitea.example.com/testuser/myimage:latest +``` + +## Pull an image + +Pull an image by executing the following command: + +```shell +docker pull gitea.example.com/{owner}/{image}:{tag} +``` + +| Parameter | Description | +| ----------| ----------- | +| `owner` | The owner of the image. | +| `image` | The name of the image. | +| `tag` | The tag of the image. | + +For example: + +```shell +docker pull gitea.example.com/testuser/myimage:latest +``` diff --git a/docs/content/doc/usage/packages/generic.en-us.md b/docs/content/doc/usage/packages/generic.en-us.md new file mode 100644 index 0000000000..fbfe42d50a --- /dev/null +++ b/docs/content/doc/usage/packages/generic.en-us.md @@ -0,0 +1,148 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Generic Packages Repository" +slug: "generic" +weight: 40 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Generic" + weight: 40 + identifier: "generic" +--- + +# Generic Packages Repository + +Publish generic files, like release binaries or other output, for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Authenticate to the package registry + +To authenticate to the Package Registry, you need to provide [custom HTTP headers or use HTTP Basic authentication]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). + +## Publish a package + +To publish a generic package perform a HTTP PUT operation with the package content in the request body. +You cannot publish a file with the same name twice to a package. You must delete the existing package version first. + +``` +PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). | +| `package_version` | The package version, a non-empty string without trailing or leading whitespaces. | +| `file_name` | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). | + +Example request using HTTP Basic authentication: + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/file.bin \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin +``` + +If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. + +The server reponds with the following HTTP Status codes. + +| HTTP Status Code | Meaning | +| ----------------- | ------- | +| `201 Created` | The package has been published. | +| `400 Bad Request` | The package name and/or version and/or file name are invalid. | +| `409 Conflict` | A file with the same name exist already in the package. | + +## Download a package + +To download a generic package perform a HTTP GET operation. + +``` +GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | +| `package_version` | The package version. | +| `file_name` | The filename. | + +The file content is served in the response body. The response content type is `application/octet-stream`. + +Example request using HTTP Basic authentication: + +```shell +curl --user your_username:your_token_or_password \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin +``` + +The server reponds with the following HTTP Status codes. + +| HTTP Status Code | Meaning | +| ----------------- | ------- | +| `200 OK` | Success | +| `404 Not Found` | The package or file was not found. | + +## Delete a package + +To delete a generic package perform a HTTP DELETE operation. This will delete all files of this version. + +``` +DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | +| `package_version` | The package version. | + +Example request using HTTP Basic authentication: + +```shell +curl --user your_username:your_token_or_password -X DELETE \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0 +``` + +The server reponds with the following HTTP Status codes. + +| HTTP Status Code | Meaning | +| ----------------- | ------- | +| `204 No Content` | Success | +| `404 Not Found` | The package was not found. | + +## Delete a package file + +To delete a file of a generic package perform a HTTP DELETE operation. This will delete the package version too if there is no file left. + +``` +DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | +| `package_version` | The package version. | +| `filename` | The filename. | + +Example request using HTTP Basic authentication: + +```shell +curl --user your_username:your_token_or_password -X DELETE \ + https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin +``` + +The server reponds with the following HTTP Status codes. + +| HTTP Status Code | Meaning | +| ----------------- | ------- | +| `204 No Content` | Success | +| `404 Not Found` | The package or file was not found. | diff --git a/docs/content/doc/usage/packages/helm.en-us.md b/docs/content/doc/usage/packages/helm.en-us.md new file mode 100644 index 0000000000..1db1e8758b --- /dev/null +++ b/docs/content/doc/usage/packages/helm.en-us.md @@ -0,0 +1,68 @@ +--- +date: "2022-04-14T00:00:00+00:00" +title: "Helm Chart Registry" +slug: "helm" +weight: 50 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Helm" + weight: 50 + identifier: "helm" +--- + +# Helm Chart Registry + +Publish [Helm](https://helm.sh/) charts for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Helm Chart registry use a simple HTTP client like `curl` or the [`helm cm-push`](https://github.com/chartmuseum/helm-push/) plugin. + +## Publish a package + +Publish a package by running the following command: + +```shell +curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts +``` + +or with the `helm cm-push` plugin: + +```shell +helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm +helm cm-push ./{chart_file}.tgz {repo} +``` + +| Parameter | Description | +| ------------ | ----------- | +| `username` | Your Gitea username. | +| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | +| `repo` | The name for the repository. | +| `chart_file` | The Helm Chart archive. | +| `owner` | The owner of the package. | + +## Install a package + +To install a Helm char from the registry, execute the following command: + +```shell +helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm +helm repo update +helm install {name} {repo}/{chart} +``` + +| Parameter | Description | +| ---------- | ----------- | +| `username` | Your Gitea username. | +| `password` | Your Gitea password or a personal access token. | +| `repo` | The name for the repository. | +| `owner` | The owner of the package. | +| `name` | The local name. | +| `chart` | The name Helm Chart. | diff --git a/docs/content/doc/usage/packages/maven.en-us.md b/docs/content/doc/usage/packages/maven.en-us.md new file mode 100644 index 0000000000..81c3e22197 --- /dev/null +++ b/docs/content/doc/usage/packages/maven.en-us.md @@ -0,0 +1,167 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Maven Packages Repository" +slug: "maven" +weight: 60 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Maven" + weight: 60 + identifier: "maven" +--- + +# Maven Packages Repository + +Publish [Maven](https://maven.apache.org) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Maven package registry, you can use [Maven](https://maven.apache.org/install.html) or [Gradle](https://gradle.org/install/). +The following examples use `Maven` and `Gradle Groovy`. + +## Configuring the package registry + +To register the package registry you first need to add your access token to the [`settings.xml`](https://maven.apache.org/settings.html) file: + +```xml +<settings> + <servers> + <server> + <id>gitea</id> + <configuration> + <httpHeaders> + <property> + <name>Authorization</name> + <value>token {access_token}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> +``` + +Afterwards add the following sections to your project `pom.xml` file: + +```xml +<repositories> + <repository> + <id>gitea</id> + <url>https://gitea.example.com/api/packages/{owner}/maven</url> + </repository> +</repositories> +<distributionManagement> + <repository> + <id>gitea</id> + <url>https://gitea.example.com/api/packages/{owner}/maven</url> + </repository> + <snapshotRepository> + <id>gitea</id> + <url>https://gitea.example.com/api/packages/{owner}/maven</url> + </snapshotRepository> +</distributionManagement> +``` + +| Parameter | Description | +| -------------- | ----------- | +| `access_token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). | +| `owner` | The owner of the package. | + +### Gradle variant + +When you plan to add some packages from Gitea instance in your project, you should add it in repositories section: + +```groovy +repositories { + // other repositories + maven { url "https://gitea.example.com/api/packages/{owner}/maven" } +} +``` + +In Groovy gradle you may include next script in your publishing part: + +```groovy +publishing { + // other settings of publication + repositories { + maven { + name = "Gitea" + url = uri("https://gitea.example.com/api/packages/{owner}/maven") + + credentials(HttpHeaderCredentials) { + name = "Authorization" + value = "token {access_token}" + } + + authentication { + header(HttpHeaderAuthentication) + } + } + } +} +``` + +## Publish a package + +To publish a package simply run: + +```shell +mvn deploy +``` + +Or call `gradle` with task `publishAllPublicationsToGiteaRepository` in case you are using gradle: + +```groovy +./gradlew publishAllPublicationsToGiteaRepository +``` + +If you want to publish a prebuild package to the registry, you can use [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html): + +```shell +mvn deploy:deploy-file -Durl=https://gitea.example.com/api/packages/{owner}/maven -DrepositoryId=gitea -Dfile=/path/to/package.jar +``` + +| Parameter | Description | +| -------------- | ----------- | +| `owner` | The owner of the package. | + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a Maven package from the package registry, add a new dependency to your project `pom.xml` file: + +```xml +<dependency> + <groupId>com.test.package</groupId> + <artifactId>test_project</artifactId> + <version>1.0.0</version> +</dependency> +``` + +And analog in gradle groovy: + +```groovy +implementation "com.test.package:test_project:1.0.0" +``` + +Afterwards run: + +```shell +mvn install +``` + +## Supported commands + +``` +mvn install +mvn deploy +mvn dependency:get: +``` diff --git a/docs/content/doc/usage/packages/npm.en-us.md b/docs/content/doc/usage/packages/npm.en-us.md new file mode 100644 index 0000000000..a15cdb9a2b --- /dev/null +++ b/docs/content/doc/usage/packages/npm.en-us.md @@ -0,0 +1,145 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "npm Packages Repository" +slug: "npm" +weight: 70 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "npm" + weight: 70 + identifier: "npm" +--- + +# npm Packages Repository + +Publish [npm](https://www.npmjs.com/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the npm package registry, you need [Node.js](https://nodejs.org/en/download/) coupled with a package manager such as [Yarn](https://classic.yarnpkg.com/en/docs/install) or [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) itself. + +The registry supports [scoped](https://docs.npmjs.com/misc/scope/) and unscoped packages. + +The following examples use the `npm` tool with the scope `@test`. + +## Configuring the package registry + +To register the package registry you need to configure a new package source. + +```shell +npm config set {scope}:registry https://gitea.example.com/api/packages/{owner}/npm/ +npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{token}" +``` + +| Parameter | Description | +| ------------ | ----------- | +| `scope` | The scope of the packages. | +| `owner` | The owner of the package. | +| `token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). | + +For example: + +```shell +npm config set @test:registry https://gitea.example.com/api/packages/testuser/npm/ +npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" +``` + +or without scope: + +```shell +npm config set registry https://gitea.example.com/api/packages/testuser/npm/ +npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" +``` + +## Publish a package + +Publish a package by running the following command in your project: + +```shell +npm publish +``` + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Unpublish a package + +Delete a package by running the following command: + +```shell +npm unpublish {package_name}[@{package_version}] +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `package_name` | The package name. | +| `package_version` | The package version. | + +For example: + +```shell +npm unpublish @test/test_package +npm unpublish @test/test_package@1.0.0 +``` + +## Install a package + +To install a package from the package registry, execute the following command: + +```shell +npm install {package_name} +``` + +| Parameter | Description | +| -------------- | ----------- | +| `package_name` | The package name. | + +For example: + +```shell +npm install @test/test_package +``` + +## Tag a package + +The registry supports [version tags](https://docs.npmjs.com/adding-dist-tags-to-packages/) which can be managed by `npm dist-tag`: + +```shell +npm dist-tag add {package_name}@{version} {tag} +``` + +| Parameter | Description | +| -------------- | ----------- | +| `package_name` | The package name. | +| `version` | The version of the package. | +| `tag` | The tag name. | + +For example: + +```shell +npm dist-tag add test_package@1.0.2 release +``` + +The tag name must not be a valid version. All tag names which are parsable as a version are rejected. + +## Search packages + +The registry supports [searching](https://docs.npmjs.com/cli/v7/commands/npm-search/) but does not support special search qualifiers like `author:gitea`. + +## Supported commands + +``` +npm install +npm ci +npm publish +npm unpublish +npm dist-tag +npm view +npm search +``` diff --git a/docs/content/doc/usage/packages/nuget.en-us.md b/docs/content/doc/usage/packages/nuget.en-us.md new file mode 100644 index 0000000000..aa88fa625e --- /dev/null +++ b/docs/content/doc/usage/packages/nuget.en-us.md @@ -0,0 +1,119 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "NuGet Packages Repository" +slug: "nuget" +weight: 80 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "NuGet" + weight: 80 + identifier: "nuget" +--- + +# NuGet Packages Repository + +Publish [NuGet](https://www.nuget.org/) packages for your user or organization. The package registry supports the V2 and V3 API protocol and you can work with [NuGet Symbol Packages](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) too. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the NuGet package registry, you can use command-line interface tools as well as NuGet features in various IDEs like Visual Studio. +More information about NuGet clients can be found in [the official documentation](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools). +The following examples use the `dotnet nuget` tool. + +## Configuring the package registry + +To register the package registry you need to configure a new NuGet feed source: + +```shell +dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json +``` + +| Parameter | Description | +| ------------- | ----------- | +| `source_name` | The desired source name. | +| `username` | Your Gitea username. | +| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | +| `owner` | The owner of the package. | + +For example: + +```shell +dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json +``` + +You can add the source without credentials and use the [`--api-key`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-push) parameter when publishing packages. In this case you need to provide a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). + +## Publish a package + +Publish a package by running the following command: + +```shell +dotnet nuget push --source {source_name} {package_file} +``` + +| Parameter | Description | +| -------------- | ----------- | +| `source_name` | The desired source name. | +| `package_file` | Path to the package `.nupkg` file. | + +For example: + +```shell +dotnet nuget push --source gitea test_package.1.0.0.nupkg +``` + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +### Symbol Packages + +The NuGet package registry has build support for a symbol server. The PDB files embedded in a symbol package (`.snupkg`) can get requested by clients. +To do so, register the NuGet package registry as symbol source: + +``` +https://gitea.example.com/api/packages/{owner}/nuget/symbols +``` + +| Parameter | Description | +| --------- | ----------- | +| `owner` | The owner of the package registry. | + +For example: + +``` +https://gitea.example.com/api/packages/testuser/nuget/symbols +``` + +## Install a package + +To install a NuGet package from the package registry, execute the following command: + +```shell +dotnet add package --source {source_name} --version {package_version} {package_name} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `source_name` | The desired source name. | +| `package_name` | The package name. | +| `package_version` | The package version. | + +For example: + +```shell +dotnet add package --source gitea --version 1.0.0 test_package +``` + +## Supported commands + +``` +dotnet add +dotnet nuget push +dotnet nuget delete +``` diff --git a/docs/content/doc/usage/packages/overview.en-us.md b/docs/content/doc/usage/packages/overview.en-us.md new file mode 100644 index 0000000000..fdeaf15af0 --- /dev/null +++ b/docs/content/doc/usage/packages/overview.en-us.md @@ -0,0 +1,107 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Package Registry" +slug: "overview" +weight: 1 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Overview" + weight: 1 + identifier: "packages-overview" +--- + +# Package Registry + +Starting with Gitea **1.17**, the Package Registry can be used as a public or private registry for common package managers. + +**Table of Contents** + +{{< toc >}} + +## Supported package managers + +The following package managers are currently supported: + +| Name | Language | Package client | +| ---- | -------- | -------------- | +| [Cargo]({{< relref "doc/usage/packages/cargo.en-us.md" >}}) | Rust | `cargo` | +| [Chef]({{< relref "doc/usage/packages/chef.en-us.md" >}}) | - | `knife` | +| [Composer]({{< relref "doc/usage/packages/composer.en-us.md" >}}) | PHP | `composer` | +| [Conan]({{< relref "doc/usage/packages/conan.en-us.md" >}}) | C++ | `conan` | +| [Conda]({{< relref "doc/usage/packages/conda.en-us.md" >}}) | - | `conda` | +| [Container]({{< relref "doc/usage/packages/container.en-us.md" >}}) | - | any OCI compliant client | +| [Generic]({{< relref "doc/usage/packages/generic.en-us.md" >}}) | - | any HTTP client | +| [Helm]({{< relref "doc/usage/packages/helm.en-us.md" >}}) | - | any HTTP client, `cm-push` | +| [Maven]({{< relref "doc/usage/packages/maven.en-us.md" >}}) | Java | `mvn`, `gradle` | +| [npm]({{< relref "doc/usage/packages/npm.en-us.md" >}}) | JavaScript | `npm`, `yarn`, `pnpm` | +| [NuGet]({{< relref "doc/usage/packages/nuget.en-us.md" >}}) | .NET | `nuget` | +| [Pub]({{< relref "doc/usage/packages/pub.en-us.md" >}}) | Dart | `dart`, `flutter` | +| [PyPI]({{< relref "doc/usage/packages/pypi.en-us.md" >}}) | Python | `pip`, `twine` | +| [RubyGems]({{< relref "doc/usage/packages/rubygems.en-us.md" >}}) | Ruby | `gem`, `Bundler` | +| [Swift]({{< relref "doc/usage/packages/rubygems.en-us.md" >}}) | Swift | `swift` | +| [Vagrant]({{< relref "doc/usage/packages/vagrant.en-us.md" >}}) | - | `vagrant` | + +**The following paragraphs only apply if Packages are not globally disabled!** + +## Repository-Packages + +A package always belongs to an owner (a user or organisation), not a repository. +To link an (already uploaded) package to a repository, open the settings page +on that package and choose a repository to link this package to. +The entire package will be linked, not just a single version. + +Linking a package results in showing that package in the repository's package list, +and shows a link to the repository on the package site (as well as a link to the repository issues). + +## Access Restrictions + +| Package owner type | User | Organization | +|--------------------|------|--------------| +| **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only | +| **write** access | owner only | org members with admin or write access to the org | + +N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission. + +## Create or upload a package + +Depending on the type of package, use the respective package-manager for that. Check out the sub-page of a specific package manager for instructions. + +## View packages + +You can view the packages of a repository on the repository page. + +1. Go to the repository. +1. Go to **Packages** in the navigation bar. + +To view more details about a package, select the name of the package. + +## Download a package + +To download a package from your repository: + +1. Go to **Packages** in the navigation bar. +1. Select the name of the package to view the details. +1. In the **Assets** section, select the name of the package file you want to download. + +## Delete a package + +You cannot edit a package after you have published it in the Package Registry. Instead, you +must delete and recreate it. + +To delete a package from your repository: + +1. Go to **Packages** in the navigation bar. +1. Select the name of the package to view the details. +1. Click **Delete package** to permanently delete the package. + +## Disable the Package Registry + +The Package Registry is automatically enabled. To disable it for a single repository: + +1. Go to **Settings** in the navigation bar. +1. Disable **Enable Repository Packages Registry**. + +Previously published packages are not deleted by disabling the Package Registry. diff --git a/docs/content/doc/usage/packages/pub.en-us.md b/docs/content/doc/usage/packages/pub.en-us.md new file mode 100644 index 0000000000..f2df2016ac --- /dev/null +++ b/docs/content/doc/usage/packages/pub.en-us.md @@ -0,0 +1,84 @@ +--- +date: "2022-07-31T00:00:00+00:00" +title: "Pub Packages Repository" +slug: "pub" +weight: 90 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Pub" + weight: 90 + identifier: "pub" +--- + +# Pub Packages Repository + +Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Pub package registry, you need to use the tools [dart](https://dart.dev/tools/dart-tool) and/or [flutter](https://docs.flutter.dev/reference/flutter-cli). + +The following examples use dart. + +## Configuring the package registry + +To register the package registry and provide credentials, execute: + +```shell +dart pub token add https://gitea.example.com/api/packages/{owner}/pub +``` + +| Placeholder | Description | +| ------------ | ----------- | +| `owner` | The owner of the package. | + +You need to provide your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). + +## Publish a package + +To publish a package, edit the `pubspec.yaml` and add the following line: + +```yaml +publish_to: https://gitea.example.com/api/packages/{owner}/pub +``` + +| Placeholder | Description | +| ------------ | ----------- | +| `owner` | The owner of the package. | + +Now you can publish the package by running the following command: + +```shell +dart pub publish +``` + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a Pub package from the package registry, execute the following command: + +```shell +dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/ +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | + +For example: + +```shell +# use latest version +dart pub add mypackage --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ +# specify version +dart pub add mypackage:1.0.8 --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ +``` diff --git a/docs/content/doc/usage/packages/pypi.en-us.md b/docs/content/doc/usage/packages/pypi.en-us.md new file mode 100644 index 0000000000..84d9453daa --- /dev/null +++ b/docs/content/doc/usage/packages/pypi.en-us.md @@ -0,0 +1,88 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "PyPI Packages Repository" +slug: "pypi" +weight: 100 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "PyPI" + weight: 100 + identifier: "pypi" +--- + +# PyPI Packages Repository + +Publish [PyPI](https://pypi.org/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the PyPI package registry, you need to use the tools [pip](https://pypi.org/project/pip/) to consume and [twine](https://pypi.org/project/twine/) to publish packages. + +## Configuring the package registry + +To register the package registry you need to edit your local `~/.pypirc` file. Add + +```ini +[distutils] +index-servers = gitea + +[gitea] +repository = https://gitea.example.com/api/packages/{owner}/pypi +username = {username} +password = {password} +``` + +| Placeholder | Description | +| ------------ | ----------- | +| `owner` | The owner of the package. | +| `username` | Your Gitea username. | +| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | + +## Publish a package + +Publish a package by running the following command: + +```shell +python3 -m twine upload --repository gitea /path/to/files/* +``` + +The package files have the extensions `.tar.gz` and `.whl`. + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a PyPI package from the package registry, execute the following command: + +```shell +pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `username` | Your Gitea username. | +| `password` | Your Gitea password or a personal access token. | +| `owner` | The owner of the package. | +| `package_name` | The package name. | + +For example: + +```shell +pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package +``` + +You can use `--extra-index-url` instead of `--index-url` but that makes you vulnerable to dependency confusion attacks because `pip` checks the official PyPi repository for the package before it checks the specified custom repository. Read the `pip` docs for more information. + +## Supported commands + +``` +pip install +twine upload +``` diff --git a/docs/content/doc/usage/packages/rubygems.en-us.md b/docs/content/doc/usage/packages/rubygems.en-us.md new file mode 100644 index 0000000000..be60ed37af --- /dev/null +++ b/docs/content/doc/usage/packages/rubygems.en-us.md @@ -0,0 +1,128 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "RubyGems Packages Repository" +slug: "rubygems" +weight: 110 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "RubyGems" + weight: 110 + identifier: "rubygems" +--- + +# RubyGems Packages Repository + +Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the RubyGems package registry, you need to use the [gem](https://guides.rubygems.org/command-reference/) command line tool to consume and publish packages. + +## Configuring the package registry + +To register the package registry edit the `~/.gem/credentials` file and add: + +```ini +--- +https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token} +``` + +| Parameter | Description | +| ------------- | ----------- | +| `owner` | The owner of the package. | +| `token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). | + +For example: + +``` +--- +https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4 +``` + +## Publish a package + +Publish a package by running the following command: + +```shell +gem push --host {host} {package_file} +``` + +| Parameter | Description | +| -------------- | ----------- | +| `host` | URL to the package registry. | +| `package_file` | Path to the package `.gem` file. | + +For example: + +```shell +gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem +``` + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a package from the package registry you can use [Bundler](https://bundler.io) or `gem`. + +### Bundler + +Add a new `source` block to your `Gemfile`: + +``` +source "https://gitea.example.com/api/packages/{owner}/rubygems" do + gem "{package_name}" +end +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | + +For example: + +``` +source "https://gitea.example.com/api/packages/testuser/rubygems" do + gem "test_package" +end +``` + +Afterwards run the following command: + +```shell +bundle install +``` + +### gem + +Execute the following command: + +```shell +gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name} +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | + +For example: + +```shell +gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package +``` + +## Supported commands + +``` +gem install +bundle install +gem push +``` diff --git a/docs/content/doc/usage/packages/storage.en-us.md b/docs/content/doc/usage/packages/storage.en-us.md new file mode 100644 index 0000000000..15481ba7a3 --- /dev/null +++ b/docs/content/doc/usage/packages/storage.en-us.md @@ -0,0 +1,85 @@ +--- +date: "2022-11-01T00:00:00+00:00" +title: "Storage" +slug: "storage" +weight: 5 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Storage" + weight: 5 + identifier: "storage" +--- + +# Storage + +This document describes the storage of the package registry and how it can be managed. + +**Table of Contents** + +{{< toc >}} + +## Deduplication + +The package registry has a build-in deduplication of uploaded blobs. +If two identical files are uploaded only one blob is saved on the filesystem. +This ensures no space is wasted for duplicated files. + +If two packages are uploaded with identical files, both packages will display the same size but on the filesystem they require only half of the size. +Whenever a package gets deleted only the references to the underlaying blobs are removed. +The blobs get not removed at this moment, so they still require space on the filesystem. +When a new package gets uploaded the existing blobs may get referenced again. + +These unreferenced blobs get deleted by a [clean up job]({{< relref "doc/administration/config-cheat-sheet.en-us.md#cron---cleanup-expired-packages-croncleanup_packages" >}}). +The config setting `OLDER_THAN` configures how long unreferenced blobs are kept before they get deleted. + +## Cleanup Rules + +Package registries can become large over time without cleanup. +It's recommended to delete unnecessary packages and set up cleanup rules to automatically manage the package registry usage. +Every package owner (user or organization) manages the cleanup rules which are applied to their packages. + +|Setting|Description| +|-|-| +|Enabled|Turn the cleanup rule on or off.| +|Type|Every rule manages a specific package type.| +|Apply pattern to full package name|If enabled, the patterns below are applied to the full package name (`package/version`). Otherwise only the version (`version`) is used.| +|Keep the most recent|How many versions to *always* keep for each package.| +|Keep versions matching|The regex pattern that determines which versions to keep. An empty pattern keeps no version while `.+` keeps all versions. The container registry will always keep the `latest` version even if not configured.| +|Remove versions older than|Remove only versions older than the selected days.| +|Remove versions matching|The regex pattern that determines which versions to remove. An empty pattern or `.+` leads to the removal of every package if no other setting tells otherwise.| + +Every cleanup rule can show a preview of the affected packages. +This can be used to check if the cleanup rules is proper configured. + +### Regex examples + +Regex patterns are automatically surrounded with `\A` and `\z` anchors. +Do not include any `\A`, `\z`, `^` or `$` token in the regex patterns as they are not necessary. +The patterns are case-insensitive which matches the behaviour of the package registry in Gitea. + +|Pattern|Description| +|-|-| +|`.*`|Match every possible version.| +|`v.+`|Match versions that start with `v`.| +|`release`|Match only the version `release`.| +|`release.*`|Match versions that are either named or start with `release`.| +|`.+-temp-.+`|Match versions that contain `-temp-`.| +|`v.+\|release`|Match versions that either start with `v` or are named `release`.| +|`package/v.+\|other/release`|Match versions of the package `package` that start with `v` or the version `release` of the package `other`. This needs the setting *Apply pattern to full package name* enabled.| + +### How the cleanup rules work + +The cleanup rules are part of the [clean up job]({{< relref "doc/administration/config-cheat-sheet.en-us.md#cron---cleanup-expired-packages-croncleanup_packages" >}}) and run periodically. + +The cleanup rule: + +1. Collects all packages of the package type for the owners registry. +1. For every package it collects all versions. +1. Excludes from the list the # versions based on the *Keep the most recent* value. +1. Excludes from the list any versions matching the *Keep versions matching* value. +1. Excludes from the list the versions more recent than the *Remove versions older than* value. +1. Excludes from the list any versions not matching the *Remove versions matching* value. +1. Deletes the remaining versions. diff --git a/docs/content/doc/usage/packages/swift.en-us.md b/docs/content/doc/usage/packages/swift.en-us.md new file mode 100644 index 0000000000..a1c818021c --- /dev/null +++ b/docs/content/doc/usage/packages/swift.en-us.md @@ -0,0 +1,94 @@ +--- +date: "2023-01-10T00:00:00+00:00" +title: "Swift Packages Repository" +slug: "swift" +weight: 95 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Swift" + weight: 95 + identifier: "swift" +--- + +# Swift Packages Repository + +Publish [Swift](hhttps://www.swift.org/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Swift package registry, you need to use [swift](https://www.swift.org/getting-started/) to consume and a HTTP client (like `curl`) to publish packages. + +## Configuring the package registry + +To register the package registry and provide credentials, execute: + +```shell +swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password} +``` + +| Placeholder | Description | +| ------------ | ----------- | +| `owner` | The owner of the package. | +| `username` | Your Gitea username. | +| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | + +The login is optional and only needed if the package registry is private. + +## Publish a package + +First you have to pack the contents of your package: + +```shell +swift package archive-source +``` + +To publish the package perform a HTTP PUT request with the package content in the request body. + +```shell --user your_username:your_password_or_token \ +curl -X PUT --user {username}:{password} \ + -H "Accept: application/vnd.swift.registry.v1+json" \ + -F source-archive=@/path/to/package.zip \ + -F metadata={metadata} \ + https://gitea.example.com/api/packages/{owner}/swift/{scope}/{name}/{version} +``` + +| Placeholder | Description | +| ----------- | ----------- | +| `username` | Your Gitea username. | +| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | +| `owner` | The owner of the package. | +| `scope` | The package scope. | +| `name` | The package name. | +| `version` | The package version. | +| `metadata` | (Optional) The metadata of the package. JSON encoded subset of https://schema.org/SoftwareSourceCode | + +You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. + +## Install a package + +To install a Swift package from the package registry, add it in the `Package.swift` file dependencies list: + +``` +dependencies: [ + .package(id: "{scope}.{name}", from:"{version}") +] +``` + +| Parameter | Description | +| ----------- | ----------- | +| `scope` | The package scope. | +| `name` | The package name. | +| `version` | The package version. | + +Afterwards execute the following command to install it: + +```shell +swift package resolve +``` diff --git a/docs/content/doc/usage/packages/vagrant.en-us.md b/docs/content/doc/usage/packages/vagrant.en-us.md new file mode 100644 index 0000000000..5c633b4f71 --- /dev/null +++ b/docs/content/doc/usage/packages/vagrant.en-us.md @@ -0,0 +1,79 @@ +--- +date: "2022-08-23T00:00:00+00:00" +title: "Vagrant Packages Repository" +slug: "vagrant" +weight: 120 +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Vagrant" + weight: 120 + identifier: "vagrant" +--- + +# Vagrant Packages Repository + +Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization. + +**Table of Contents** + +{{< toc >}} + +## Requirements + +To work with the Vagrant package registry, you need [Vagrant](https://www.vagrantup.com/downloads) and a tool to make HTTP requests like `curl`. + +## Publish a package + +Publish a Vagrant box by performing a HTTP PUT request to the registry: + +``` +PUT https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box +``` + +| Parameter | Description | +| ----------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | +| `package_version` | The package version, semver compatible. | +| `provider` | One of the [supported provider names](https://www.vagrantup.com/docs/providers). | + +Example for uploading a Hyper-V box: + +```shell +curl --user your_username:your_password_or_token \ + --upload-file path/to/your/vagrant.box \ + https://gitea.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box +``` + +You cannot publish a box if a box of the same name, version and provider already exists. You must delete the existing package first. + +## Install a package + +To install a box from the package registry, execute the following command: + +```shell +vagrant box add "https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}" +``` + +| Parameter | Description | +| -------------- | ----------- | +| `owner` | The owner of the package. | +| `package_name` | The package name. | + +For example: + +```shell +vagrant box add "https://gitea.example.com/api/packages/testuser/vagrant/test_system" +``` + +This will install the latest version of the package. To add a specific version, use the `--box-version` parameter. +If the registry is private you can pass your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) in the `VAGRANT_CLOUD_TOKEN` environment variable. + +## Supported commands + +``` +vagrant box add +``` diff --git a/docs/content/doc/usage/permissions.en-us.md b/docs/content/doc/usage/permissions.en-us.md index 013dbfabd4..0778f6943f 100644 --- a/docs/content/doc/usage/permissions.en-us.md +++ b/docs/content/doc/usage/permissions.en-us.md @@ -5,6 +5,8 @@ slug: "permissions" weight: 14 toc: false draft: false +aliases: + - /en-us/permissions menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/protected-tags.en-us.md b/docs/content/doc/usage/protected-tags.en-us.md index f7404d32cb..c5e763659d 100644 --- a/docs/content/doc/usage/protected-tags.en-us.md +++ b/docs/content/doc/usage/protected-tags.en-us.md @@ -5,6 +5,8 @@ slug: "protected-tags" weight: 45 toc: false draft: false +aliases: + - /en-us/protected-tags menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/pull-request.en-us.md b/docs/content/doc/usage/pull-request.en-us.md index c7fea88a5a..feb8f848c9 100644 --- a/docs/content/doc/usage/pull-request.en-us.md +++ b/docs/content/doc/usage/pull-request.en-us.md @@ -5,6 +5,8 @@ slug: "pull-request" weight: 13 toc: false draft: false +aliases: + - /en-us/pull-request menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/pull-request.zh-cn.md b/docs/content/doc/usage/pull-request.zh-cn.md index 04125672df..d64690c05e 100644 --- a/docs/content/doc/usage/pull-request.zh-cn.md +++ b/docs/content/doc/usage/pull-request.zh-cn.md @@ -5,6 +5,8 @@ slug: "pull-request" weight: 13 toc: false draft: false +aliases: + - /zh-cn/pull-request menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/pull-request.zh-tw.md b/docs/content/doc/usage/pull-request.zh-tw.md index b666fece13..54cd178321 100644 --- a/docs/content/doc/usage/pull-request.zh-tw.md +++ b/docs/content/doc/usage/pull-request.zh-tw.md @@ -5,6 +5,8 @@ slug: "pull-request" weight: 13 toc: false draft: false +aliases: + - /zh-tw/pull-request menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/push.en-us.md b/docs/content/doc/usage/push.en-us.md index cf858e4e51..097b07c9b4 100644 --- a/docs/content/doc/usage/push.en-us.md +++ b/docs/content/doc/usage/push.en-us.md @@ -5,6 +5,9 @@ slug: "push" weight: 15 toc: false draft: false +aliases: + - /en-us/push-to-create + - /en-us/push-options menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/push.zh-tw.md b/docs/content/doc/usage/push.zh-tw.md index f97d4285cc..5fe5052c11 100644 --- a/docs/content/doc/usage/push.zh-tw.md +++ b/docs/content/doc/usage/push.zh-tw.md @@ -5,6 +5,8 @@ slug: "push" weight: 15 toc: false draft: false +aliases: + - /zh-tw/push-options menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/repo-mirror.en-us.md b/docs/content/doc/usage/repo-mirror.en-us.md index 9a52282bb3..5e2b5c3238 100644 --- a/docs/content/doc/usage/repo-mirror.en-us.md +++ b/docs/content/doc/usage/repo-mirror.en-us.md @@ -5,6 +5,8 @@ slug: "repo-mirror" weight: 45 toc: false draft: false +aliases: + - /en-us/repo-mirror menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/secrets.en-us.md b/docs/content/doc/usage/secrets.en-us.md index b45044cc33..c193a54a6c 100644 --- a/docs/content/doc/usage/secrets.en-us.md +++ b/docs/content/doc/usage/secrets.en-us.md @@ -1,10 +1,12 @@ --- date: "2022-12-19T21:26:00+08:00" title: "Secrets" -slug: "usage/secrets" +slug: "secrets" weight: 50 draft: false toc: false +aliases: + - /en-us/secrets menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/template-repositories.en-us.md b/docs/content/doc/usage/template-repositories.en-us.md index 9a2a23ed2b..0c278648b3 100644 --- a/docs/content/doc/usage/template-repositories.en-us.md +++ b/docs/content/doc/usage/template-repositories.en-us.md @@ -5,6 +5,8 @@ slug: "template-repositories" weight: 14 toc: false draft: false +aliases: + - /en-us/template-repositories menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/webhooks.en-us.md b/docs/content/doc/usage/webhooks.en-us.md index 457113c5cf..24cd48c919 100644 --- a/docs/content/doc/usage/webhooks.en-us.md +++ b/docs/content/doc/usage/webhooks.en-us.md @@ -5,6 +5,8 @@ slug: "webhooks" weight: 30 toc: false draft: false +aliases: + - /en-us/webhooks menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/webhooks.zh-cn.md b/docs/content/doc/usage/webhooks.zh-cn.md index 9e9f2bf502..44d97cc83f 100644 --- a/docs/content/doc/usage/webhooks.zh-cn.md +++ b/docs/content/doc/usage/webhooks.zh-cn.md @@ -5,6 +5,8 @@ slug: "webhooks" weight: 30 toc: false draft: false +aliases: + - /zh-cn/webhooks menu: sidebar: parent: "usage" diff --git a/docs/content/doc/usage/webhooks.zh-tw.md b/docs/content/doc/usage/webhooks.zh-tw.md index 9afad42369..ca5991354a 100644 --- a/docs/content/doc/usage/webhooks.zh-tw.md +++ b/docs/content/doc/usage/webhooks.zh-tw.md @@ -5,6 +5,8 @@ slug: "webhooks" weight: 30 toc: false draft: false +aliases: + - /zh-tw/webhooks menu: sidebar: parent: "usage" |