gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-07 14:09:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add 1.25.0 documentation (#289)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/289
This commit is contained in:
Lunny Xiao
2025-11-01 06:48:53 +00:00
parent d5eac4f23d
commit 7d50e32ba8
112 changed files with 49039 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
versioned_docs/version-1.25/usage/packages/alpine.md Normal file
View File

@@ -0,0 +1,122 @@
---
date: "2023-03-25T00:00:00+00:00"
slug: "alpine"
sidebar_position: 4
---
# Alpine Package Registry
Publish [Alpine](https://pkgs.alpinelinux.org/) packages for your user or organization.
## Requirements
To work with the Alpine registry, you need to use a HTTP client like `curl` to upload and a package manager like `apk` to consume packages.
The following examples use `apk`.
## Configuring the package registry
To register the Alpine registry add the url to the list of known apk sources (`/etc/apk/repositories`):
```
https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the packages. |
| `branch` | The branch to use. |
| `repository` | The repository to use. |
If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
```
https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
```
The Alpine registry files are signed with a RSA key which must be known to apk. Download the public key and store it in `/etc/apk/keys/`:
```shell
curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key
```
Afterwards update the local package index:
```shell
apk update
```
## Publish a package
To publish an Alpine package (`*.apk`), perform a HTTP `PUT` operation with the package content in the request body.
```
PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}
```
| Parameter | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
| `branch` | The branch may match the release version of the OS, ex: `v3.17`. |
| `repository` | The repository can be used [to group packages](https://wiki.alpinelinux.org/wiki/Repositories) or just `main` or similar. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.apk \
https://gitea.example.com/api/packages/testuser/alpine/v3.17/main
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a file with the same name twice to a package. You must delete the existing package file first.
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, version, branch, repository or architecture are invalid. |
| `409 Conflict` | A package file with the same combination of parameters exist already in the package. |
## Delete a package
To delete an Alpine 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}/alpine/{branch}/{repository}/{architecture}/{filename}
```
| Parameter | Description |
| -------------- | ----------- |
| `owner` | The owner of the package. |
| `branch` | The branch to use. |
| `repository` | The repository to use. |
| `architecture` | The package architecture. |
| `filename` | The file to delete. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk
```
The server responds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |
## Install a package
To install a package from the Alpine registry, execute the following commands:
```shell
# use latest version
apk add {package_name}
# use specific version
apk add {package_name}={package_version}
```

132
versioned_docs/version-1.25/usage/packages/arch.md Normal file
View File

@@ -0,0 +1,132 @@
---
date: "2023-05-15T00:00:00+00:00"
slug: "arch"
sidebar_position: 5
---
# Arch package registry
Publish [Arch](https://archlinux.org/packages/) packages for your user or organization. The registry can act as a fully working [Arch linux mirror](https://wiki.archlinux.org/title/mirrors) connected directly in `/etc/pacman.conf`.
## Requirements
To work with the Arch registry, you need to use a HTTP client like `curl` to upload and a package manager like `pacman` to consume packages.
The following examples use `pacman`.
## Configuring the package registry
Before you can use the package registry, you need to download the package verification key and add the registry to the pacman config.
Download the package verification key.
```sh
wget https://gitea.example.com/api/packages/{owner}/arch/repository.key
```
Display the id the key (the long line with hex characters).
```sh
gpg --show-keys repository.key
```
Add the key to pacman and sign it (use the key id from the previous step).
```sh
pacman-key --add repository.key
pacman-key --lsign-key {key id}
```
Now add the registry configuration to `/etc/pacman.conf`.
```conf
[{owner}.gitea.example.com]
SigLevel = Required
Server = https://gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
```
| Placeholder | Description |
| -------------- | ----------- |
| `owner` | The owner of the packages. |
| `repository` | The repository to use. |
| `architecture` | The architecture to use. |
Consult the owners package overview to see what `repository` and `architecture` is available.
If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
```
Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
```
## Publish a package
To publish an Arch package, perform a HTTP `PUT` operation with the package content in the request body.
```
PUT https://gitea.example.com/api/packages/{owner}/arch/{repository}
```
| Parameter | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
| `repository` | The repository can be used to group packages or just `core` or similar. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.pkg.tar.zst \
https://gitea.example.com/api/packages/testuser/arch/core
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a file with the same name twice to a package. You must delete the existing package file first.
The server responds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `201 Created` | The package has been published. |
| `400 Bad Request` | Something of the package is invalid. The error message contains more information. |
| `409 Conflict` | A package file with the same combination of parameters exist already in the package. |
## Install packages
To install a package run the pacman sync command:
```sh
pacman -Sy {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| `package_name` | The package name. |
## Delete a package
To delete an Arch 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}/arch/{repository}/{package_name}/{package_version}/{architecture}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `repository` | The repository to use. |
| `architecture` | The package architecture. |
| `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/arch/core/test-package/1.0.0/x86-64
```
The server responds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |

104
versioned_docs/version-1.25/usage/packages/cargo.md Normal file
View File

@@ -0,0 +1,104 @@
---
date: "2022-11-20T00:00:00+00:00"
slug: "cargo"
sidebar_position: 5
---
# Cargo Package Registry
Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization.
## Requirements
To work with the Cargo package registry, you need [Rust and Cargo](https://www.rust-lang.org/tools/install).
Cargo stores information 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 information 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 = "sparse+https://gitea.example.com/api/packages/{owner}/cargo/" # Sparse index
# index = "https://gitea.example.com/{owner}/_cargo-index.git" # 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](development/api-usage.md#authentication) |
## Git vs Sparse
Currently, cargo supports two ways for fetching crates in a registry: Git index & sparse index.
Sparse index is the newest method and offers better performance when updating crates compared to git.
Since Rust 1.68, sparse is the default method for crates.io.
## 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
```

84
versioned_docs/version-1.25/usage/packages/chef.md Normal file
View File

@@ -0,0 +1,84 @@
---
date: "2023-01-20T00:00:00+00:00"
slug: "chef"
sidebar_position: 10
---
# Chef Package Registry
Publish [Chef](https://chef.io/) cookbooks for your user or organization.
## 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. |

112
versioned_docs/version-1.25/usage/packages/composer.md Normal file
View File

@@ -0,0 +1,112 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "composer"
sidebar_position: 15
---
# Composer Package Registry
Publish [Composer](https://getcomposer.org/) packages for your user or organization.
## 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](development/api-usage.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 is invalid. |
| `409 Conflict` | A package file with the same combination of parameters exists already. |
## 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. |

91
versioned_docs/version-1.25/usage/packages/conan.md Normal file
View File

@@ -0,0 +1,91 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "conan"
sidebar_position: 20
---
# Conan Package Registry
Publish [Conan](https://conan.io/) packages for your user or organization.
## 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](development/api-usage.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
```
You cannot publish a file with the same name twice to a package. You must delete the existing package or file first.
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
```

83
versioned_docs/version-1.25/usage/packages/conda.md Normal file
View File

@@ -0,0 +1,83 @@
---
date: "2022-12-28T00:00:00+00:00"
slug: "conda"
sidebar_position: 25
---
# Conda Package Registry
Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization.
## 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
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
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 is invalid. |
| `409 Conflict` | A package file with the same combination of parameters exists already. |
## 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) |

93
versioned_docs/version-1.25/usage/packages/container.md Normal file
View File

@@ -0,0 +1,93 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "container"
sidebar_position: 30
---
# 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/).
## 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](development/api-usage.md#authentication) instead of the password.
## Image naming convention
Images must follow this naming convention:
`{registry}/{owner}/{image}`
When building your docker image, using the naming convention above, this looks like:
```shell
# build an image with tag
docker build -t {registry}/{owner}/{image}:{tag} .
# name an existing image with tag
docker tag {some-existing-image}:{tag} {registry}/{owner}/{image}:{tag}
```
where your registry is the domain of your gitea instance (e.g. gitea.example.com).
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
```

91
versioned_docs/version-1.25/usage/packages/cran.md Normal file
View File

@@ -0,0 +1,91 @@
---
date: "2023-01-01T00:00:00+00:00"
slug: "cran"
sidebar_position: 35
---
# CRAN Package Registry
Publish [R](https://www.r-project.org/) packages to a [CRAN](https://cran.r-project.org/)-like registry for your user or organization.
## Requirements
To work with the CRAN package registry, you need to install [R](https://cran.r-project.org/).
## Configuring the package registry
To register the package registry you need to add it to `Rprofile.site`, either on the system-level, user-level (`~/.Rprofile`) or project-level:
```
options("repos" = c(getOption("repos"), c(gitea="https://gitea.example.com/api/packages/{owner}/cran")))
```
| Parameter | Description |
| --------- | ----------- |
| `owner` | The owner of the package. |
If you need to provide credentials, you may embed them as part of the url (`https://user:password@gitea.example.com/...`).
## Publish a package
To publish a R package, perform a HTTP `PUT` operation with the package content in the request body.
Source packages:
```
PUT https://gitea.example.com/api/packages/{owner}/cran/src
```
| Parameter | Description |
| --------- | ----------- |
| `owner` | The owner of the package. |
Binary packages:
```
PUT https://gitea.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion}
```
| Parameter | Description |
| ---------- | ----------- |
| `owner` | The owner of the package. |
| `platform` | The name of the platform. |
| `rversion` | The R version of the binary. |
For example:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/package.zip \
https://gitea.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
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 is invalid. |
| `409 Conflict` | A package file with the same combination of parameters exists already. |
## Install a package
To install a R package from the package registry, execute the following command:
```shell
install.packages("{package_name}")
```
| Parameter | Description |
| -------------- | ----------- |
| `package_name` | The package name. |
For example:
```shell
install.packages("testpackage")
```

123
versioned_docs/version-1.25/usage/packages/debian.md Normal file
View File

@@ -0,0 +1,123 @@
---
date: "2023-01-07T00:00:00+00:00"
slug: "debian"
sidebar_position: 40
---
# Debian Package Registry
Publish [Debian](https://www.debian.org/distrib/packages) packages for your user or organization.
## Requirements
To work with the Debian registry, you need to use a HTTP client like `curl` to upload and a package manager like `apt` to consume packages.
The following examples use `apt`.
## Configuring the package registry
To register the Debian registry add the url to the list of known apt sources:
```shell
echo "deb [signed-by=/etc/apt/keyrings/gitea-{owner}.asc] https://gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
```
| Placeholder | Description |
| -------------- | ----------- |
| `owner` | The owner of the package. |
| `distribution` | The distribution to use. |
| `component` | The component to use. |
If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
```shell
echo "deb [signed-by=/etc/apt/keyrings/gitea-{owner}.asc] https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list
```
The Debian registry files are signed with a PGP key which must be known to apt:
```shell
sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/keyrings/gitea-{owner}.asc
```
Afterwards update the local package index:
```shell
apt update
```
## Publish a package
To publish a Debian package (`*.deb`), perform a HTTP `PUT` operation with the package content in the request body.
```
PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload
```
| Parameter | Description |
| -------------- | ----------- |
| `owner` | The owner of the package. |
| `distribution` | The distribution may match the release name of the OS, ex: `bionic`. |
| `component` | The component can be used to group packages or just `main` or similar. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.deb \
https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/upload
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a package if a package of the same name, version, distribution, component and architecture already exists. You must delete the existing package first.
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 is invalid. |
| `409 Conflict` | A package file with the same combination of parameters exists already. |
## Delete a package
To delete a Debian 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}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `distribution` | The package distribution. |
| `component` | The package component. |
| `architecture` | The package architecture. |
Example request using HTTP Basic authentication:
```shell
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/test-package/1.0.0/amd64
```
The server responds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |
## Install a package
To install a package from the Debian registry, execute the following commands:
```shell
# use latest version
apt install {package_name}
# use specific version
apt install {package_name}={package_version}
```

135
versioned_docs/version-1.25/usage/packages/generic.md Normal file
View File

@@ -0,0 +1,135 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "generic"
sidebar_position: 500
---
# Generic Package Registry
Publish generic files, like release binaries or other output, for your user or organization.
## Authenticate to the package registry
To authenticate to the Package Registry, you need to provide [custom HTTP headers or use HTTP Basic authentication](development/api-usage.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](development/api-usage.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 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 responds 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 responds 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 responds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |

66
versioned_docs/version-1.25/usage/packages/go.md Normal file
View File

@@ -0,0 +1,66 @@
---
date: "2023-05-10T00:00:00+00:00"
slug: "go"
sidebar_position: 45
---
# Go Package Registry
Publish Go packages for your user or organization.
## Publish a package
To publish a Go 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.
The package must follow the [documented structure](https://go.dev/ref/mod#zip-files).
```
PUT https://gitea.example.com/api/packages/{owner}/go/upload
```
| Parameter | Description |
| --------- | ----------- |
| `owner` | The owner of the package. |
To authenticate to the package registry, you need to provide [custom HTTP headers or use HTTP Basic authentication](development/api-usage.md#authentication):
```shell
curl --user your_username:your_password_or_token \
--upload-file path/to/file.zip \
https://gitea.example.com/api/packages/testuser/go/upload
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
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 is invalid. |
| `409 Conflict` | A package with the same name exist already. |
## Install a package
To install a Go package instruct Go to use the package registry as proxy:
```shell
# use latest version
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}
# or
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest
# use specific version
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
If the owner of the packages is private you need to [provide credentials](https://go.dev/ref/mod#private-module-proxy-auth).
More information about the `GOPROXY` environment variable and how to protect against data leaks can be found in [the documentation](https://go.dev/ref/mod#private-modules).

55
versioned_docs/version-1.25/usage/packages/helm.md Normal file
View File

@@ -0,0 +1,55 @@
---
date: "2022-04-14T00:00:00+00:00"
slug: "helm"
sidebar_position: 50
---
# Helm Chart Registry
Publish [Helm](https://helm.sh/) charts for your user or organization.
## 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](development/api-usage.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. |

154
versioned_docs/version-1.25/usage/packages/maven.md Normal file
View File

@@ -0,0 +1,154 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "maven"
sidebar_position: 60
---
# Maven Package Registry
Publish [Maven](https://maven.apache.org) packages for your user or organization.
## 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](development/api-usage.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:
```

132
versioned_docs/version-1.25/usage/packages/npm.md Normal file
View File

@@ -0,0 +1,132 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "npm"
sidebar_position: 70
---
# NPM Package Registry
Publish [npm](https://www.npmjs.com/) packages for your user or organization.
## 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](development/api-usage.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
```

106
versioned_docs/version-1.25/usage/packages/nuget.md Normal file
View File

@@ -0,0 +1,106 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "nuget"
sidebar_position: 80
---
# NuGet Package Registry
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.
## 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](development/api-usage.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](development/api-usage.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
```

100
versioned_docs/version-1.25/usage/packages/overview.md Normal file
View File

@@ -0,0 +1,100 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "overview"
sidebar_position: 1
---
# Overview
Starting with Gitea **1.17**, the Package Registry can be used as a public or private registry for common package managers.
## Supported package managers
The following package managers are currently supported:
| Name | Language | Package client |
| ---- | -------- | -------------- |
| [Alpine](usage/packages/alpine.md) | - | `apk` |
| [Arch](usage/packages/arch.md) | - | `pacman` |
| [Cargo](usage/packages/cargo.md) | Rust | `cargo` |
| [Chef](usage/packages/chef.md) | - | `knife` |
| [Composer](usage/packages/composer.md) | PHP | `composer` |
| [Conan](usage/packages/conan.md) | C++ | `conan` |
| [Conda](usage/packages/conda.md) | - | `conda` |
| [Container](usage/packages/container.md) | - | any OCI compliant client |
| [CRAN](usage/packages/cran.md) | R | - |
| [Debian](usage/packages/debian.md) | - | `apt` |
| [Generic](usage/packages/generic.md) | - | any HTTP client |
| [Go](usage/packages/go.md) | Go | `go` |
| [Helm](usage/packages/helm.md) | - | any HTTP client, `cm-push` |
| [Maven](usage/packages/maven.md) | Java | `mvn`, `gradle` |
| [npm](usage/packages/npm.md) | JavaScript | `npm`, `yarn`, `pnpm` |
| [NuGet](usage/packages/nuget.md) | .NET | `nuget` |
| [Pub](usage/packages/pub.md) | Dart | `dart`, `flutter` |
| [PyPI](usage/packages/pypi.md) | Python | `pip`, `twine` |
| [RPM](usage/packages/rpm.md) | - | `yum`, `dnf`, `zypper` |
| [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` |
| [Swift](usage/packages/swift.md) | Swift | `swift` |
| [Vagrant](usage/packages/vagrant.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.

71
versioned_docs/version-1.25/usage/packages/pub.md Normal file
View File

@@ -0,0 +1,71 @@
---
date: "2022-07-31T00:00:00+00:00"
slug: "pub"
sidebar_position: 90
---
# Pub Package Registry
Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization.
## 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](development/api-usage.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/
```

75
versioned_docs/version-1.25/usage/packages/pypi.md Normal file
View File

@@ -0,0 +1,75 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "pypi"
sidebar_position: 100
---
# PyPI Package Registry
Publish [PyPI](https://pypi.org/) packages for your user or organization.
## 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](development/api-usage.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
```

130
versioned_docs/version-1.25/usage/packages/rpm.md Normal file
View File

@@ -0,0 +1,130 @@
---
date: "2023-03-08T00:00:00+00:00"
slug: "rpm"
sidebar_position: 105
---
# RPM Package Registry
Publish [RPM](https://rpm.org/) packages for your user or organization.
## Requirements
To work with the RPM registry, you need to use a package manager like `yum`, `dnf` or `zypper` to consume packages.
The following examples use `dnf`.
## Configuring the package registry
To register the RPM registry add the url to the list of known sources:
```shell
dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm/{group}.repo
```
| Placeholder | Description |
| ----------- | ----------- |
| `owner` | The owner of the package. |
| `group` | Optional: Everything, e.g. empty, `el7`, `rocky/el9`, `test/fc38`. |
Example:
```shell
# without a group
dnf config-manager --add-repo https://gitea.example.com/api/packages/testuser/rpm.repo
# with the group 'centos/el7'
dnf config-manager --add-repo https://gitea.example.com/api/packages/testuser/rpm/centos/el7.repo
```
If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
```shell
dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm/{group}.repo
```
You have to add the credentials to the urls in the created `.repo` file in `/etc/yum.repos.d` too.
## Publish a package
To publish a RPM package (`*.rpm`), perform a HTTP PUT operation with the package content in the request body.
```
PUT https://gitea.example.com/api/packages/{owner}/rpm/{group}/upload
```
| Parameter | Description |
| --------- | ----------- |
| `owner` | The owner of the package. |
| `group` | Optional: Everything, e.g. empty, `el7`, `rocky/el9`, `test/fc38`. |
Example request using HTTP Basic authentication:
```shell
# without a group
curl --user your_username:your_password_or_token \
--upload-file path/to/file.rpm \
https://gitea.example.com/api/packages/testuser/rpm/upload
# with the group 'centos/el7'
curl --user your_username:your_password_or_token \
--upload-file path/to/file.rpm \
https://gitea.example.com/api/packages/testuser/rpm/centos/el7/upload
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a file with the same name twice to a package. You must delete the existing package version first.
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 is invalid. |
| `409 Conflict` | A package file with the same combination of parameters exist already in the package. |
## Delete a package
To delete an RPM 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}/rpm/{group}/package/{package_name}/{package_version}/{architecture}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `group` | Optional: The package group. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `architecture` | The package architecture. |
Example request using HTTP Basic authentication:
```shell
# without a group
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/rpm/package/test-package/1.0.0/x86_64
# with the group 'centos/el7'
curl --user your_username:your_token_or_password -X DELETE \
https://gitea.example.com/api/packages/testuser/rpm/centos/el7/package/test-package/1.0.0/x86_64
```
The server responds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |
## Install a package
To install a package from the RPM registry, execute the following commands:
```shell
# use latest version
dnf install {package_name}
# use specific version
dnf install {package_name}-{package_version}.{architecture}
```

115
versioned_docs/version-1.25/usage/packages/rubygems.md Normal file
View File

@@ -0,0 +1,115 @@
---
date: "2021-07-20T00:00:00+00:00"
slug: "rubygems"
sidebar_position: 110
---
# RubyGems Package Registry
Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization.
## 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](development/api-usage.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
```

72
versioned_docs/version-1.25/usage/packages/storage.md Normal file
View File

@@ -0,0 +1,72 @@
---
date: "2022-11-01T00:00:00+00:00"
slug: "storage"
sidebar_position: 3
---
# Storage
This document describes the storage of the package registry and how it can be managed.
## 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 underlying 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](../../administration/config-cheat-sheet.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](../../administration/config-cheat-sheet.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.
2. For every package it collects all versions.
3. Excludes from the list the # versions based on the *Keep the most recent* value.
4. Excludes from the list any versions matching the *Keep versions matching* value.
5. Excludes from the list the versions more recent than the *Remove versions older than* value.
6. Excludes from the list any versions not matching the *Remove versions matching* value.
7. Deletes the remaining versions.

90
versioned_docs/version-1.25/usage/packages/swift.md Normal file
View File

@@ -0,0 +1,90 @@
---
date: "2023-01-10T00:00:00+00:00"
slug: "swift"
sidebar_position: 115
---
# Swift Package Registry
Publish [Swift](https://www.swift.org/) packages for your user or organization.
## 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
swift package-registry login https://gitea.example.com/api/packages/{owner}/swift --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](development/api-usage.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](development/api-usage.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.
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 is invalid. |
| `409 Conflict` | A package file with the same combination of parameters exists already. |
## 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
```

76
versioned_docs/version-1.25/usage/packages/vagrant.md Normal file
View File

@@ -0,0 +1,76 @@
---
date: "2022-08-23T00:00:00+00:00"
slug: "vagrant"
sidebar_position: 120
---
# Vagrant Package Registry
Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization.
## 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
```
If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
You cannot publish a box if a box of the same name, version and provider already exists. You must delete the existing package first.
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 is invalid. |
| `409 Conflict` | A package with the same combination of parameters exists already. |
## 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](development/api-usage.md#authentication) in the `VAGRANT_CLOUD_TOKEN` environment variable.
## Supported commands
```
vagrant box add
```