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