diff options
Diffstat (limited to 'docs/content')
| -rw-r--r-- | docs/content/doc/advanced/config-cheat-sheet.en-us.md | 15 | ||||
| -rw-r--r-- | docs/content/doc/developers.en-us.md | 2 | ||||
| -rw-r--r-- | docs/content/doc/developers.zh-tw.md | 2 | ||||
| -rw-r--r-- | docs/content/doc/features/comparison.en-us.md | 38 | ||||
| -rw-r--r-- | docs/content/doc/packages.en-us.md | 12 | ||||
| -rw-r--r-- | docs/content/doc/packages/composer.en-us.md | 120 | ||||
| -rw-r--r-- | docs/content/doc/packages/conan.en-us.md | 101 | ||||
| -rw-r--r-- | docs/content/doc/packages/container.en-us.md | 91 | ||||
| -rw-r--r-- | docs/content/doc/packages/generic.en-us.md | 80 | ||||
| -rw-r--r-- | docs/content/doc/packages/maven.en-us.md | 110 | ||||
| -rw-r--r-- | docs/content/doc/packages/npm.en-us.md | 118 | ||||
| -rw-r--r-- | docs/content/doc/packages/nuget.en-us.md | 116 | ||||
| -rw-r--r-- | docs/content/doc/packages/overview.en-us.md | 76 | ||||
| -rw-r--r-- | docs/content/doc/packages/pypi.en-us.md | 85 | ||||
| -rw-r--r-- | docs/content/doc/packages/rubygems.en-us.md | 127 | ||||
| -rw-r--r-- | docs/content/doc/translation.de-de.md | 2 | ||||
| -rw-r--r-- | docs/content/doc/translation.en-us.md | 2 | ||||
| -rw-r--r-- | docs/content/doc/translation.zh-tw.md | 2 |
18 files changed, 1074 insertions, 25 deletions
diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md index ae40e0954b..25247a6805 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -856,7 +856,7 @@ Default templates for project boards: - `RUN_AT_START`: **true**: Run repository statistics check at start time. - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check. -### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`) +#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`) - `ENABLED`: **true**: Enable cleanup hook_task job. - `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED). @@ -865,6 +865,14 @@ Default templates for project boards: - `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted. - `NUMBER_TO_KEEP`: **10**: If CLEANUP_TYPE is set to PerWebhook, this is number of hook_task records to keep for a webhook (i.e. keep the most recent x deliveries). +#### Cron - Cleanup expired packages (`cron.cleanup_packages`) + +- `ENABLED`: **true**: Enable cleanup expired packages job. +- `RUN_AT_START`: **true**: Run job at start time (if ENABLED). +- `NOTICE_ON_SUCCESS`: **false**: Notify every time this job runs. +- `SCHEDULE`: **@midnight**: Cron syntax for the job. +- `OLDER_THAN`: **24h**: Unreferenced package data created more than OLDER_THAN ago is subject to deletion. + #### Cron - Update Migration Poster ID (`cron.update_migration_poster_id`) - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts. @@ -1077,6 +1085,11 @@ Task queue configuration has been moved to `queue.task`. However, the below conf - `ENABLED`: **true**: Enable/Disable federation capabilities +## Packages (`packages`) + +- `ENABLED`: **true**: Enable/Disable package registry capabilities +- `CHUNKED_UPLOAD_PATH`: **tmp/package-upload**: Path for chunked uploads. Defaults to `APP_DATA_PATH` + `tmp/package-upload` + ## Mirror (`mirror`) - `ENABLED`: **true**: Enables the mirror functionality. Set to **false** to disable all mirrors. diff --git a/docs/content/doc/developers.en-us.md b/docs/content/doc/developers.en-us.md index c24a23dfae..917049e5df 100644 --- a/docs/content/doc/developers.en-us.md +++ b/docs/content/doc/developers.en-us.md @@ -8,6 +8,6 @@ draft: false menu: sidebar: name: "Developers" - weight: 50 + weight: 55 identifier: "developers" --- diff --git a/docs/content/doc/developers.zh-tw.md b/docs/content/doc/developers.zh-tw.md index e2fbd4a34f..c9ce6634ad 100644 --- a/docs/content/doc/developers.zh-tw.md +++ b/docs/content/doc/developers.zh-tw.md @@ -8,6 +8,6 @@ draft: false menu: sidebar: name: "開發人員" - weight: 50 + weight: 55 identifier: "developers" --- diff --git a/docs/content/doc/features/comparison.en-us.md b/docs/content/doc/features/comparison.en-us.md index 745c5d37bc..36180e3f5b 100644 --- a/docs/content/doc/features/comparison.en-us.md +++ b/docs/content/doc/features/comparison.en-us.md @@ -34,25 +34,25 @@ _Symbols used in table:_ ## General Features | Feature | Gitea | Gogs | GitHub EE | GitLab CE | GitLab EE | BitBucket | RhodeCode CE | -| ----------------------------------- | -------------------------------------------------- | ---- | --------- | --------- | --------- | -------------- | ------------ | -| Open source and free | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | -| Low resource usage (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | -| Multiple database support | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ | -| Multiple OS support | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | -| Easy upgrade process | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | -| Markdown support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Orgmode support | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ? | -| CSV support | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? | -| Third-party render tool support | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? | -| Static Git-powered pages | [✘](https://github.com/go-gitea/gitea/issues/302) | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Integrated Git-powered wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ | -| Deploy Tokens | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Repository Tokens with write rights | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Built-in Container Registry | [✘](https://github.com/go-gitea/gitea/issues/2316) | ✘ | ✘ | ✓ | ✓ | ✘ | ✘ | -| External git mirroring | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | -| WebAuthn (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ? | -| Built-in CI/CD | ✘ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | -| Subgroups: groups within groups | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ | +| ----------------------------------- | ---------------------------------------------------| ---- | --------- | --------- | --------- | -------------- | ------------ | +| Open source and free | ✓ | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | +| Low resource usage (RAM/CPU) | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✘ | +| Multiple database support | ✓ | ✓ | ✘ | ⁄ | ⁄ | ✓ | ✓ | +| Multiple OS support | ✓ | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | +| Easy upgrade process | ✓ | ✓ | ✘ | ✓ | ✓ | ✘ | ✓ | +| Markdown support | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Orgmode support | ✓ | ✘ | ✓ | ✘ | ✘ | ✘ | ? | +| CSV support | ✓ | ✘ | ✓ | ✘ | ✘ | ✓ | ? | +| Third-party render tool support | ✓ | ✘ | ✘ | ✘ | ✘ | ✓ | ? | +| Static Git-powered pages | [✘](https://github.com/go-gitea/gitea/issues/302) | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Integrated Git-powered wiki | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (cloud only) | ✘ | +| Deploy Tokens | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Repository Tokens with write rights | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Built-in Package/Container Registry | ✓ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| External git mirroring | ✓ | ✓ | ✘ | ✘ | ✓ | ✓ | ✓ | +| WebAuthn (2FA) | ✓ | ✘ | ✓ | ✓ | ✓ | ✓ | ? | +| Built-in CI/CD | ✘ | ✘ | ✓ | ✓ | ✓ | ✘ | ✘ | +| Subgroups: groups within groups | ✘ | ✘ | ✘ | ✓ | ✓ | ✘ | ✓ | ## Code management diff --git a/docs/content/doc/packages.en-us.md b/docs/content/doc/packages.en-us.md new file mode 100644 index 0000000000..e613b6b250 --- /dev/null +++ b/docs/content/doc/packages.en-us.md @@ -0,0 +1,12 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Package Registry" +slug: "packages" +toc: false +draft: false +menu: + sidebar: + name: "Package Registry" + weight: 45 + identifier: "packages" +--- diff --git a/docs/content/doc/packages/composer.en-us.md b/docs/content/doc/packages/composer.en-us.md new file mode 100644 index 0000000000..2502ee45b5 --- /dev/null +++ b/docs/content/doc/packages/composer.en-us.md @@ -0,0 +1,120 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Composer Packages Repository" +slug: "packages/composer" +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 +``` + +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/packages/conan.en-us.md b/docs/content/doc/packages/conan.en-us.md new file mode 100644 index 0000000000..c650e9d7ea --- /dev/null +++ b/docs/content/doc/packages/conan.en-us.md @@ -0,0 +1,101 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Conan Packages Repository" +slug: "packages/conan" +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 or a personal access token. | +| `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/packages/container.en-us.md b/docs/content/doc/packages/container.en-us.md new file mode 100644 index 0000000000..28559eb22b --- /dev/null +++ b/docs/content/doc/packages/container.en-us.md @@ -0,0 +1,91 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Container Registry" +slug: "packages/container" +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 +``` + +## 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/packages/generic.en-us.md b/docs/content/doc/packages/generic.en-us.md new file mode 100644 index 0000000000..afef323938 --- /dev/null +++ b/docs/content/doc/packages/generic.en-us.md @@ -0,0 +1,80 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Generic Packages Repository" +slug: "packages/generic" +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/developers/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 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}/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 (`-`), or underscores (`_`). | +| `package_version` | The package version as described in the [SemVer](https://semver.org/) spec. | +| `file_name` | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), 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 +``` + +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 are invalid or a package with the same name and version already exist. | + +## 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 +``` diff --git a/docs/content/doc/packages/maven.en-us.md b/docs/content/doc/packages/maven.en-us.md new file mode 100644 index 0000000000..78288a9e42 --- /dev/null +++ b/docs/content/doc/packages/maven.en-us.md @@ -0,0 +1,110 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Maven Packages Repository" +slug: "packages/maven" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Maven" + weight: 50 + 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`. + +## 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/developers/api-usage.en-us.md#authentication" >}}). | +| `owner` | The owner of the package. | + +## Publish a package + +To publish a package simply run: + +```shell +mvn deploy +``` + +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> +``` + +Afterwards run: + +```shell +mvn install +``` + +## Supported commands + +``` +mvn install +mvn deploy +mvn dependency:get: +```
\ No newline at end of file diff --git a/docs/content/doc/packages/npm.en-us.md b/docs/content/doc/packages/npm.en-us.md new file mode 100644 index 0000000000..28b7cb8827 --- /dev/null +++ b/docs/content/doc/packages/npm.en-us.md @@ -0,0 +1,118 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "npm Packages Repository" +slug: "packages/npm" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "npm" + weight: 60 + 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/developers/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. + +## 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. + +## Supported commands + +``` +npm install +npm ci +npm publish +npm dist-tag +npm view +``` diff --git a/docs/content/doc/packages/nuget.en-us.md b/docs/content/doc/packages/nuget.en-us.md new file mode 100644 index 0000000000..5565bf5b89 --- /dev/null +++ b/docs/content/doc/packages/nuget.en-us.md @@ -0,0 +1,116 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "NuGet Packages Repository" +slug: "packages/nuget" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "NuGet" + weight: 70 + identifier: "nuget" +--- + +# NuGet Packages Repository + +Publish [NuGet](https://www.nuget.org/) packages for your user or organization. The package registry supports [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 informations 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 or a personal access token. | +| `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 +``` + +## 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/packages/overview.en-us.md b/docs/content/doc/packages/overview.en-us.md new file mode 100644 index 0000000000..f7809fc8a3 --- /dev/null +++ b/docs/content/doc/packages/overview.en-us.md @@ -0,0 +1,76 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "Package Registry" +slug: "packages/overview" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "Overview" + weight: 1 + identifier: "overview" +--- + +# Package Registry + +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 | +| ---- | -------- | -------------- | +| [Composer]({{< relref "doc/packages/composer.en-us.md" >}}) | PHP | `composer` | +| [Conan]({{< relref "doc/packages/conan.en-us.md" >}}) | C++ | `conan` | +| [Container]({{< relref "doc/packages/container.en-us.md" >}}) | - | any OCI compliant client | +| [Generic]({{< relref "doc/packages/generic.en-us.md" >}}) | - | any HTTP client | +| [Maven]({{< relref "doc/packages/maven.en-us.md" >}}) | Java | `mvn`, `gradle` | +| [npm]({{< relref "doc/packages/npm.en-us.md" >}}) | JavaScript | `npm`, `yarn` | +| [NuGet]({{< relref "doc/packages/nuget.en-us.md" >}}) | .NET | `nuget` | +| [PyPI]({{< relref "doc/packages/pypi.en-us.md" >}}) | Python | `pip`, `twine` | +| [RubyGems]({{< relref "doc/packages/rubygems.en-us.md" >}}) | Ruby | `gem`, `Bundler` | + +**The following paragraphs only apply if Packages are not globally disabled!** + +## 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 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/packages/pypi.en-us.md b/docs/content/doc/packages/pypi.en-us.md new file mode 100644 index 0000000000..1d7a8f22e8 --- /dev/null +++ b/docs/content/doc/packages/pypi.en-us.md @@ -0,0 +1,85 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "PyPI Packages Repository" +slug: "packages/pypi" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "PyPI" + weight: 80 + 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 or a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). | + +## 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 +``` + +## Supported commands + +``` +pip install +twine upload +```
\ No newline at end of file diff --git a/docs/content/doc/packages/rubygems.en-us.md b/docs/content/doc/packages/rubygems.en-us.md new file mode 100644 index 0000000000..603e925e32 --- /dev/null +++ b/docs/content/doc/packages/rubygems.en-us.md @@ -0,0 +1,127 @@ +--- +date: "2021-07-20T00:00:00+00:00" +title: "RubyGems Packages Repository" +slug: "packages/rubygems" +draft: false +toc: false +menu: + sidebar: + parent: "packages" + name: "RubyGems" + weight: 90 + 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. | + +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 +```
\ No newline at end of file diff --git a/docs/content/doc/translation.de-de.md b/docs/content/doc/translation.de-de.md index 585783a706..3470faa59b 100644 --- a/docs/content/doc/translation.de-de.md +++ b/docs/content/doc/translation.de-de.md @@ -8,6 +8,6 @@ draft: false menu: sidebar: name: "Übersetzung" - weight: 45 + weight: 50 identifier: "translation" --- diff --git a/docs/content/doc/translation.en-us.md b/docs/content/doc/translation.en-us.md index 208eb32ab8..c281088503 100644 --- a/docs/content/doc/translation.en-us.md +++ b/docs/content/doc/translation.en-us.md @@ -8,6 +8,6 @@ draft: false menu: sidebar: name: "Translation" - weight: 45 + weight: 50 identifier: "translation" --- diff --git a/docs/content/doc/translation.zh-tw.md b/docs/content/doc/translation.zh-tw.md index ca820c093c..5374e87e89 100644 --- a/docs/content/doc/translation.zh-tw.md +++ b/docs/content/doc/translation.zh-tw.md @@ -8,6 +8,6 @@ draft: false menu: sidebar: name: "翻譯" - weight: 45 + weight: 50 identifier: "translation" --- |