完成文档部分内容
This commit is contained in:
267
docs/document/usage/actions/act-runner.md
Normal file
267
docs/document/usage/actions/act-runner.md
Normal file
@@ -0,0 +1,267 @@
|
||||
---
|
||||
date: "2023-05-24T15:00:00+08:00"
|
||||
slug: "act-runner"
|
||||
sidebar_position: 20
|
||||
---
|
||||
|
||||
# Act Runner
|
||||
|
||||
本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)，这是Gitea Actions的Runner。
|
||||
|
||||
## 要求
|
||||
|
||||
建议在Docker容器中运行Job，因此您需要首先安装Docker。
|
||||
并确保Docker守护进程正在运行。
|
||||
|
||||
其他与Docker API兼容的OCI容器引擎也应该可以正常工作，但尚未经过测试。
|
||||
|
||||
但是，如果您确定要直接在主机上运行Job，则不需要Docker。
|
||||
|
||||
## 安装
|
||||
|
||||
有多种安装Act Runner的方法。
|
||||
|
||||
### 下载二进制文件
|
||||
|
||||
您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
|
||||
然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
|
||||
|
||||
下载二进制文件时，请确保您已经下载了适用于您的平台的正确版本。
|
||||
您可以通过运行以下命令进行检查：
|
||||
|
||||
```bash
|
||||
chmod +x act_runner
|
||||
./act_runner --version
|
||||
```
|
||||
|
||||
如果看到版本信息，则表示您已经下载了正确的二进制文件。
|
||||
|
||||
### 使用 Docker 镜像
|
||||
|
||||
您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
|
||||
与二进制文件类似，您可以使用`nightly`标签使用最新的夜间构建版本，而`latest`标签是最新的稳定版本。
|
||||
|
||||
```bash
|
||||
docker pull docker.io/gitea/act_runner:latest # for the latest stable release
|
||||
docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
配置通过配置文件进行。它是可选的，当没有指定配置文件时，将使用默认配置。
|
||||
|
||||
您可以通过运行以下命令生成配置文件：
|
||||
|
||||
```bash
|
||||
./act_runner generate-config
|
||||
```
|
||||
|
||||
默认配置是安全的，可以直接使用。
|
||||
|
||||
```bash
|
||||
./act_runner generate-config > config.yaml
|
||||
./act_runner --config config.yaml [command]
|
||||
```
|
||||
|
||||
您亦可以如下使用 docker 创建配置文件：
|
||||
|
||||
```bash
|
||||
docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
|
||||
```
|
||||
|
||||
当使用Docker镜像时，可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中：
|
||||
|
||||
```bash
|
||||
docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
|
||||
```
|
||||
|
||||
您可能注意到上面的命令都是不完整的，因为现在还不是运行Act Runner的时候。
|
||||
在运行Act Runner之前，我们需要首先将其注册到您的Gitea实例中。
|
||||
|
||||
## 注册
|
||||
|
||||
在运行Act Runner之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。
|
||||
|
||||
### Runner级别
|
||||
|
||||
您可以在不同级别上注册Runner，它可以是：
|
||||
|
||||
- 实例级别：Runner将为实例中的所有存储库运行Job。
|
||||
- 组织级别：Runner将为组织中的所有存储库运行Job。
|
||||
- 存储库级别：Runner将为其所属的存储库运行Job。
|
||||
|
||||
请注意，即使存储库具有自己的存储库级别Runner，它仍然可以使用实例级别或组织级别Runner。未来的版本可能提供更多对此进行更好控制的选项。
|
||||
|
||||
### 获取注册令牌
|
||||
|
||||
Runner级别决定了从哪里获取注册令牌。
|
||||
|
||||
- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。
|
||||
- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
|
||||
- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
|
||||
|
||||
如果您无法看到设置页面，请确保您具有正确的权限并且已启用 Actions。
|
||||
|
||||
注册令牌的格式是一个随机字符串 `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`。
|
||||
|
||||
注册令牌也可以通过 Gitea 的 [命令行](../../administration/command-line.md#actions-generate-runner-token) 获得:
|
||||
|
||||
```
|
||||
gitea --config /etc/gitea/app.ini actions generate-runner-token
|
||||
```
|
||||
|
||||
用户也可以使用 `GITEA_RUNNER_REGISTRATION_TOKEN` 或 `GITEA_RUNNER_REGISTRATION_TOKEN_FILE` 环境变量以在 Gitea 启动时设置全局的注册令牌，例如：
|
||||
|
||||
```
|
||||
openssl rand -hex 24 > /some-dir/runner-token
|
||||
export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
|
||||
./gitea --config ...
|
||||
```
|
||||
|
||||
来自环境变量的令牌在通过 Web 界面或 API 重置(重新创建新令牌)前将一直有效。
|
||||
|
||||
令牌可用于注册多个 Runner，直到使用 Web 界面中的令牌重置链接将其撤销并替换为新令牌。
|
||||
|
||||
### 注册Runner
|
||||
|
||||
可以通过运行以下命令来注册Act Runner：
|
||||
|
||||
```bash
|
||||
./act_runner register
|
||||
```
|
||||
|
||||
或者，您可以使用 `--config` 选项来指定前面部分提到的配置文件。
|
||||
|
||||
```bash
|
||||
./act_runner --config config.yaml register
|
||||
```
|
||||
|
||||
您将逐步输入注册信息，包括：
|
||||
|
||||
- Gitea 实例的 URL，例如 `https://gitea.com/` 或 `http://192.168.8.8:3000/`。
|
||||
- 注册令牌。
|
||||
- Runner名称（可选）。如果留空，将使用主机名。
|
||||
- Runner标签（可选）。如果留空，将使用默认标签。
|
||||
|
||||
您可能对Runner标签感到困惑，稍后将对其进行解释。
|
||||
|
||||
如果您想以非交互方式注册Runner，可以使用参数执行以下操作。
|
||||
|
||||
```bash
|
||||
./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
|
||||
```
|
||||
|
||||
注册Runner后，您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
|
||||
请不要手动编辑该文件。
|
||||
如果此文件丢失或损坏，可以直接删除它并重新注册。
|
||||
|
||||
如果您想将注册信息存储在其他位置，请在配置文件中指定，并不要忘记指定 `--config` 选项。
|
||||
|
||||
### 使用Docker注册Runner
|
||||
|
||||
如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行Act Runner时指定注册信息。
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
-v $(pwd)/config.yaml:/config.yaml \
|
||||
-v $(pwd)/data:/data \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-e CONFIG_FILE=/config.yaml \
|
||||
-e GITEA_INSTANCE_URL=<instance_url> \
|
||||
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
|
||||
-e GITEA_RUNNER_NAME=<runner_name> \
|
||||
-e GITEA_RUNNER_LABELS=<runner_labels> \
|
||||
--name my_runner \
|
||||
-d gitea/act_runner:nightly
|
||||
```
|
||||
|
||||
您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
|
||||
这是因为Act Runner将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
|
||||
如前所述，如果要在主机上直接运行Job，可以将其移除。
|
||||
需要明确的是，这里的 "主机" 实际上指的是当前运行 Act Runner的容器，而不是主机机器本身。
|
||||
|
||||
### 使用 Docker compose 运行 Runner
|
||||
|
||||
您亦可使用如下的 `docker-compose.yml`:
|
||||
|
||||
```yml
|
||||
version: "3.8"
|
||||
services:
|
||||
runner:
|
||||
image: gitea/act_runner:nightly
|
||||
environment:
|
||||
CONFIG_FILE: /config.yaml
|
||||
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
|
||||
GITEA_RUNNER_NAME: "${RUNNER_NAME}"
|
||||
GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
|
||||
volumes:
|
||||
- ./config.yaml:/config.yaml
|
||||
- ./data:/data
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
### 当您使用 Docker 镜像启动 Runner，如何配置 Cache
|
||||
|
||||
如果你不打算在工作流中使用 `actions/cache`，你可以忽略本段。
|
||||
|
||||
如果您在使用 `actions/cache` 时没有进行额外的配置，将会返回以下错误信息：
|
||||
> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
|
||||
|
||||
这个错误的原因是 runner 容器和作业容器位于不同的网络中，因此作业容器无法访问 runner 容器。
|
||||
因此，配置 cache 动作以确保其正常运行是非常重要的。请按照以下步骤操作：
|
||||
|
||||
- 1.获取 Runner 容器所在主机的 LAN（本地局域网） IP 地址。
|
||||
- 2.获取一个 Runner 容器所在主机的空闲端口号。
|
||||
- 3.在配置文件中如下配置：
|
||||
|
||||
```yaml
|
||||
cache:
|
||||
enabled: true
|
||||
dir: ""
|
||||
# 使用步骤 1. 获取的 LAN IP
|
||||
host: "192.168.8.17"
|
||||
# 使用步骤 2. 获取的端口号
|
||||
port: 8088
|
||||
```
|
||||
|
||||
- 4.启动容器时, 将 Cache 端口映射至主机。
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
--name gitea-docker-runner \
|
||||
-p 8088:8088 \
|
||||
-d gitea/act_runner:nightly
|
||||
```
|
||||
|
||||
### 标签
|
||||
|
||||
Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们。
|
||||
|
||||
默认标签为`ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`。
|
||||
它们是逗号分隔的列表，每个项目都是一个标签。
|
||||
|
||||
让我们以 `ubuntu-22.04:docker://node:16-bullseye` 为例。
|
||||
它意味着Runner可以运行带有`runs-on: ubuntu-22.04`的Job，并且该Job将在使用`node:16-bullseye`镜像的Docker容器中运行。
|
||||
|
||||
如果默认镜像无法满足您的需求，并且您有足够的磁盘空间可以使用更好、更大的镜像，您可以将其更改为`ubuntu-22.04:docker://<您喜欢的镜像>`。
|
||||
您可以在[act 镜像](https://github.com/nektos/act/blob/master/IMAGES.md)上找到更多有用的镜像。
|
||||
|
||||
如果您想直接在主机上运行Job，您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04`，`:host`是可选的。
|
||||
然而，我们建议您使用类似`linux_amd64:host`或`windows:host`的特殊名称，以避免误用。
|
||||
|
||||
从 Gitea 1.21 开始，您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签（如果没有配置文件，请参考 [配置教程](#配置)），通过执行 `./act_runner daemon --config config.yaml` 命令重启 runner 之后，这些新定义的标签就会生效。
|
||||
|
||||
## 运行
|
||||
|
||||
注册完Runner后，您可以通过运行以下命令来运行它：
|
||||
|
||||
```bash
|
||||
./act_runner daemon
|
||||
# or
|
||||
./act_runner daemon --config config.yaml
|
||||
```
|
||||
|
||||
Runner将从Gitea实例获取Job并自动运行它们。
|
||||
|
||||
由于Act Runner仍处于开发中，建议定期检查最新版本并进行升级。
|
||||
27
docs/document/usage/actions/badge.md
Normal file
27
docs/document/usage/actions/badge.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
date: "2023-02-25T00:00:00+00:00"
|
||||
slug: "badge"
|
||||
sidebar_position: 110
|
||||
---
|
||||
|
||||
# Badge
|
||||
|
||||
Gitea has its builtin Badge system which allows you to display the status of your repository in other places. You can use the following badges:
|
||||
|
||||
## Workflow Badge
|
||||
|
||||
The Gitea Actions workflow badge is a badge that shows the status of the latest workflow run.
|
||||
It is designed to be compatible with [GitHub Actions workflow badge](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge).
|
||||
|
||||
You can use the following URL to get the badge:
|
||||
|
||||
```
|
||||
https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}/badge.svg?branch={branch}&event={event}&style={style}
|
||||
```
|
||||
|
||||
- `{owner}`: The owner of the repository.
|
||||
- `{repo}`: The name of the repository.
|
||||
- `{workflow_file}`: The name of the workflow file.
|
||||
- `{branch}`: Optional. The branch of the workflow. Default to your repository's default branch.
|
||||
- `{event}`: Optional. The event of the workflow. Default to none.
|
||||
- `{style}`: Optional. Style of the badge, either `flat` or `flat-square`. Default to `flat`.
|
||||
125
docs/document/usage/actions/comparison.md
Normal file
125
docs/document/usage/actions/comparison.md
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
date: "2023-05-24T15:00:00+08:00"
|
||||
slug: "comparison"
|
||||
sidebar_position: 15
|
||||
---
|
||||
|
||||
# 与GitHub Actions的对比
|
||||
|
||||
尽管Gitea Actions旨在与GitHub Actions兼容，但它们之间存在一些差异。
|
||||
|
||||
## 额外功能
|
||||
|
||||
### Action URL绝对路径
|
||||
|
||||
Gitea Actions支持通过URL绝对路径定义actions，这意味着您可以使用来自任何Git存储库的Actions。
|
||||
例如，`uses: https://github.com/actions/checkout@v4`或`uses: http://your_gitea.com/owner/repo@branch`。
|
||||
|
||||
### 使用Go编写Actions
|
||||
|
||||
Gitea Actions支持使用Go编写Actions。
|
||||
请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
|
||||
|
||||
### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
|
||||
|
||||
Github Actions 不支持这些语法，详见： https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
|
||||
|
||||
## 不支持的工作流语法
|
||||
|
||||
### `concurrency`
|
||||
|
||||
这是用于一次运行一个Job。
|
||||
请参阅[使用并发](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `run-name`
|
||||
|
||||
这是工作流生成的工作流运行的名称。
|
||||
请参阅[GitHub Actions 的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `permissions`和`jobs.<job_id>.permissions`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `jobs.<job_id>.timeout-minutes`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `jobs.<job_id>.continue-on-error`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `jobs.<job_id>.environment`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
|
||||
|
||||
Gitea Actions 目前不支持此功能。
|
||||
|
||||
### 复杂的`runs-on`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
|
||||
|
||||
Gitea Actions目前只支持`runs-on: xyz`或`runs-on: [xyz]`。
|
||||
|
||||
### `hashFiles`表达式
|
||||
|
||||
请参阅[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。
|
||||
|
||||
Gitea Actions目前不支持此功能，如果使用它，结果将始终为空字符串。
|
||||
|
||||
作为解决方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。
|
||||
|
||||
## 缺失的功能
|
||||
|
||||
### 问题匹配器
|
||||
|
||||
问题匹配器是一种扫描Actions输出以查找指定正则表达式模式并在用户界面中突出显示该信息的方法。
|
||||
请参阅[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### 为错误创建注释
|
||||
|
||||
请参阅[为错误创建注释](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### 表达式
|
||||
|
||||
对于 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions), 当前仅 [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) 被支持。
|
||||
|
||||
## 缺失的UI功能
|
||||
|
||||
### 预处理和后处理步骤
|
||||
|
||||
预处理和后处理步骤在Job日志用户界面中没有自己的用户界面。
|
||||
|
||||
### 服务步骤
|
||||
|
||||
服务步骤在Job日志用户界面中没有自己的用户界面。
|
||||
|
||||
## 不一样的行为
|
||||
|
||||
### 下载Actions
|
||||
|
||||
当 `[actions].DEFAULT_ACTIONS_URL` 保持默认值为 `github` 时，Gitea将会从 https://github.com 下载相对路径的actions。比如：
|
||||
如果你使用 `uses: actions/checkout@v4`，Gitea将会从 https://github.com/actions/checkout.git 下载这个 actions 项目。
|
||||
如果你想要从另外一个 Git服务下载actions，你只需要使用绝对URL `uses: https://gitea.com/actions/checkout@v4` 来下载。
|
||||
|
||||
如果你的 Gitea 实例是部署在一个互联网限制的网络中，也可以使用绝对地址来下载 actions。你也可以将配置项修改为 `[actions].DEFAULT_ACTIONS_URL = self`。这样所有的相对路径的actions引用，将不再会从 github.com 去下载，而会从这个 Gitea 实例自己的仓库中去下载。例如： `uses: actions/checkout@v4` 将会从 `[server].ROOT_URL`/actions/checkout.git 这个地址去下载 actions。
|
||||
|
||||
设置`[actions].DEFAULT_ACTIONS_URL`进行配置。请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
|
||||
### 上下文可用性
|
||||
|
||||
不检查上下文可用性，因此您可以在更多地方使用env上下文。
|
||||
请参阅[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
|
||||
124
docs/document/usage/actions/design.md
Normal file
124
docs/document/usage/actions/design.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
date: "2023-05-24T15:00:00+08:00"
|
||||
slug: "design"
|
||||
sidebar_position: 40
|
||||
---
|
||||
|
||||
# Gitea Actions设计
|
||||
|
||||
Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
|
||||
|
||||
## Act
|
||||
|
||||
[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。
|
||||
我们受到了它的启发，并思考它是否可能为Gitea运行Actions。
|
||||
|
||||
然而，尽管[nektos/act](https://github.com/nektos/act)被设计为一个命令行工具，但我们实际上需要的是一个专为Gitea修改的Go库。
|
||||
因此，我们在[gitea/act](https://gitea.com/gitea/act)基础上进行了分叉。
|
||||
|
||||
这是一个软分叉，将定期跟进上游。
|
||||
虽然添加了一些自定义提交，但我们会尽力避免对原始代码进行太多更改。
|
||||
|
||||
分叉的 act 只是Gitea特定用途的桥接或适配器。
|
||||
还添加了一些额外的提交，例如：
|
||||
|
||||
- 将执行日志输出到日志记录器钩子，以便报告给Gitea
|
||||
- 禁用 GraphQL URL，因为Gitea不支持它
|
||||
- 每个Job启动一个新的容器，而不是重复使用，以确保隔离性。
|
||||
|
||||
这些修改没有理由合并到上游。
|
||||
如果用户只想在本地运行可信的Actions，它们是没有意义的。
|
||||
|
||||
然而，将来可能会出现重叠，例如两个项目都需要的必要错误修复或新功能。
|
||||
在这些情况下，我们将向上游仓库贡献变更。
|
||||
|
||||
## act runner
|
||||
|
||||
Gitea的Runner被称为act runner，因为它基于act。
|
||||
|
||||
与其他CIRunner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
|
||||
|
||||
为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。
|
||||
此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。
|
||||
|
||||
之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。
|
||||
但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。
|
||||
这就是为什么在注册过程中添加自定义标签时，需要输入一些复杂内容，比如`my_custom_label:docker://centos:7`。
|
||||
这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
|
||||
|
||||
然而，Docker不是唯一的选择。
|
||||
act 也支持直接在主机上运行Job。
|
||||
这是通过像`linux_arm:host`这样的标签实现的。
|
||||
这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。
|
||||
|
||||
标签的设计遵循格式`label[:schema[:args]]`。
|
||||
如果省略了schema，则默认为`host`。
|
||||
|
||||
因此，
|
||||
|
||||
- `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。
|
||||
- `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。
|
||||
- `my_custom_label`：等同于`my_custom_label:host`。
|
||||
- `my_custom_label:vm:ubuntu-latest`：（仅为示例，未实现）使用带有`ubuntu-latest` ISO的虚拟机运行带有`my_custom_label`标签的Job。
|
||||
|
||||
## 通信协议
|
||||
|
||||
由于act runner是Gitea的独立部分，我们需要一种协议让Runner与Gitea实例进行通信。
|
||||
然而，我们不认为让Gitea监听一个新端口是个好主意。
|
||||
相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
|
||||
因此，我们选择使用基于HTTP的gRPC。
|
||||
|
||||
我们使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 进行连接。
|
||||
有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。
|
||||
|
||||
## 网络架构
|
||||
|
||||
让我们来看一下整体的网络架构。
|
||||
这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。
|
||||
|
||||
|
||||
|
||||
图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。
|
||||
|
||||
### 连接 1，act runner到Gitea实例
|
||||
|
||||
act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
|
||||
|
||||
### 连接 2，Job容器到Gitea实例
|
||||
|
||||
即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
|
||||
举个例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要连接到Gitea来获取代码。
|
||||
获取代码并不总是运行某些Job所必需的，但在大多数情况下是必需的。
|
||||
|
||||
如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
|
||||
然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。
|
||||
|
||||
### 连接 3，act runner到互联网
|
||||
|
||||
当您使用诸如 `actions/checkout@v4` 的一些Actions时，act runner下载的是脚本，而不是Job容器。
|
||||
默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
|
||||
那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
|
||||
它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
|
||||
|
||||
然而，互联网访问并不是绝对必需的。
|
||||
您可以配置您的Gitea实例从您的内部网络设施中获取 Actions 或镜像。
|
||||
|
||||
实际上，您的Gitea实例可以同时充当 Actions 市场和镜像注册表。
|
||||
您可以将GitHub上的Actions仓库镜像到您的Gitea实例，并将其用作普通Actions。
|
||||
而 [Gitea 容器注册表](usage/packages/container.md) 可用作Docker镜像注册表。
|
||||
|
||||
### 连接 4，Job容器到互联网
|
||||
|
||||
当使用诸如`actions/setup-go@v5`的Actions时，可能需要从互联网下载资源，以设置Job容器中的Go语言环境。
|
||||
因此，成功完成这些Actions需要访问互联网。
|
||||
|
||||
然而，这也是可选的。
|
||||
您可以使用自定义的Actions来避免依赖互联网访问，或者可以使用已安装所有依赖项的打包的Docker镜像来运行Job。
|
||||
|
||||
## 总结
|
||||
|
||||
使用Gitea Actions只需要确保Runner能够连接到Gitea实例。
|
||||
互联网访问是可选的，但如果没有互联网访问，将需要额外的工作。
|
||||
换句话说：当Runner能够自行查询互联网时，它的工作效果最好，但您不需要将其暴露给互联网（无论是单向还是双向）。
|
||||
|
||||
如果您在使用Gitea Actions时遇到任何网络问题，希望上面的图片能够帮助您进行故障排除。
|
||||
167
docs/document/usage/actions/faq.md
Normal file
167
docs/document/usage/actions/faq.md
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
date: "2023-05-24T15:00:00+08:00"
|
||||
slug: "faq"
|
||||
sidebar_position: 100
|
||||
---
|
||||
|
||||
# Gitea Actions常见问题解答
|
||||
|
||||
本页面包含一些关于Gitea Actions的常见问题和答案。
|
||||
|
||||
## 是否可以在我的实例中默认禁用新仓库的Actions？
|
||||
|
||||
是的，当您为实例启用Actions时，您可以选择默认启用actions单元以适用于所有新仓库。
|
||||
|
||||
```ini
|
||||
[repository]
|
||||
; 去掉 repo.actions 将不会为新仓库自动启用actions
|
||||
DEFAULT_REPO_UNITS = ...,repo.actions
|
||||
```
|
||||
|
||||
## 在工作流文件中应该使用`github.xyz`还是`gitea.xyz`？
|
||||
|
||||
您可以使用`github.xyz`，Gitea将正常工作。
|
||||
如前所述，Gitea Actions的设计是与GitHub Actions兼容的。
|
||||
然而，我们建议在工作流文件中使用`gitea.xyz`，以防止在工作流文件中出现不同类型的密钥（因为您在Gitea上使用此工作流，而不是GitHub）。
|
||||
不过，这完全是可选的，因为目前这两个选项的效果是相同的。
|
||||
|
||||
## 使用`actions/checkout@v4`等Actions时，Job容器会从何处下载脚本？
|
||||
|
||||
GitHub 上有成千上万个 [Actions 脚本](https://github.com/marketplace?type=actions)。
|
||||
当您编写 `uses: actions/checkout@v4` 时，它默认会从 [github.com/actions/checkout](https://github.com/actions/checkout) 下载脚本。
|
||||
那如果您想使用一些托管在其它平台上的脚本呢，比如在 gitea.com 上的？
|
||||
|
||||
好消息是，您可以指定要从任何位置使用Actions的URL前缀。
|
||||
这是Gitea Actions中的额外语法。
|
||||
例如：
|
||||
|
||||
- `uses: https://gitea.com/xxx/xxx@xxx`
|
||||
- `uses: https://github.com/xxx/xxx@xxx`
|
||||
- `uses: http://your_gitea_instance.com/xxx@xxx`
|
||||
|
||||
注意，`https://`或`http://`前缀是必需的！
|
||||
|
||||
这是与 GitHub Actions 的一个区别，GitHub Actions 只允许使用托管在 GitHub 上的 actions 脚本。
|
||||
但用户理应拥有权利去灵活决定如何运行 Actions。
|
||||
|
||||
另外，如果您希望您的 Runner 默认从您自己的 Gitea 实例下载 Actions，可以通过设置 `[actions].DEFAULT_ACTIONS_URL`进行配置。
|
||||
参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
|
||||
## 如何限制Runner的权限？
|
||||
|
||||
Runner仅具有连接到您的Gitea实例的权限。
|
||||
当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。
|
||||
如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](usage/actions/secrets.md)。
|
||||
|
||||
对于 Actions 的细粒度权限控制是一项复杂的工作。
|
||||
在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。
|
||||
|
||||
## 如何避免被黑客攻击？
|
||||
|
||||
有两种可能的攻击类型：未知的Runner窃取您的仓库中的代码或密钥，或恶意脚本控制您的Runner。
|
||||
|
||||
避免前者意味着不允许您不认识的人为您的仓库、组织或实例注册Runner。
|
||||
|
||||
后者要复杂一些。
|
||||
如果您为公司使用私有的Gitea实例，您可能不需要担心安全问题，因为您信任您的同事，并且可以追究他们的责任。
|
||||
|
||||
对于公共实例，情况略有不同。
|
||||
以下是我们在 [gitea.com](http://gitea.com/)上的做法：
|
||||
|
||||
- 我们仅为 "gitea" 组织注册Runner，因此我们的Runner不会执行来自其他仓库的Job。
|
||||
- 我们的Runner始终在隔离容器中运行Job。虽然可以直接在主机上进行这样的操作，但出于安全考虑，我们选择不这样做。
|
||||
- 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
|
||||
- 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。
|
||||
|
||||
## act runner支持哪些操作系统？
|
||||
|
||||
它在Linux、macOS和Windows上运行良好。
|
||||
虽然理论上支持其他操作系统，但需要进一步测试。
|
||||
|
||||
需要注意的一点是，如果选择直接在主机上运行Job而不是在Job容器中运行，操作系统之间的环境差异可能会导致意外的失败。
|
||||
|
||||
例如，在大多数情况下，Windows上没有可用的bash，而act尝试默认使用bash运行脚本。
|
||||
因此，您需要在工作流文件中将默认shell指定为`powershell`，参考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。
|
||||
|
||||
```yaml
|
||||
defaults:
|
||||
run:
|
||||
shell: powershell
|
||||
```
|
||||
|
||||
## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？
|
||||
|
||||
[@lunny](https://gitea.com/lunny)在实现Actions的[问题](https://github.com/go-gitea/gitea/issues/13539)中已经解释过这个问题。
|
||||
此外，Actions不仅是一个CI/CD 系统，还是一个自动化工具。
|
||||
|
||||
在开源世界中，已经有许多[市场上的Actions](https://github.com/marketplace?type=actions)实现了。
|
||||
能够重用它们是令人兴奋的。
|
||||
|
||||
## 如果它在多个标签上运行，例如 `runs-on: [label_a, label_b]`，会发生什么？
|
||||
|
||||
这是有效的语法。
|
||||
它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
|
||||
不幸的是，act runner 并不支持这种方式。
|
||||
如上所述，我们将标签映射到环境：
|
||||
|
||||
- `ubuntu` → `ubuntu:22.04`
|
||||
- `centos` → `centos:8`
|
||||
|
||||
但我们需要将标签组映射到环境，例如：
|
||||
|
||||
- `[ubuntu]` → `ubuntu:22.04`
|
||||
- `[with-gpu]` → `linux:with-gpu`
|
||||
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
|
||||
|
||||
我们还需要重新设计任务分配给Runner的方式。
|
||||
具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
|
||||
因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
|
||||
这不是一个技术问题，只是在早期设计中被忽视了。
|
||||
参见[runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
|
||||
|
||||
目前，act runner尝试匹配标签中的每一个，并使用找到的第一个匹配项。
|
||||
|
||||
## 代理标签和自定义标签对于Runner有什么区别？
|
||||
|
||||
|
||||
|
||||
代理标签是由Runner在注册过程中向Gitea实例报告的。
|
||||
而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。
|
||||
|
||||
然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
|
||||
您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
|
||||
然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
|
||||
这个默认值可能与用户的期望不符。
|
||||
参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
|
||||
|
||||
与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。
|
||||
|
||||
## Gitea Actions runner会有更多的实现吗？
|
||||
|
||||
虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。
|
||||
然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
|
||||
我们支持您的选择，无论您如何决定。
|
||||
如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
|
||||
|
||||
## Gitea 支持哪些工作流触发事件？
|
||||
|
||||
表格中列出的所有事件都是支持的，并且与 GitHub 兼容。
|
||||
对于仅 GitHub 支持的事件，请参阅 GitHub 的[文档](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)。
|
||||
|
||||
| 触发事件 | 活动类型 |
|
||||
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
|
||||
| create | 不适用 |
|
||||
| delete | 不适用 |
|
||||
| fork | 不适用 |
|
||||
| gollum | 不适用 |
|
||||
| push | 不适用 |
|
||||
| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
|
||||
| issue_comment | `created`, `edited`, `deleted` |
|
||||
| pull_request | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled` |
|
||||
| pull_request_review | `submitted`, `edited` |
|
||||
| pull_request_review_comment | `created`, `edited` |
|
||||
| release | `published`, `edited` |
|
||||
| registry_package | `published` |
|
||||
|
||||
> 对于 `pull_request` 事件，在 [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) 中 `ref` 是 `refs/pull/:prNumber/merge`，它指向这个拉取请求合并提交的一个预览。但是 Gitea 没有这种 reference。
|
||||
> 因此，Gitea Actions 中 `ref` 是 `refs/pull/:prNumber/head`，它指向这个拉取请求的头分支而不是合并提交的预览。
|
||||
42
docs/document/usage/actions/overview.md
Normal file
42
docs/document/usage/actions/overview.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
date: "2023-05-24T15:00:00+08:00"
|
||||
slug: "overview"
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
从Gitea **1.19**版本开始，Gitea Actions成为了内置的CI/CD解决方案。
|
||||
|
||||
## 名称
|
||||
|
||||
Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且兼容，它的名称也受到了它的启发。
|
||||
为了避免混淆，在这里我们明确了拼写方式：
|
||||
|
||||
- "Gitea Actions"（两个单词都大写且带有"s"）是Gitea功能的名称。
|
||||
- "GitHub Actions"是GitHub功能的名称。
|
||||
- "Actions"根据上下文的不同可以指代以上任意一个。在本文档中指代的是"Gitea Actions"。
|
||||
- "action"或"actions"指代一些要使用的脚本/插件，比如"actions/checkout@v4"或"actions/cache@v3"。
|
||||
|
||||
## Runner
|
||||
|
||||
和其他CI/CD解决方案一样，Gitea不会自己运行Job，而是将Job委托给Runner。
|
||||
Gitea Actions的Runner被称为[act runner](https://gitea.com/gitea/act_runner)，它是一个独立的程序，也是用Go语言编写的。
|
||||
它是基于[nektos/act](http://github.com/nektos/act)的一个[分支](https://gitea.com/gitea/act) 。
|
||||
|
||||
由于Runner是独立部署的，可能存在潜在的安全问题。
|
||||
为了避免这些问题，请遵循两个简单的规则：
|
||||
|
||||
- 不要为你的仓库、组织或实例使用你不信任的Runner。
|
||||
- 不要为你不信任的仓库、组织或实例提供Runner。
|
||||
|
||||
对于内部使用的Gitea实例，比如企业或个人使用的实例，这两个规则不是问题，它们自然而然就是如此。
|
||||
然而，对于公共的Gitea实例，比如[gitea.com](https://gitea.com)，在添加或使用Runner时应当牢记这两个规则。
|
||||
|
||||
## 状态
|
||||
|
||||
Gitea Actions仍然在开发中，因此可能存在一些错误和缺失的功能。
|
||||
并且在稳定版本（v1.20或更高版本）之前可能会进行一些重大的更改。
|
||||
|
||||
如果情况发生变化，我们将在此处进行更新。
|
||||
因此，请在其他地方找到过时文章时参考此处的内容。
|
||||
131
docs/document/usage/actions/quickstart.md
Normal file
131
docs/document/usage/actions/quickstart.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
date: "2023-05-24T15:00:00+08:00"
|
||||
slug: "quickstart"
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
# 快速入门
|
||||
|
||||
本页面将指导您使用Gitea Actions的过程。
|
||||
|
||||
## 设置Gitea
|
||||
|
||||
首先，您需要一个Gitea实例。
|
||||
您可以按照[文档](installation/from-package.md) 来设置一个新实例或升级现有实例。
|
||||
无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。
|
||||
|
||||
从1.21.0开始，默认情况下，Actions是启用的。如果您正在使用1.21.0之前的版本，您需要将以下内容添加到配置文件中以启用它：
|
||||
|
||||
```ini
|
||||
[actions]
|
||||
ENABLED=true
|
||||
```
|
||||
|
||||
如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
|
||||
### 设置Runner
|
||||
|
||||
Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
|
||||
为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
|
||||
|
||||
您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
|
||||
|
||||
在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
|
||||
如果出现问题，这样调试起来会更容易。
|
||||
|
||||
该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。
|
||||
虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。
|
||||
然而，建议使用Docker运行Job，因为它更安全且更易于管理。
|
||||
|
||||
在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
|
||||
|
||||
```bash
|
||||
./act_runner register --no-interactive --instance <instance> --token <token>
|
||||
```
|
||||
|
||||
需要两个必需的参数：`instance` 和 `token`。
|
||||
|
||||
`instance`是您的Gitea实例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。
|
||||
Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
|
||||
这意味着它可能与用于Web访问的`ROOT_URL`不同。
|
||||
使用回环地址（例如 `127.0.0.1` 或 `localhost`）是一个不好的选择。
|
||||
如果不确定使用哪个地址，通常选择局域网地址即可。
|
||||
|
||||
`token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
|
||||
它只能使用一次，并且不能用于注册多个Runner。
|
||||
您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner`
|
||||
|
||||
- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。
|
||||
- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
|
||||
- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
|
||||
|
||||
|
||||
|
||||
注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。
|
||||
请不要手动编辑该文件。
|
||||
如果该文件丢失或损坏，只需删除它然后重新注册即可。
|
||||
|
||||
最后，是时候启动Runner了：
|
||||
|
||||
```bash
|
||||
./act_runner daemon
|
||||
```
|
||||
|
||||
您可以在管理页面上看到新的Runner：
|
||||
|
||||
|
||||
|
||||
您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
|
||||
|
||||
### 使用Actions
|
||||
|
||||
即使对于启用了Gitea实例的Actions，存储库仍默认禁用Actions。
|
||||
|
||||
要启用它，请转到存储库的设置页面，例如`your_gitea.com/<owner>/repo/settings`，然后启用`Enable Repository Actions`。
|
||||
|
||||
|
||||
|
||||
接下来的步骤可能相当复杂。
|
||||
您需要学习Actions的[工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，并编写您想要的工作流文件。
|
||||
|
||||
不过，我们可以从一个简单的演示开始：
|
||||
|
||||
```yaml
|
||||
name: Gitea Actions Demo
|
||||
run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
|
||||
on: [push]
|
||||
|
||||
jobs:
|
||||
Explore-Gitea-Actions:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event."
|
||||
- run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
|
||||
- run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
|
||||
- name: Check out repository code
|
||||
uses: actions/checkout@v4
|
||||
- run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner."
|
||||
- run: echo "🖥️ The workflow is now ready to test your code on the runner."
|
||||
- name: List files in the repository
|
||||
run: |
|
||||
ls ${{ gitea.workspace }}
|
||||
- run: echo "🍏 This job's status is ${{ job.status }}."
|
||||
```
|
||||
|
||||
您可以将上述示例上传为一个以`.yaml`扩展名的文件，放在存储库的`.gitea/workflows/`目录中，例如`.gitea/workflows/demo.yaml`。
|
||||
您可能会注意到，这与[GitHub Actions的快速入门](https://docs.github.com/en/actions/quickstart)非常相似。
|
||||
这是因为Gitea Actions在尽可能兼容GitHub Actions的基础上进行设计。
|
||||
|
||||
请注意，演示文件中包含一些表情符号。
|
||||
请确保您的数据库支持它们，特别是在使用MySQL时。
|
||||
如果字符集不是`utf8mb4`，将出现错误，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。
|
||||
有关更多信息，请参阅[数据库准备工作](../../installation/database-preparation.md#mysqlmariadb)。
|
||||
|
||||
或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。
|
||||
|
||||
`on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。
|
||||
然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。
|
||||
|
||||
|
||||
|
||||
做得好！您已成功开始使用Actions。
|
||||
28
docs/document/usage/actions/secrets.md
Normal file
28
docs/document/usage/actions/secrets.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "secrets"
|
||||
sidebar_position: 50
|
||||
---
|
||||
|
||||
# 密钥管理
|
||||
|
||||
密钥管理允许您在用户、组织或仓库中存储敏感信息。
|
||||
密钥管理在 Gitea 1.19+ 版本中可用。
|
||||
|
||||
## 设置密钥名称
|
||||
|
||||
以下规则适用于密钥名称：
|
||||
|
||||
- 密钥名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
|
||||
|
||||
- 密钥名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
|
||||
|
||||
- 密钥名称不能以数字开头。
|
||||
|
||||
- 密钥名称不区分大小写。
|
||||
|
||||
- 密钥名称在创建它们的级别上必须是唯一的。
|
||||
|
||||
例如，对于在仓库级别创建的密钥，它在该仓库中必须具有唯一的名称；对于在组织级别创建的密钥，它在该级别上必须具有唯一的名称。
|
||||
|
||||
如果在多个级别上存在具有相同名称的密钥，则最低级别的密钥优先生效。例如，如果组织级别的密钥与仓库级别的密钥具有相同的名称，则仓库级别的密钥将优先生效。
|
||||
34
docs/document/usage/actions/variables.md
Normal file
34
docs/document/usage/actions/variables.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
date: "2024-04-10T22:21:00+08:00"
|
||||
slug: "actions-variables"
|
||||
sidebar_position: 25
|
||||
---
|
||||
|
||||
# 变量
|
||||
|
||||
您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时，变量的名称会被
|
||||
转换为大写，在yaml文件中引用时需要使用大写。
|
||||
|
||||
## 命名规则
|
||||
|
||||
以下规则适用于变量名：
|
||||
|
||||
- 变量名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
|
||||
- 变量名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
|
||||
- 变量名称不能以数字开头。
|
||||
- 变量名称不区分大小写。
|
||||
- 变量名称在创建它们的级别上必须是唯一的。
|
||||
- 变量名称不能为 `CI`。
|
||||
|
||||
## 使用
|
||||
|
||||
创建配置变量后，它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似
|
||||
```yaml
|
||||
${{ vars.VARIABLE_NAME }}
|
||||
```
|
||||
这样的表达式来使用它们。
|
||||
|
||||
## 优先级
|
||||
|
||||
如果同名变量存在于多个级别，则级别最低的变量优先。
|
||||
仓库级别的变量总是比组织或者用户级别的变量优先被选中。
|
||||
45
docs/document/usage/agit-support.md
Normal file
45
docs/document/usage/agit-support.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "agit"
|
||||
sidebar_position: 12
|
||||
aliases:
|
||||
- /zh-cn/agit-setup
|
||||
---
|
||||
|
||||
# AGit
|
||||
|
||||
在 Gitea `1.13` 版本中，添加了对 [AGit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。AGit 允许用户在没有仓库写入权限的情况下直接创建拉取请求，也不需要分叉仓库。这有助于减少重复仓库的数量，降低不必要的磁盘使用量。
|
||||
|
||||
:::note
|
||||
服务器端需要 Git 版本 2.29 或更高版本才能正常运行。
|
||||
:::
|
||||
|
||||
## 使用 AGit 创建 PR
|
||||
|
||||
AGit 允许在推送代码到远程仓库时创建 PR（合并请求）。
|
||||
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
|
||||
下面的示例说明了这一点：
|
||||
|
||||
```shell
|
||||
git push origin HEAD:refs/for/main
|
||||
```
|
||||
|
||||
该命令的结构如下：
|
||||
|
||||
- `HEAD`：目标分支
|
||||
- `refs/<for|draft|for-review>/<branch>`：目标 PR 类型
|
||||
- `for`：创建一个以 `<branch>` 为目标分支的普通 PR
|
||||
- `draft`/`for-review`：目前被静默忽略
|
||||
- `<branch>/<session>`：要打开 PR 的目标分支
|
||||
- `-o <topic|title|description>`：PR 的选项
|
||||
- `title`：PR 的标题
|
||||
- `topic`：PR 应该打开的分支名称
|
||||
- `description`：PR 的描述
|
||||
- `force-push=true`: 是否强制更新目标分支
|
||||
- 注意: 如果不传值，只用 `-o force-push` 也同样可以正常工作。
|
||||
|
||||
下面是另一个高级示例，用于创建一个以 `topic`、`title` 和 `description` 为参数的新 PR，目标分支是 `main`：
|
||||
|
||||
```shell
|
||||
git push origin HEAD:refs/for/main -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
|
||||
```
|
||||
48
docs/document/usage/agit.md
Normal file
48
docs/document/usage/agit.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
date: " 2022-09-01T20:50:42+0000"
|
||||
slug: "agit"
|
||||
sidebar_position: 12
|
||||
aliases:
|
||||
- /en-us/agit-setup
|
||||
- /agit-setup
|
||||
---
|
||||
|
||||
# AGit
|
||||
|
||||
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
|
||||
|
||||
:::note
|
||||
Git version 2.29 or higher is required on the server side for this to work.
|
||||
:::
|
||||
|
||||
## Creating PRs with AGit
|
||||
|
||||
AGit allows to create PRs while pushing code to the remote repo.
|
||||
This can be done by pushing to the branch followed by a specific refspec (a location identifier known to git).
|
||||
The following example illustrates this:
|
||||
|
||||
```shell
|
||||
git push origin HEAD:refs/for/main
|
||||
```
|
||||
|
||||
The command has the following structure:
|
||||
|
||||
- `HEAD`: The target branch
|
||||
- `origin`: The target repository (not a fork!)
|
||||
- `HEAD`: The local branch containing the changes you are proposing
|
||||
- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
|
||||
- `for`: Create a normal PR with `<branch>` as the target branch
|
||||
- `draft`/`for-review`: Currently ignored silently
|
||||
- `<branch>/`: The branch you want your changes to be merged into
|
||||
- `-o <topic|title|description>`: Options for the PR
|
||||
- `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review. This is REQUIRED to trigger a pull request.
|
||||
- `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
|
||||
- `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
|
||||
- `force-push=true`: Specifies whether to force-update the target branch.
|
||||
- Note: omitting the value and using just `-o force-push` will also work.
|
||||
|
||||
Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
|
||||
|
||||
```shell
|
||||
git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
|
||||
```
|
||||
29
docs/document/usage/blame.md
Normal file
29
docs/document/usage/blame.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
date: "2023-08-14T00:00:00+00:00"
|
||||
slug: "blame"
|
||||
sidebar_position: 13
|
||||
aliases:
|
||||
- /en-us/blame
|
||||
---
|
||||
|
||||
# Blame File View
|
||||
|
||||
Gitea supports viewing the line-by-line revision history for a file also known as blame view.
|
||||
You can also use [`git blame`](https://git-scm.com/docs/git-blame) on the command line to view the revision history of lines within a file.
|
||||
|
||||
1. Navigate to and open the file whose line history you want to view.
|
||||
1. Click the `Blame` button in the file header bar.
|
||||
1. The new view shows the line-by-line revision history for a file with author and commit information on the left side.
|
||||
1. To navigate to an older commit, click the  icon.
|
||||
|
||||
## Ignore commits in the blame view
|
||||
|
||||
All revisions specified in the `.git-blame-ignore-revs` file are hidden from the blame view.
|
||||
This is especially useful to hide reformatting changes and keep the benefits of `git blame`.
|
||||
Lines that were changed or added by an ignored commit will be blamed on the previous commit that changed that line or nearby lines.
|
||||
The `.git-blame-ignore-revs` file must be located in the root directory of the repository.
|
||||
For more information like the file format, see [the `git blame --ignore-revs-file` documentation](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt).
|
||||
|
||||
### Bypassing `.git-blame-ignore-revs` in the blame view
|
||||
|
||||
If the blame view for a file shows a message about ignored revisions, you can see the normal blame view by appending the url parameter `?bypass-blame-ignore=true`.
|
||||
47
docs/document/usage/blocking-users.md
Normal file
47
docs/document/usage/blocking-users.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
date: "2024-01-31T00:00:00+00:00"
|
||||
slug: "blocking-user"
|
||||
sidebar_position: 25
|
||||
aliases:
|
||||
- /en-us/webhooks
|
||||
---
|
||||
|
||||
# Blocking a user
|
||||
|
||||
Gitea supports blocking of users to restrict how they can interact with you and your content.
|
||||
|
||||
You can block a user in your account settings, from the user's profile or from comments created by the user.
|
||||
The user is not directly notified about the block, but they can notice they are blocked when they attempt to interact with you.
|
||||
Organization owners can block anyone who is not a member of the organization too.
|
||||
If a blocked user has admin permissions, they can still perform all actions even if blocked.
|
||||
|
||||
### When you block a user
|
||||
|
||||
- the user stops following you
|
||||
- you stop following the user
|
||||
- the user's stars are removed from your repositories
|
||||
- your stars are removed from their repositories
|
||||
- the user stops watching your repositories
|
||||
- you stop watching their repositories
|
||||
- the user's issue assignments are removed from your repositories
|
||||
- your issue assignments are removed from their repositories
|
||||
- the user is removed as a collaborator on your repositories
|
||||
- you are removed as a collaborator on their repositories
|
||||
- any pending repository transfers to or from the blocked user are canceled
|
||||
|
||||
### When you block a user, the user cannot
|
||||
|
||||
- follow you
|
||||
- watch your repositories
|
||||
- star your repositories
|
||||
- fork your repositories
|
||||
- transfer repositories to you
|
||||
- open issues or pull requests on your repositories
|
||||
- comment on issues or pull requests you've created
|
||||
- comment on issues or pull requests on your repositories
|
||||
- react to your comments on issues or pull requests
|
||||
- react to comments on issues or pull requests on your repositories
|
||||
- assign you to issues or pull requests
|
||||
- add you as a collaborator on their repositories
|
||||
- send you notifications by @mentioning your username
|
||||
- be added as team member (if blocked by an organization)
|
||||
18
docs/document/usage/clone-filter.md
Normal file
18
docs/document/usage/clone-filter.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
|
||||
slug: "clone-filters"
|
||||
sidebar_position: 25
|
||||
aliases:
|
||||
- /zh-cn/clone-filters
|
||||
---
|
||||
|
||||
# 克隆过滤器 (部分克隆)
|
||||
|
||||
Git 引入了 `--filter` 选项用于 `git clone` 命令，该选项可以过滤掉大文件和对象（如 blob），从而创建一个仓库的部分克隆。克隆过滤器对于大型仓库和/或按流量计费的连接特别有用，因为完全克隆（不使用 `--filter`）可能会很昂贵（需要下载所有历史数据）。
|
||||
|
||||
这需要 Git 2.22 或更高版本，无论是在 Gitea 服务器上还是在客户端上都需要如此。为了使克隆过滤器正常工作，请确保客户端上的 Git 版本至少与服务器上的版本相同（或更高）。以管理员身份登录到 Gitea，然后转到管理后台 -> 应用配置，查看服务器的 Git 版本。
|
||||
|
||||
默认情况下，克隆过滤器是启用的，除非在 `[git]` 下将 `DISABLE_PARTIAL_CLONE` 设置为 `true`。
|
||||
|
||||
请参阅 [GitHub 博客文章：了解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以获取克隆过滤器的常见用法（无 Blob 和无树的克隆），以及 [GitLab 部分克隆文档](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。
|
||||
56
docs/document/usage/code-owners.md
Normal file
56
docs/document/usage/code-owners.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
date: "2023-05-24T16:00:00+00:00"
|
||||
slug: "code-owners"
|
||||
sidebar_position: 30
|
||||
aliases:
|
||||
- /en-us/code-owners
|
||||
---
|
||||
|
||||
# Code Owners
|
||||
|
||||
Gitea maintains code owner files. It looks for it in the following locations in this order:
|
||||
|
||||
- `./CODEOWNERS`
|
||||
- `./docs/CODEOWNERS`
|
||||
- `./.gitea/CODEOWNERS`
|
||||
|
||||
And stops at the first found file.
|
||||
|
||||
File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
|
||||
|
||||
Regexp specified in golang Regex format.
|
||||
Regexp can start with `!` for negative rules - match all files except specified.
|
||||
|
||||
Example file:
|
||||
|
||||
```bash
|
||||
.*\\.go @user1 @user2 # This is comment
|
||||
|
||||
# Comment too
|
||||
# You can assigning code owning for users or teams
|
||||
frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
|
||||
|
||||
# You can use negative pattern
|
||||
!frontend/src/.* @org1/team3 @user5
|
||||
|
||||
# You can use power of go regexp
|
||||
docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
|
||||
!/assets/.*\\.(bin|exe|msi) @user9
|
||||
```
|
||||
|
||||
### Escaping
|
||||
|
||||
You can escape characters `#`, ` ` (space) and `\` with `\`, like:
|
||||
|
||||
```
|
||||
dir/with\#hashtag @user1
|
||||
path\ with\ space @user2
|
||||
path/with\\backslash @user3
|
||||
```
|
||||
|
||||
Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
|
||||
|
||||
```
|
||||
path/\\.with\\.dots
|
||||
path/with\\+plus
|
||||
```
|
||||
38
docs/document/usage/incoming-email.md
Normal file
38
docs/document/usage/incoming-email.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
|
||||
slug: "incoming-email"
|
||||
sidebar_position: 13
|
||||
aliases:
|
||||
- /zh-cn/incoming-email
|
||||
---
|
||||
|
||||
# 邮件接收
|
||||
|
||||
Gitea 支持通过接收邮件执行多种操作。本页面描述了如何进行设置。
|
||||
|
||||
## 要求
|
||||
|
||||
处理接收的电子邮件需要启用 IMAP 功能的电子邮件帐户。
|
||||
推荐的策略是使用 [电子邮件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 邮箱。
|
||||
接收电子邮件地址中包含一个用户/操作特定的令牌，告诉 Gitea 应执行哪个操作。
|
||||
此令牌应该出现在 `To` 和 `Delivered-To` 头字段中。
|
||||
|
||||
Gitea 会尝试检测自动回复并跳过它们，电子邮件服务器也应该配置以减少接收到的干扰（垃圾邮件、通讯订阅等）。
|
||||
|
||||
## 配置
|
||||
|
||||
要激活处理接收的电子邮件消息功能，您需要在配置文件中配置 `email.incoming` 部分。
|
||||
|
||||
`REPLY_TO_ADDRESS` 包含电子邮件客户端将要回复的地址。
|
||||
该地址需要包含 `%{token}` 占位符，该占位符将被替换为描述用户/操作的令牌。
|
||||
此占位符在地址中只能出现一次，并且必须位于地址的用户部分（`@` 之前）。
|
||||
|
||||
使用电子邮件子地址的示例可能如下：`incoming+%{token}@example.com`
|
||||
|
||||
如果使用 catch-all 邮箱，则占位符可以出现在地址的用户部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com`
|
||||
|
||||
## 安全性
|
||||
|
||||
在选择用于接收传入电子邮件的域时要小心。
|
||||
建议在子域名上接收传入电子邮件，例如 `incoming.example.com`，以防止与运行在 `example.com` 上的其他服务可能存在的安全问题。
|
||||
283
docs/document/usage/issue-pull-request-templates.md
Normal file
283
docs/document/usage/issue-pull-request-templates.md
Normal file
@@ -0,0 +1,283 @@
|
||||
---
|
||||
date: "2022-09-07T16:00:00+08:00"
|
||||
slug: "issue-pull-request-templates"
|
||||
sidebar_position: 15
|
||||
toc: true
|
||||
aliases:
|
||||
- /zh-cn/issue-pull-request-templates
|
||||
---
|
||||
|
||||
# 从模板创建工单与合并请求
|
||||
|
||||
开发者可以利用问题模板创建工单与合并请求，其目的在于规范参与者的语言表达。
|
||||
|
||||
## 模板介绍
|
||||
|
||||
Gitea 支持两种格式的模板：Markdown 和 YAML。
|
||||
|
||||
### Markdown 模板
|
||||
|
||||
在 Gitea 中存在两种用途的 Markdown 模板：
|
||||
|
||||
- `ISSUE_TEMPLATE/bug-report.md` 用于规范工单的 Markdown 文本描述
|
||||
- `PULL_REQUEST_TEMPLATE.md` 用于规范合并请求的 Markdown 文本描述
|
||||
|
||||
对于以上 Markdown 模板，我们推荐您将它们放置到项目目录 `.gitea` 进行收纳。
|
||||
|
||||
### YAML 模板
|
||||
|
||||
用 YAML 语法编写的模板相比 Markdown 可以实现更丰富的功能，利用表单实现诸如：问卷调查、字符校验。在 Gitea 中的 YAML 同样支持两种用途：
|
||||
|
||||
- `ISSUE_TEMPLATE/bug-report.yaml` 用于创建问卷调查形式的工单
|
||||
- `PULL_REQUEST_TEMPLATE.yaml` 用于创建表单形式的合并请求
|
||||
|
||||
对于以上 YAML 模板，我们同样推荐您将它们放置到项目目录 `.gitea` 进行收纳。
|
||||
|
||||
##### 表单支持通过 URL 查询参数传值
|
||||
|
||||
当新建工单页面 URL 以 `?title=Issue+Title&body=Issue+Text` 为查询参数，表单将使用其中的参数（key-value）填充表单内容。
|
||||
|
||||
### Gitea 支持的模板文件路径
|
||||
|
||||
工单模板文件名:
|
||||
|
||||
- `ISSUE_TEMPLATE.md`
|
||||
- `ISSUE_TEMPLATE.yaml`
|
||||
- `ISSUE_TEMPLATE.yml`
|
||||
- `issue_template.md`
|
||||
- `issue_template.yaml`
|
||||
- `issue_template.yml`
|
||||
- `.gitea/ISSUE_TEMPLATE.md`
|
||||
- `.gitea/ISSUE_TEMPLATE.yaml`
|
||||
- `.gitea/ISSUE_TEMPLATE.yml`
|
||||
- `.gitea/issue_template.md`
|
||||
- `.gitea/issue_template.yaml`
|
||||
- `.gitea/issue_template.yml`
|
||||
- `.github/ISSUE_TEMPLATE.md`
|
||||
- `.github/ISSUE_TEMPLATE.yaml`
|
||||
- `.github/ISSUE_TEMPLATE.yml`
|
||||
- `.github/issue_template.md`
|
||||
- `.github/issue_template.yaml`
|
||||
- `.github/issue_template.yml`
|
||||
|
||||
合并请求模板:
|
||||
|
||||
- `PULL_REQUEST_TEMPLATE.md`
|
||||
- `PULL_REQUEST_TEMPLATE.yaml`
|
||||
- `PULL_REQUEST_TEMPLATE.yml`
|
||||
- `pull_request_template.md`
|
||||
- `pull_request_template.yaml`
|
||||
- `pull_request_template.yml`
|
||||
- `.gitea/PULL_REQUEST_TEMPLATE.md`
|
||||
- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
|
||||
- `.gitea/PULL_REQUEST_TEMPLATE.yml`
|
||||
- `.gitea/pull_request_template.md`
|
||||
- `.gitea/pull_request_template.yaml`
|
||||
- `.gitea/pull_request_template.yml`
|
||||
- `.github/PULL_REQUEST_TEMPLATE.md`
|
||||
- `.github/PULL_REQUEST_TEMPLATE.yaml`
|
||||
- `.github/PULL_REQUEST_TEMPLATE.yml`
|
||||
- `.github/pull_request_template.md`
|
||||
- `.github/pull_request_template.yaml`
|
||||
- `.github/pull_request_template.yml`
|
||||
|
||||
#### 工单模板目录
|
||||
|
||||
由于工单存在多种类型，Gitea 支持将工单模板统一收纳到 `ISSUE_TEMPLATE` 目录。以下是 Gitea 支持的工单模板目录:
|
||||
|
||||
- `ISSUE_TEMPLATE`
|
||||
- `issue_template`
|
||||
- `.gitea/ISSUE_TEMPLATE`
|
||||
- `.gitea/issue_template`
|
||||
- `.github/ISSUE_TEMPLATE`
|
||||
- `.github/issue_template`
|
||||
- `.gitlab/ISSUE_TEMPLATE`
|
||||
- `.gitlab/issue_template`
|
||||
|
||||
目录支持混合存放 Markdown (`.md`) 或 YAML (`.yaml`/`.yml`) 格式的工单模板。另外，合并请求模板不支持目录存放。
|
||||
|
||||
## Markdown 模板语法
|
||||
|
||||
```md
|
||||
---
|
||||
name: "Template Name"
|
||||
about: "This template is for testing!"
|
||||
title: "[TEST] "
|
||||
ref: "main"
|
||||
labels:
|
||||
- bug
|
||||
- "help needed"
|
||||
---
|
||||
|
||||
This is the template!
|
||||
```
|
||||
|
||||
上面的示例表示用户从列表中选择一个工单模板时，列表会展示模板名称 `Template Name` 和模板描述 `This template is for testing!`。 同时，标题会预先填充为 `[TEST]`，而正文将预先填充 `This is the template!`。该 Issue 会被指派给 `user1`。 最后，Issue 还会被分配两个标签，`bug` 和 `help needed`，并且将问题指向 `main` 分支。
|
||||
|
||||
## YAML 模板语法
|
||||
|
||||
YAML 模板格式如下，相比 Markdown 模板提供了更多实用性的功能。
|
||||
|
||||
```yaml
|
||||
name: 表单名称
|
||||
about: 表单描述
|
||||
title: 默认标题
|
||||
body: 主体内容
|
||||
type: 定义表单元素类型
|
||||
id: 定义表单标号
|
||||
attributes: 扩展的属性
|
||||
validations: 内容校验
|
||||
```
|
||||
|
||||
下例 YAML 配置文件完整定义了一个用于提交 bug 的问卷调查。
|
||||
|
||||
```yaml
|
||||
name: Bug Report
|
||||
about: File a bug report
|
||||
title: "[Bug]: "
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for taking the time to fill out this bug report!
|
||||
- type: input
|
||||
id: contact
|
||||
attributes:
|
||||
label: Contact Details
|
||||
description: How can we get in touch with you if we need more info?
|
||||
placeholder: ex. email@example.com
|
||||
validations:
|
||||
required: false
|
||||
- type: textarea
|
||||
id: what-happened
|
||||
attributes:
|
||||
label: What happened?
|
||||
description: Also tell us, what did you expect to happen?
|
||||
placeholder: Tell us what you see!
|
||||
value: "A bug happened!"
|
||||
validations:
|
||||
required: true
|
||||
- type: dropdown
|
||||
id: version
|
||||
attributes:
|
||||
label: Version
|
||||
description: What version of our software are you running?
|
||||
options:
|
||||
- 1.0.2 (Default)
|
||||
- 1.0.3 (Edge)
|
||||
validations:
|
||||
required: true
|
||||
- type: dropdown
|
||||
id: browsers
|
||||
attributes:
|
||||
label: What browsers are you seeing the problem on?
|
||||
multiple: true
|
||||
options:
|
||||
- Firefox
|
||||
- Chrome
|
||||
- Safari
|
||||
- Microsoft Edge
|
||||
- type: textarea
|
||||
id: logs
|
||||
attributes:
|
||||
label: Relevant log output
|
||||
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
|
||||
render: shell
|
||||
- type: checkboxes
|
||||
id: terms
|
||||
attributes:
|
||||
label: Code of Conduct
|
||||
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
|
||||
options:
|
||||
- label: I agree to follow this project's Code of Conduct
|
||||
required: true
|
||||
```
|
||||
|
||||
### Markdown 段落
|
||||
|
||||
您可以在 YAML 模板中使用 `markdown` 元素为开发者提供额外的上下文支撑，这部分内容会作为创建工单的提示但不会作为工单内容提交。
|
||||
|
||||
`attributes` 子项提供了以下扩展能力：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ------- | ------------------------------ | ---- | ------ | ------ | ------ |
|
||||
| `value` | 渲染的文本。支持 Markdown 格式 | 必选 | 字符串 | - | - |
|
||||
|
||||
### Textarea 多行文本输入框
|
||||
|
||||
您可以使用 `textarea` 元素在表单中添加多行文本输入框。 除了输入文本，开发者还可以在 `textarea` 区域附加文件。
|
||||
|
||||
`attributes` 子项提供了以下扩展能力：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ------------- | ----------------------------------------------------------------------------------------------------- | ---- | ------ | -------- | ------------------ |
|
||||
| `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - |
|
||||
| `description` | 提供上下文或指导的文本区域的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
|
||||
| `placeholder` | 半透明的占位符，在文本区域空白时呈现 | 可选 | 字符串 | 空字符串 | - |
|
||||
| `value` | 在文本区域中预填充的文本。 | 可选 | 字符串 | - | - |
|
||||
| `render` | 如果提供了值，提交的文本将格式化为代码块。 提供此键时，文本区域将不会扩展到文件附件或 Markdown 编辑。 | 可选 | 字符串 | - | Gitea 支持的语言。 |
|
||||
|
||||
`validations` 子项提供以下文本校验参数：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
|
||||
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
|
||||
|
||||
### Input 单行输入框
|
||||
|
||||
您可以使用 `input` 元素添加单行文本字段到表单。
|
||||
|
||||
`attributes` 子项提供了以下扩展能力：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ------------- | ---------------------------------------------- | ---- | ------ | -------- | ------ |
|
||||
| `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - |
|
||||
| `description` | 提供上下文或指导的字段的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
|
||||
| `placeholder` | 半透明的占位符，在字段空白时呈现。 | 可选 | 字符串 | 空字符串 | - |
|
||||
| `value` | 字段中预填的文本。 | 可选 | 字符串 | - | - |
|
||||
|
||||
`validations` 子项提供以下文本校验参数：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ----------- | -------------------------------- | ---- | ------ | ------ | -------------------------------------------------------------- |
|
||||
| `required` | 防止在未填内容时提交表单。 | 可选 | 布尔型 | false | - |
|
||||
| `is_number` | 防止在未填数字时提交表单。 | 可选 | 布尔型 | false | - |
|
||||
| `regex` | 直到满足了与正则表达式匹配的值。 | 可选 | 字符串 | - | [正则表达式](https://en.wikipedia.org/wiki/Regular_expression) |
|
||||
|
||||
### Dropdown 下拉菜单
|
||||
|
||||
您可以使用 `dropdown` 元素在表单中添加下拉菜单。
|
||||
|
||||
`attributes` 子项提供了以下扩展能力：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ------------- | --------------------------------------------------------- | ---- | ---------- | -------- | ------ |
|
||||
| `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - |
|
||||
| `description` | 提供上下文或指导的下拉列表的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
|
||||
| `multiple` | 确定用户是否可以选择多个选项。 | 可选 | 布尔型 | false | - |
|
||||
| `options` | 用户可以选择的选项列表。 不能为空，所有选择必须是不同的。 | 必选 | 字符串数组 | - | - |
|
||||
|
||||
`validations` 子项提供以下文本校验参数：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
|
||||
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
|
||||
|
||||
### Checkboxes 复选框
|
||||
|
||||
您可以使用 `checkboxes` 元素添加一组复选框到表单。
|
||||
|
||||
`attributes` 子项提供了以下扩展能力：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ------------- | ----------------------------------------------------- | ---- | ------ | -------- | ------ |
|
||||
| `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - |
|
||||
| `description` | 复选框集的描述，以表单形式显示。 支持 Markdown 格式。 | 可选 | 字符串 | 空字符串 | - |
|
||||
| `options` | 用户可以选择的复选框列表。 有关语法，请参阅下文。 | 必选 | 数组 | - | - |
|
||||
|
||||
对于 `options`，您可以设置以下参数：
|
||||
|
||||
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
|
||||
| ---------- | --------------------------------------------------------------------------------- | ---- | ------ | ------ | ------ |
|
||||
| `label` | 选项的标识符，显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。 | 必选 | 字符串 | - | - |
|
||||
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
|
||||
33
docs/document/usage/labels.md
Normal file
33
docs/document/usage/labels.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "labels"
|
||||
sidebar_position: 13
|
||||
aliases:
|
||||
- /zh-cn/labels
|
||||
---
|
||||
|
||||
# 标签
|
||||
|
||||
您可以使用标签对工单和合并请求进行分类，并提高对它们的概览。
|
||||
|
||||
## 创建标签
|
||||
|
||||
对于仓库，可以在 `工单（Issues）` 中点击 `标签（Labels）` 来创建标签。
|
||||
|
||||
对于组织，您可以定义组织级别的标签，这些标签与所有组织仓库共享，包括已存在的仓库和新创建的仓库。可以在组织的 `设置（Settings）` 中创建组织级别的标签。
|
||||
|
||||
标签具有必填的名称和颜色，可选的描述，以及必须是独占的或非独占的（见下面的“作用域标签”）。
|
||||
|
||||
当您创建一个仓库时，可以通过使用 `工单标签（Issue Labels）` 选项来选择标签集。该选项列出了一些在您的实例上 [全局配置的可用标签集](../administration/customizing-gitea.md#labels)。在创建仓库时，这些标签也将被创建。
|
||||
|
||||
## 作用域标签
|
||||
|
||||
作用域标签用于确保将至多一个具有相同作用域的标签分配给工单或合并请求。例如，如果标签 `kind/bug` 和 `kind/enhancement` 的独占选项被设置，那么工单只能被分类为 bug 或 enhancement 中的一个。
|
||||
|
||||
作用域标签的名称必须包含 `/`（不能在名称的任一端）。标签的作用域是基于最后一个 `/` 决定的，因此例如标签 `scope/subscope/item` 的作用域是 `scope/subscope`。
|
||||
|
||||
## 按标签筛选
|
||||
|
||||
工单和合并请求列表可以按标签进行筛选。选择多个标签将显示具有所有选定标签的工单和合并请求。
|
||||
|
||||
通过按住 alt 键并单击标签，可以将具有所选标签的工单和合并请求从列表中排除。
|
||||
143
docs/document/usage/linked-references.md
Normal file
143
docs/document/usage/linked-references.md
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "automatically-linked-references"
|
||||
sidebar_position: 15
|
||||
aliases:
|
||||
- /zh-cn/automatically-linked-references
|
||||
---
|
||||
|
||||
# 自动链接引用
|
||||
|
||||
当发布工单、合并请求或评论时，文本描述会被解析以查找引用。这些引用将显示为工单视图中的链接，并且在某些情况下会触发特定的“操作”。
|
||||
|
||||
类似地，当列出提交消息时，它们也会被解析，并且当它们被推送到主分支时可以触发“操作”。
|
||||
|
||||
为了防止意外创建引用，对于引用的识别有一定的规则。例如，它们不应该包含在代码文本内部。它们还应该在周围的文本中合理清晰（例如，使用空格）。
|
||||
|
||||
## 用户、团队和组织提及
|
||||
|
||||
当找到形式为 `@username` 的文本，并且 `username` 与现有用户的名称匹配时，将创建一个“提及”引用。这将通过将文本更改为指向该用户个人资料的链接来显示，并根据被提及的用户是否具有访问内容所需的权限来可能创建通知。
|
||||
|
||||
示例：
|
||||
|
||||
> [@John](#)，你能看一下这个吗？
|
||||
|
||||
对于团队和组织也是有效的：
|
||||
|
||||
> [@Documenters](#)，我们需要为此进行规划。
|
||||
> [@CoolCompanyInc](#)，这个问题关系到我们所有人！
|
||||
|
||||
团队将在适当时收到邮件通知，但整个组织不会收到通知。
|
||||
|
||||
提交消息不会产生用户通知。
|
||||
|
||||
## 提交
|
||||
|
||||
可以使用提交的 SHA1 哈希或至少七个字符的一部分来引用提交。它们将显示为指向相应提交的链接。
|
||||
|
||||
示例：
|
||||
|
||||
> 这个错误是在 [e59ff077](#) 中引入的
|
||||
|
||||
## 工单和合并请求
|
||||
|
||||
可以使用简单的符号 `#1234` 来创建对另一个工单或合并请求的引用，其中 _1234_ 是同一仓库中一个工单或合并请求的编号。这些引用将显示为指向被引用内容的链接。
|
||||
|
||||
创建此类型引用的效果是，在被引用的文档中创建一个“通知”，前提是引用的创建者对其具有读取权限。
|
||||
|
||||
示例：
|
||||
|
||||
> 这似乎与 [#1234](#) 相关
|
||||
|
||||
还可以使用形式 `owner/repository#1234` 来引用其他仓库中的工单和合并请求：
|
||||
|
||||
> 这似乎与 [mike/compiler#1234](#) 相关
|
||||
|
||||
或者也可以使用 `!1234` 符号。虽然在 Gitea 中合并请求是工单的一种形式，但 `#1234` 形式总是链接到工单；如果链接的条目恰好是一个合并请求，Gitea 会适当地进行重定向。而使用 `!1234` 符号，则会创建一个合并请求链接，根据需要会被重定向到工单。然而，如果使用外部跟踪器，这个区别可能很重要，因为工单和合并请求的链接是不能互换的。
|
||||
|
||||
## 可操作的引用在合并请求和提交消息中
|
||||
|
||||
有时，一个提交或合并请求可能会修复或重新出现在某个特定工单中。Gitea 支持在引用之前加上特定的“关键字”来关闭和重新打开被引用的工单。常见的关键字包括“closes”、“fixes”、“reopens”等。这个列表可以由站点管理员进行 [自定义](../administration/config-cheat-sheet.md)。
|
||||
|
||||
示例：
|
||||
|
||||
> 这个合并请求 _closes_ [#1234](#)
|
||||
|
||||
如果可操作的引用被接受，这将在被引用的工单上创建一个通知，宣布当引用的合并请求被合并时该工单将被关闭。
|
||||
|
||||
为了接受可操作的引用，必须满足以下至少一项条件之一：
|
||||
|
||||
- 评论者在创建引用时具有关闭或重新打开工单的权限。
|
||||
- 引用位于提交消息中。
|
||||
- 引用作为合并请求描述的一部分发布。
|
||||
|
||||
在最后一种情况下，只有当合并合并请求的人具有相应权限时，工单才会被关闭或重新打开。
|
||||
|
||||
此外，只有合并请求和提交消息可以创建一个操作，只有工单可以通过这种方式被关闭或重新打开。
|
||||
|
||||
默认的关键字如下：
|
||||
|
||||
- **关闭工单**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
|
||||
- **重新打开工单**: reopen, reopens, reopened
|
||||
|
||||
## 合并请求和提交消息中的时间跟踪
|
||||
|
||||
当提交或合并合并请求导致自动关闭工单时，还可以通过提交消息添加解决此工单所花费的时间。
|
||||
|
||||
要指定解决工单所花费的时间，需要在工单编号后面以 `@<number><time-unit>` 的格式指定时间。在一个提交消息中，可以指定多个已解决的工单，并为每个工单指定花费的时间。
|
||||
|
||||
支持的时间单位（`<time-unit>`）：
|
||||
|
||||
- `m` - 分钟
|
||||
- `h` - 小时
|
||||
- `d` - 天（相当于 8 小时）
|
||||
- `w` - 周（相当于 5 天）
|
||||
- `mo` - 月（相当于 4 周）
|
||||
|
||||
用于指定时间的数字（`<number>`）也可以是小数，例如 `@1.5h` 表示一小时半。多个时间单位可以结合使用，例如 `@1h10m` 表示 1 小时 10 分钟。
|
||||
|
||||
提交消息示例：
|
||||
|
||||
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
|
||||
|
||||
这将导致工单 #123 增加 1 小时，工单 #124 增加 1 小时半。
|
||||
|
||||
## 外部跟踪器
|
||||
|
||||
Gitea 支持使用外部工单跟踪器，并可以在合并请求中创建对外部托管的工单的引用。但是，如果外部跟踪器使用数字来标识工单，那么它们将与 Gitea 中托管的合并请求无法区分。为了解决这个问题，Gitea 允许使用 `!` 标记来标识合并请求。例如：
|
||||
|
||||
> 这是工单 [#1234](#)，并链接到外部跟踪器。
|
||||
> 这是合并请求 [!1234](#)，并链接到 Gitea 中的合并请求。
|
||||
|
||||
在工单和合并请求中，`!` 和 `#` 可以互换使用，除非需要进行区分。如果仓库使用外部跟踪器，默认情况下，合并提交消息将使用 `!` 作为引用。
|
||||
|
||||
## 工单和合并请求引用摘要
|
||||
|
||||
下表说明了工单和合并请求的不同类型的交叉引用。在示例中，`User1/Repo1` 指的是使用引用的仓库，而 `UserZ/RepoZ` 表示另一个仓库。
|
||||
|
||||
| 在 User1/Repo1 中的引用 | Repo1 的工单是外部的 | RepoZ 的工单是外部的 | 渲染效果 |
|
||||
| ----------------------- | :------------------: | :------------------: | --------------------------------------------- |
|
||||
| `#1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
|
||||
| `!1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
|
||||
| `#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ 1234 |
|
||||
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||||
| `User1/Repo1#1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
|
||||
| `User1/Repo1!1234` | 否 | - | 链接到 `User1/Repo1` 中的工单/合并请求 1234 |
|
||||
| `User1/Repo1#1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ 1234 |
|
||||
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||||
| `UserZ/RepoZ#1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234 |
|
||||
| `UserZ/RepoZ!1234` | - | 否 | 链接到 `UserZ/RepoZ` 中的工单/合并请求 1234 |
|
||||
| `UserZ/RepoZ#1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工单_ 1234 |
|
||||
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 的 _PR_ 1234 |
|
||||
| **字母数字工单编号:** | - | - | - |
|
||||
| `AAA-1234` | 是 | - | 链接到 `User1/Repo1` 的 _外部工单_ `AAA-1234` |
|
||||
| `!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||||
| `User1/Repo1!1234` | 是 | - | 链接到 `User1/Repo1` 的 _PR_ 1234 |
|
||||
| _不支持_ | - | 是 | 链接到 `UserZ/RepoZ` 的 _外部工单_ `AAA-1234` |
|
||||
| `UserZ/RepoZ!1234` | - | 是 | 链接到 `UserZ/RepoZ` 中的 _PR_ 1234 |
|
||||
|
||||
_最后一部分适用于使用字母数字格式的外部工单跟踪器的仓库。_
|
||||
|
||||
_**-**: 不适用_
|
||||
|
||||
注意：不完全支持具有不同类型工单（外部 vs. 内部）的仓库之间的自动引用，可能会导致无效链接。
|
||||
102
docs/document/usage/markdown.md
Normal file
102
docs/document/usage/markdown.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
date: "2025-04-05T00:00:00+08:00"
|
||||
slug: "markdown"
|
||||
---
|
||||
|
||||
# Markdown
|
||||
|
||||
Gitea uses MarkDown structured text in many places, you can recognise it by the `.md` file extension.
|
||||
Markdown is plain text format for writing structured documents, allowing one to write
|
||||
"plain" text files that nonetheless have _"fancy"_ **formatting**, while still keeping the plain-text version readable.
|
||||
|
||||
Unfortunately, due to historical implementation differences, many subtle dialects exist.
|
||||
To avoid adding to the confusion, Gitea tries to follow "[GitHub Flavoured Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/)" as close as possible.
|
||||
"GFM" is an extension on top of the rigorously-specified [CommonMark](https://commonmark.org/) standard.
|
||||
CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse)
|
||||
and git forges (GitHub, GitLab and our very own Gitea), thus you shouldn't run into any surprises with Gitea.
|
||||
|
||||
For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation:
|
||||
- [Basic formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
|
||||
- [Advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting)
|
||||
|
||||
For a deeper history about CommonMark, its spec, and its reason for existence, see [CommonMark.org](https://commonmark.org/).
|
||||
|
||||
## Rendering options
|
||||
|
||||
Some Gitea's markdown rendering behaviors can be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
|
||||
|
||||
|
||||
## Link path resolving
|
||||
|
||||
When rendering links for `<a href>`, `<img src>` and `<video src>`, Gitea resolves the link paths in the rendering context.
|
||||
|
||||
- If the link is an absolute path with scheme, the link is kept as-is.
|
||||
- If the link is an URL path, it is resolved with the base path of current rendering context.
|
||||
- In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: `/owner-name/repo-name`.
|
||||
- In a repository file context (markdown files in the repository), the base path is current git ref path.
|
||||
|
||||
### Special link tokens
|
||||
|
||||
To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
|
||||
This will always resolve to Gitea's ROOT_URL.
|
||||
|
||||
Gitea also supports GitHub's `?raw=1` query parameter.
|
||||
A request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to
|
||||
`/owner-name/repo-name/raw/branch/main/file`. This makes it possible to target raw contents from relative links
|
||||
(normally, the `src/` section of the path is provided automatically by Gitea and cannot be overriden).
|
||||
|
||||
### Link handling examples
|
||||
|
||||
For example, when rendering a markdown file in `/owner-name/repo-name/src/branch/main/dir`:
|
||||
1) Absolute with scheme: Link `https://example.org` will be rendered as-is.
|
||||
2) Relative from current file: Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
|
||||
3) Relative from repo root: Link `/sub/file` (note leading slash) is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
|
||||
4) Raw media: If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
|
||||
5) Raw relative: `sub/file?raw=1` will resolve to `/owner-name/repo-name/src/branch/main/dir/sub/file?raw=1`,
|
||||
which will redirect to `/owner-name/repo-name/raw/branch/main/dir/sub/file`.
|
||||
6) explicit root: Link `/:root/any-path` is always resolved to `$ROOT_URL/any-path` without any further processing.
|
||||
|
||||
|
||||
## Issue and pull-request reference
|
||||
|
||||
Using issue/pull-request numbers in a list:
|
||||
|
||||
```
|
||||
* #123
|
||||
* #456
|
||||
```
|
||||
|
||||
It will be rendered with issue titles to:
|
||||
|
||||
```
|
||||
* the issue title (#123)
|
||||
* the other issue title (#456)
|
||||
```
|
||||
|
||||
## Math expressions
|
||||
|
||||
Gitea supports GitHub-like math expression formatting.
|
||||
|
||||
### Inline expression
|
||||
|
||||
- ``` $\alpha$ ```: quoted by single-dollar `$`
|
||||
- ``` $$\alpha$$ ```: quoted by double-dollar `$$`
|
||||
- ``` $`\alpha`$ ```: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.
|
||||
|
||||
### Block expression
|
||||
|
||||
Using `$$`:
|
||||
|
||||
````
|
||||
$$
|
||||
\alpha
|
||||
$$
|
||||
````
|
||||
|
||||
Using code-block with language:
|
||||
|
||||
````
|
||||
```math
|
||||
\alpha
|
||||
```
|
||||
````
|
||||
47
docs/document/usage/merge-message-templates.md
Normal file
47
docs/document/usage/merge-message-templates.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "merge-message-templates"
|
||||
sidebar_position: 15
|
||||
|
||||
aliases:
|
||||
- /zh-cn/merge-message-templates
|
||||
---
|
||||
|
||||
# 合并消息模板
|
||||
|
||||
## 文件名
|
||||
|
||||
PR 默认合并消息模板可能的文件名：
|
||||
|
||||
- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
|
||||
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
|
||||
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
|
||||
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
|
||||
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
|
||||
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
|
||||
|
||||
## 变量
|
||||
|
||||
您可以在这些模板中使用以下以 `${}` 包围的变量，这些变量遵循 [os.Expand](https://pkg.go.dev/os#Expand) 语法：
|
||||
|
||||
- BaseRepoOwnerName：此合并请求的基础仓库所有者名称
|
||||
- BaseRepoName：此合并请求的基础仓库名称
|
||||
- BaseBranch：此合并请求的基础仓库目标分支名称
|
||||
- HeadRepoOwnerName：此合并请求的源仓库所有者名称
|
||||
- HeadRepoName：此合并请求的源仓库名称
|
||||
- HeadBranch：此合并请求的源仓库分支名称
|
||||
- PullRequestTitle：合并请求的标题
|
||||
- PullRequestDescription：合并请求的描述
|
||||
- PullRequestPosterName：合并请求的提交者名称
|
||||
- PullRequestIndex：合并请求的索引号
|
||||
- PullRequestReference：合并请求的引用字符与索引号。例如，#1、!2
|
||||
- ClosingIssues：返回一个包含将由此合并请求关闭的所有工单的字符串。例如 `close #1, close #2`
|
||||
- ReviewedOn: 该提交所属的合并请求。例如： `Reviewed-on: https://gitea.com/foo/bar/pulls/1`
|
||||
- ReviewedBy: 谁同意的此合并请求。例如： `Reviewed-by: Jane Doe <jane.doe@example.com>`
|
||||
|
||||
## 变基（Rebase）
|
||||
|
||||
在没有合并提交的情况下进行变基时，`REBASE_TEMPLATE.md` 修改最后一次提交的消息。此模板还提供以下附加变量：
|
||||
|
||||
- CommitTitle：提交的标题
|
||||
- CommitBody：提交的正文文本
|
||||
53
docs/document/usage/migration.md
Normal file
53
docs/document/usage/migration.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
date: "2024-09-11T09:30:00+08:00"
|
||||
slug: "migration"
|
||||
sidebar_position: 45
|
||||
---
|
||||
|
||||
# Migration
|
||||
|
||||
You can migrate repositories from other Git services to your Gitea instance.
|
||||
|
||||
## How to migrate from Gogs/GitHub/GitLab to Gitea
|
||||
|
||||
To migrate from Gogs to Gitea:
|
||||
|
||||
- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
|
||||
|
||||
To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
|
||||
|
||||
In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
|
||||
|
||||
[Example (requires login)](https://demo.gitea.com/repo/migrate)
|
||||
|
||||
To migrate from GitLab to Gitea, you can use this non-affiliated tool:
|
||||
|
||||
https://github.com/loganinak/MigrateGitlabToGogs
|
||||
|
||||
## How to migrate from AWS CodeCommit to Gitea
|
||||
|
||||
- To use the AWS CodeCommit API, Gitea requires an access key ID and a secret access key. For security reasons, we recommend creating a new user with the minimum necessary permissions and generating an access key ID and secret access key for the migration. The minimum permissions required for this user are as follows:
|
||||
```
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"codecommit:GetRepository",
|
||||
"codecommit:GitPull",
|
||||
"codecommit:ListPullRequests",
|
||||
"codecommit:GetPullRequest",
|
||||
"codecommit:GetCommentsForPullRequest"
|
||||
],
|
||||
"Resource": [
|
||||
"arn:aws:codecommit:<region>:<account>:<Repo-to-Migrate>
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
- If you do not need to migrate pull requests, you can remove the `ListPullRequests`, `GetPullRequest`, and `GetCommentsForPullRequest` actions.
|
||||
|
||||
- For instructions on how to create an IAM user and assign permissions, you can refer to this [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
|
||||
|
||||
- To clone this repository, Gitea requires HTTPS Git credentials. You can create HTTPS Git credentials according to this [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html).
|
||||
28
docs/document/usage/multi-factor-authentication.md
Normal file
28
docs/document/usage/multi-factor-authentication.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
date: "2023-08-22T14:21:00+08:00"
|
||||
slug: "multi-factor-authentication"
|
||||
weight: 15
|
||||
---
|
||||
|
||||
# Multi-factor Authentication (MFA)
|
||||
|
||||
Multi-factor Authentication (also referred to as MFA or 2FA) enhances security by requiring a time-sensitive set of credentials in addition to a password.
|
||||
If a password were later to be compromised, logging into Gitea will not be possible without the additional credentials and the account would remain secure.
|
||||
Gitea supports both TOTP (Time-based One-Time Password) tokens and FIDO-based hardware keys using the Webauthn API.
|
||||
|
||||
MFA can be configured within the "Security" tab of the user settings page.
|
||||
|
||||
## MFA Considerations
|
||||
|
||||
Enabling MFA on a user does affect how the Git HTTP protocol can be used with the Git CLI.
|
||||
This interface does not support MFA, and trying to use a password normally will no longer be possible whilst MFA is enabled.
|
||||
If SSH is not an option for Git operations, an access token can be generated within the "Applications" tab of the user settings page.
|
||||
This access token can be used as if it were a password in order to allow the Git CLI to function over HTTP.
|
||||
|
||||
:::warning
|
||||
By its very nature, an access token sidesteps the security benefits of MFA.
|
||||
It must be kept secure and should only be used as a last resort.
|
||||
:::
|
||||
|
||||
The Gitea API supports providing the relevant TOTP password in the `X-Gitea-OTP` header, as described in [API Usage](development/api-usage.md).
|
||||
This should be used instead of an access token where possible.
|
||||
121
docs/document/usage/packages/alpine.md
Normal file
121
docs/document/usage/packages/alpine.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
date: "2023-03-25T00:00:00+00:00"
|
||||
slug: "alpine"
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Alpine 软件包注册表
|
||||
|
||||
在您的用户或组织中发布 [Alpine](https://pkgs.alpinelinux.org/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Alpine 注册表，您需要使用像 curl 这样的 HTTP 客户端来上传包，并使用像 apk 这样的包管理器来消费包。
|
||||
|
||||
以下示例使用 `apk`。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册 Alpine 注册表，请将 URL 添加到已知的 apk 源列表中 (`/etc/apk/repositories`):
|
||||
|
||||
```
|
||||
https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ------------ | -------------- |
|
||||
| `owner` | 软件包所有者 |
|
||||
| `branch` | 要使用的分支名 |
|
||||
| `repository` | 要使用的仓库名 |
|
||||
|
||||
如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌](development/api-usage.md#通过-api-认证):
|
||||
|
||||
```
|
||||
https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository>
|
||||
```
|
||||
|
||||
Alpine 注册表文件使用 RSA 密钥进行签名，apk 必须知道该密钥。下载公钥并将其存储在 `/etc/apk/keys/` 目录中：
|
||||
|
||||
```shell
|
||||
curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key
|
||||
```
|
||||
|
||||
之后，更新本地软件包索引：
|
||||
|
||||
```shell
|
||||
apk update
|
||||
```
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布一个 Alpine 包（`*.apk`），请执行带有包内容的 HTTP `PUT` 操作，将其放在请求体中。
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------------ | --------------------------------------------------------------------------------------------------- |
|
||||
| `owner` | 包的所有者。 |
|
||||
| `branch` | 分支可以与操作系统的发行版本匹配，例如：v3.17。 |
|
||||
| `repository` | 仓库可以用于[分组包](https://wiki.alpinelinux.org/wiki/Repositories) 或者只是 `main` 或类似的名称。 |
|
||||
|
||||
使用 HTTP 基本身份验证的示例请求：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
如果您使用的是双重身份验证或 OAuth，请使用[个人访问令牌](development/api-usage.md#authentication)代替密码。
|
||||
您不能将具有相同名称的文件两次发布到一个包中。您必须首先删除现有的包文件。
|
||||
|
||||
服务器将以以下的 HTTP 状态码响应：
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ----------------- | ------------------------------------------ |
|
||||
| `201 Created` | 软件包已发布。 |
|
||||
| `400 Bad Request` | 软件包的名称、版本、分支、仓库或架构无效。 |
|
||||
| `409 Conflict` | 具有相同参数组合的包文件已存在于软件包中。 |
|
||||
|
||||
## 删除软件包
|
||||
|
||||
要删除 Alpine 包，执行 HTTP 的 DELETE 操作。如果没有文件，这将同时删除包版本。
|
||||
|
||||
```
|
||||
DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `branch` | 要使用的分支名 |
|
||||
| `repository` | 要使用的仓库名 |
|
||||
| `architecture` | 软件包的架构 |
|
||||
| `filename` | 要删除的文件名 |
|
||||
|
||||
使用 HTTP 基本身份验证的示例请求：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
服务器将以以下的 HTTP 状态码响应：
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ---------------- | ------------------ |
|
||||
| `204 No Content` | 成功 |
|
||||
| `404 Not Found` | 未找到软件包或文件 |
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从 Alpine 注册表安装软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
# use latest version
|
||||
apk add {package_name}
|
||||
# use specific version
|
||||
apk add {package_name}={package_version}
|
||||
```
|
||||
132
docs/document/usage/packages/arch.md
Normal file
132
docs/document/usage/packages/arch.md
Normal 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. |
|
||||
98
docs/document/usage/packages/cargo.md
Normal file
98
docs/document/usage/packages/cargo.md
Normal file
@@ -0,0 +1,98 @@
|
||||
---
|
||||
date: "2022-11-20T00:00:00+00:00"
|
||||
slug: "cargo"
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Cargo 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Cargo](https://doc.rust-lang.org/stable/cargo/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
若要使用 Cargo 软件包注册表, 您需要安装 [Rust 和 Cargo](https://www.rust-lang.org/tools/install).
|
||||
|
||||
Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。
|
||||
这个仓库是与注册表交互所必需的。
|
||||
下面的部分将介绍如何创建它。
|
||||
|
||||
## 索引仓库
|
||||
|
||||
Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。
|
||||
在 Gitea 中，这个仓库有一个特殊的名称叫做 `_cargo-index`。
|
||||
在上传软件包之后，它的元数据会自动写入索引中。
|
||||
不应手动修改这个注册表的内容。
|
||||
|
||||
用户或组织软件包设置页面允许创建这个索引仓库以及配置文件。
|
||||
如果需要，此操作将重写配置文件。
|
||||
例如，如果 Gitea 实例的域名已更改，这将非常有用。
|
||||
|
||||
如果存储在 Gitea 中的软件包与索引注册表中的信息不同步，设置页面允许重建这个索引注册表。
|
||||
这个操作将遍历注册表中的所有软件包，并将它们的信息写入索引中。
|
||||
如果有很多软件包，这个过程可能需要一些时间。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册这个软件包注册表，必须更新 Cargo 的配置。
|
||||
将以下文本添加到位于当前用户主目录中的配置文件中（例如 `~/.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
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | ---------------- |
|
||||
| `owner` | 软件包的所有者。 |
|
||||
|
||||
如果这个注册表是私有的或者您想要发布新的软件包，您必须配置您的凭据。
|
||||
将凭据部分添加到位于当前用户主目录中的凭据文件中（例如 `~/.cargo/credentials.toml`）：
|
||||
|
||||
```
|
||||
[registries.gitea]
|
||||
token = "Bearer {token}"
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | ------------------------------------------------------------------------------------- |
|
||||
| `token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证) |
|
||||
|
||||
## 发布软件包
|
||||
|
||||
在项目中运行以下命令来发布软件包：
|
||||
|
||||
```shell
|
||||
cargo publish
|
||||
```
|
||||
|
||||
如果已经存在同名和版本的软件包，您将无法发布新的软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表安装软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
cargo add {package_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ------------ |
|
||||
| `package_name` | 软件包名称。 |
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
cargo publish
|
||||
cargo add
|
||||
cargo install
|
||||
cargo yank
|
||||
cargo unyank
|
||||
cargo search
|
||||
```
|
||||
84
docs/document/usage/packages/chef.md
Normal file
84
docs/document/usage/packages/chef.md
Normal file
@@ -0,0 +1,84 @@
|
||||
---
|
||||
date: "2023-01-20T00:00:00+00:00"
|
||||
slug: "chef"
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Chef 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Chef](https://chef.io/) cookbooks。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Chef 软件包注册表，您需要使用 [`knife`](https://docs.chef.io/workstation/knife/).
|
||||
|
||||
## 认证
|
||||
|
||||
Chef 软件包注册表不使用用户名和密码进行身份验证，而是使用私钥和公钥对请求进行签名。
|
||||
请访问软件包所有者设置页面以创建必要的密钥对。
|
||||
只有公钥存储在Gitea中。如果您丢失了私钥的访问权限，您必须重新生成密钥对。
|
||||
[配置 `knife`](https://docs.chef.io/workstation/knife_setup/)，使用下载的私钥，并将 Gitea 用户名设置为 `client_name`。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要将 [`knife` 配置](https://docs.chef.io/workstation/knife_setup/)为使用 Gitea 软件包注册表，请将 URL 添加到 `~/.chef/config.rb` 文件中。
|
||||
|
||||
```
|
||||
knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef'
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
## 发布软件包
|
||||
|
||||
若要发布 Chef 软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
knife supermarket share {package_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ---------- |
|
||||
| `package_name` | 软件包名称 |
|
||||
|
||||
如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表中安装软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
knife supermarket install {package_name}
|
||||
```
|
||||
|
||||
您可以指定软件包的版本，这是可选的：
|
||||
|
||||
```shell
|
||||
knife supermarket install {package_name} {package_version}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | ---------- |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
|
||||
## 删除软件包
|
||||
|
||||
如果您想要从注册表中删除软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
knife supermarket unshare {package_name}
|
||||
```
|
||||
|
||||
可选地，您可以指定软件包的版本：
|
||||
|
||||
```shell
|
||||
knife supermarket unshare {package_name}/versions/{package_version}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | ---------- |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
110
docs/document/usage/packages/composer.md
Normal file
110
docs/document/usage/packages/composer.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "composer"
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
# Composer 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Composer](https://getcomposer.org/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Composer 软件包注册表，您可以使用 [Composer](https://getcomposer.org/download/) 消费，并使用类似 `curl` 的 HTTP 上传客户端发布软件包。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布 Composer 软件包，请执行 HTTP `PUT` 操作，将软件包内容放入请求体中。
|
||||
软件包内容必须是包含 `composer.json` 文件的压缩 PHP 项目。
|
||||
如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/composer
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
如果 `composer.json` 文件不包含 `version` 属性，您必须将其作为查询参数提供：
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z}
|
||||
```
|
||||
|
||||
使用 HTTP 基本身份验证的示例请求：
|
||||
|
||||
```shell
|
||||
curl --user your_username:your_password_or_token \
|
||||
--upload-file path/to/project.zip \
|
||||
https://gitea.example.com/api/packages/testuser/composer
|
||||
```
|
||||
|
||||
或者将软件包版本指定为查询参数：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。
|
||||
|
||||
服务器将以以下 HTTP 状态码响应。
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ----------------- | ----------------------------------------------------------- |
|
||||
| `201 Created` | 软件包已发布 |
|
||||
| `400 Bad Request` | 软件包名称和/或版本无效，或具有相同名称和版本的软件包已存在 |
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，您需要将其添加到 Composer 的 `config.json` 文件中（通常可以在 `<user-home-dir>/.composer/config.json` 中找到）：
|
||||
|
||||
```json
|
||||
{
|
||||
"repositories": [{
|
||||
"type": "composer",
|
||||
"url": "https://gitea.example.com/api/packages/{owner}/composer"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
要使用凭据访问软件包注册表，您必须在 `auth.json` 文件中指定它们，如下所示：
|
||||
|
||||
```json
|
||||
{
|
||||
"http-basic": {
|
||||
"gitea.example.com": {
|
||||
"username": "{username}",
|
||||
"password": "{password}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ---------- | --------------------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `username` | 您的 Gitea 用户名 |
|
||||
| `password` | 您的Gitea密码或个人访问令牌 |
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表中安装软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
composer require {package_name}
|
||||
```
|
||||
|
||||
您可以指定软件包的版本，这是可选的：
|
||||
|
||||
```shell
|
||||
composer require {package_name}:{package_version}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | ---------- |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
89
docs/document/usage/packages/conan.md
Normal file
89
docs/document/usage/packages/conan.md
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "conan"
|
||||
sidebar_position: 20
|
||||
---
|
||||
|
||||
# Conan 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Conan](https://conan.io/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 [conan](https://conan.io/downloads.html) 软件包注册表，您需要使用 conan 命令行工具来消费和发布软件包。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，您需要配置一个新的 Conan remote：
|
||||
|
||||
```shell
|
||||
conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan
|
||||
conan user --remote {remote} --password {password} {username}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `remote` | 远程名称。 |
|
||||
| `username` | 您的 Gitea 用户名。 |
|
||||
| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。 |
|
||||
| `owner` | 软件包的所有者。 |
|
||||
|
||||
例如:
|
||||
|
||||
```shell
|
||||
conan remote add gitea https://gitea.example.com/api/packages/testuser/conan
|
||||
conan user --remote gitea --password password123 testuser
|
||||
```
|
||||
|
||||
## 发布软件包
|
||||
|
||||
通过运行以下命令发布 Conan 软件包：
|
||||
|
||||
```shell
|
||||
conan upload --remote={remote} {recipe}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------- | --------------- |
|
||||
| `remote` | 远程名称 |
|
||||
| `recipe` | 要上传的 recipe |
|
||||
|
||||
For example:
|
||||
|
||||
```shell
|
||||
conan upload --remote=gitea ConanPackage/1.2@gitea/final
|
||||
```
|
||||
|
||||
Gitea Conan 软件包注册表支持完整的[版本修订](https://docs.conan.io/en/latest/versioning/revisions.html)。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表中安装Conan软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
conan install --remote={remote} {recipe}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------- | --------------- |
|
||||
| `remote` | 远程名称 |
|
||||
| `recipe` | 要下载的 recipe |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
conan install --remote=gitea ConanPackage/1.2@gitea/final
|
||||
```
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
conan install
|
||||
conan get
|
||||
conan info
|
||||
conan search
|
||||
conan upload
|
||||
conan user
|
||||
conan download
|
||||
conan remove
|
||||
```
|
||||
73
docs/document/usage/packages/conda.md
Normal file
73
docs/document/usage/packages/conda.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
date: "2022-12-28T00:00:00+00:00"
|
||||
slug: "conda"
|
||||
sidebar_position: 25
|
||||
---
|
||||
|
||||
# Conda 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Conda](https://docs.conda.io/en/latest/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Conda 软件包注册表，您需要使用 [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) 命令行工具。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表并提供凭据，请编辑您的 `.condarc` 文件：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
有关各个设置的解释，请参阅[官方文档](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html)。
|
||||
|
||||
如果需要提供凭据，可以将它们作为通道 URL 的一部分嵌入（`https://user:password@gitea.example.com/...`）。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布一个软件包，请执行一个HTTP `PUT`操作，请求正文中包含软件包内容。
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename}
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ---------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `channel` | 软件包的[通道](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html)（可选） |
|
||||
| `filename` | 文件名 |
|
||||
|
||||
使用HTTP基本身份验证的示例请求：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
如果已经存在同名和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表中安装软件包，请执行以下命令之一：
|
||||
|
||||
```shell
|
||||
conda install {package_name}
|
||||
conda install {package_name}={package_version}
|
||||
conda install -c {channel} {package_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | -------------------- |
|
||||
| `package_name` | 软件包的名称 |
|
||||
| `package_version` | 软件包的版本 |
|
||||
| `channel` | 软件包的通道（可选） |
|
||||
81
docs/document/usage/packages/container.md
Normal file
81
docs/document/usage/packages/container.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "container"
|
||||
sidebar_position: 30
|
||||
---
|
||||
|
||||
# 容器注册表
|
||||
|
||||
为您的用户或组织发布符合 [Open Container Initiative(OCI)](https://opencontainers.org/) 规范的镜像。
|
||||
该容器注册表遵循 OCI 规范，并支持所有兼容的镜像类型，如 [Docker](https://www.docker.com/) 和 [Helm Charts](https://helm.sh/)。
|
||||
|
||||
## 目录
|
||||
|
||||
要使用容器注册表，您可以使用适用于特定镜像类型的工具。
|
||||
以下示例使用 `docker` 客户端。
|
||||
|
||||
## 登录容器注册表
|
||||
|
||||
要推送镜像或者如果镜像位于私有注册表中，您需要进行身份验证：
|
||||
|
||||
```shell
|
||||
docker login gitea.example.com
|
||||
```
|
||||
|
||||
如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码进行身份验证。
|
||||
|
||||
## 镜像命名约定
|
||||
|
||||
镜像必须遵循以下命名约定：
|
||||
|
||||
`{registry}/{owner}/{image}`
|
||||
|
||||
例如，以下是所有者为 `testuser` 的有效镜像名称示例：
|
||||
|
||||
`gitea.example.com/testuser/myimage`
|
||||
|
||||
`gitea.example.com/testuser/my-image`
|
||||
|
||||
`gitea.example.com/testuser/my/image`
|
||||
|
||||
**注意:** 该注册表仅支持大小写不敏感的标签名称。因此，`image:tag` 和 `image:Tag` 将被视为相同的镜像和标签。
|
||||
|
||||
## 推送镜像
|
||||
|
||||
通过执行以下命令来推送镜像：
|
||||
|
||||
```shell
|
||||
docker push gitea.example.com/{owner}/{image}:{tag}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | ------------ |
|
||||
| `owner` | 镜像的所有者 |
|
||||
| `image` | 镜像的名称 |
|
||||
| `tag` | 镜像的标签 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
docker push gitea.example.com/testuser/myimage:latest
|
||||
```
|
||||
|
||||
## 拉取镜像
|
||||
|
||||
通过执行以下命令来拉取镜像：
|
||||
|
||||
```shell
|
||||
docker pull gitea.example.com/{owner}/{image}:{tag}
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| --------- | ------------ |
|
||||
| `owner` | 镜像的所有者 |
|
||||
| `image` | 镜像的名称 |
|
||||
| `tag` | 镜像的标签 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
docker pull gitea.example.com/testuser/myimage:latest
|
||||
```
|
||||
81
docs/document/usage/packages/cran.md
Normal file
81
docs/document/usage/packages/cran.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
date: "2023-01-01T00:00:00+00:00"
|
||||
slug: "cran"
|
||||
sidebar_position: 35
|
||||
---
|
||||
|
||||
# CRAN 软件包注册表
|
||||
|
||||
将 [R](https://www.r-project.org/) 软件包发布到您的用户或组织的类似 [CRAN](https://cran.r-project.org/) 的注册表。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用CRAN软件包注册表，您需要安装 [R](https://cran.r-project.org/)。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，您需要将其添加到 `Rprofile.site` 文件中，可以是系统级别、用户级别 `~/.Rprofile` 或项目级别：
|
||||
|
||||
```
|
||||
options("repos" = c(getOption("repos"), c(gitea="https://gitea.example.com/api/packages/{owner}/cran")))
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
如果需要提供凭据，可以将它们嵌入到URL(`https://user:password@gitea.example.com/...`)中。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布 R 软件包，请执行带有软件包内容的 HTTP `PUT` 操作。
|
||||
|
||||
源代码软件包：
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/cran/src
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
二进制软件包：
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ---------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `platform` | 平台的名称 |
|
||||
| `rversion` | 二进制的R版本 |
|
||||
|
||||
例如：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
如果同名和版本的软件包已存在，则无法发布软件包。您必须首先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表中安装R软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
install.packages("{package_name}")
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ----------------- |
|
||||
| `package_name` | The package name. |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
install.packages("testpackage")
|
||||
```
|
||||
121
docs/document/usage/packages/debian.md
Normal file
121
docs/document/usage/packages/debian.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
date: "2023-01-07T00:00:00+00:00"
|
||||
slug: "debian"
|
||||
---
|
||||
|
||||
# Debian 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Debian](https://www.debian.org/distrib/packages) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Debian 注册表，您需要使用类似于 `curl` 的 HTTP 客户端进行上传，并使用类似于 `apt` 的软件包管理器消费软件包。
|
||||
|
||||
以下示例使用 `apt`。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册 Debian 注册表，请将 URL 添加到已知 `apt` 源列表中：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| -------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `distribution` | 要使用的发行版 |
|
||||
| `component` | 要使用的组件 |
|
||||
|
||||
如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌](development/api-usage.md#通过-api-认证)：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Debian 注册表文件使用 PGP 密钥进行签名，`apt` 必须知道该密钥：
|
||||
|
||||
```shell
|
||||
sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/keyrings/gitea-{owner}.asc
|
||||
```
|
||||
|
||||
然后更新本地软件包索引：
|
||||
|
||||
```shell
|
||||
apt update
|
||||
```
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布一个 Debian 软件包（`*.deb`），执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ----------------------------------------------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `distribution` | 发行版，可能与操作系统的发行版名称匹配，例如 `bionic` |
|
||||
| `component` | 组件，可用于分组软件包，或仅为 `main` 或类似的组件。 |
|
||||
|
||||
使用 HTTP 基本身份验证的示例请求：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。
|
||||
您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。
|
||||
|
||||
服务器将使用以下 HTTP 状态代码进行响应。
|
||||
|
||||
| HTTP 状态码 | 意义 |
|
||||
| ----------------- | ---------------------------------------- |
|
||||
| `201 Created` | 软件包已发布 |
|
||||
| `400 Bad Request` | 软件包名称、版本、发行版、组件或架构无效 |
|
||||
| `409 Conflict` | 具有相同参数组合的软件包文件已经存在 |
|
||||
|
||||
## 删除软件包
|
||||
|
||||
要删除 Debian 软件包，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。
|
||||
|
||||
```
|
||||
DELETE https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
| `distribution` | 软件包发行版 |
|
||||
| `component` | 软件包组件 |
|
||||
| `architecture` | 软件包架构 |
|
||||
|
||||
使用 HTTP 基本身份验证的示例请求：
|
||||
|
||||
```shell
|
||||
curl --user your_username:your_token_or_password -X DELETE \
|
||||
https://gitea.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64
|
||||
```
|
||||
|
||||
服务器将使用以下 HTTP 状态代码进行响应。
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ---------------- | ------------------ |
|
||||
| `204 No Content` | 成功 |
|
||||
| `404 Not Found` | 找不到软件包或文件 |
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从 Debian 注册表安装软件包，请执行以下命令:
|
||||
|
||||
```shell
|
||||
# use latest version
|
||||
apt install {package_name}
|
||||
# use specific version
|
||||
apt install {package_name}={package_version}
|
||||
```
|
||||
135
docs/document/usage/packages/generic.md
Normal file
135
docs/document/usage/packages/generic.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "generic"
|
||||
sidebar_position: 500
|
||||
---
|
||||
|
||||
# 通用软件包注册表
|
||||
|
||||
发布通用文件，如发布二进制文件或其他输出，供您的用户或组织使用。
|
||||
|
||||
## 身份验证软件包注册表
|
||||
|
||||
要身份验证软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证](development/api-usage.md#通过-api-认证)。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布通用软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
|
||||
您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `owner` | 软件包的所有者。 |
|
||||
| `package_name` | 软件包名称。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) |
|
||||
| `package_version` | 软件包版本，一个非空字符串，不包含前导或尾随空格 |
|
||||
| `file_name` | 文件名。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) |
|
||||
|
||||
使用 HTTP 基本身份验证的示例请求：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。
|
||||
|
||||
服务器将使用以下 HTTP 状态代码进行响应。
|
||||
|
||||
| HTTP 状态码 | 意义 |
|
||||
| ----------------- | ---------------------------------- |
|
||||
| `201 Created` | 软件包已发布 |
|
||||
| `400 Bad Request` | 软件包名称和/或版本和/或文件名无效 |
|
||||
| `409 Conflict` | 具有相同名称的文件已存在于软件包中 |
|
||||
|
||||
## 下载软件包
|
||||
|
||||
要下载通用软件包，请执行 HTTP `GET` 操作。
|
||||
|
||||
```
|
||||
GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
| `file_name` | 文件名 |
|
||||
|
||||
文件内容将在响应主体中返回。响应的内容类型为 `application/octet-stream`。
|
||||
|
||||
服务器将使用以下 HTTP 状态代码进行响应。
|
||||
|
||||
```shell
|
||||
curl --user your_username:your_token_or_password \
|
||||
https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
|
||||
```
|
||||
|
||||
服务器会以以下 HTTP 状态码进行响应：
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| --------------- | -------------------- |
|
||||
| `200 OK` | 成功 |
|
||||
| `404 Not Found` | 找不到软件包或者文件 |
|
||||
|
||||
## 删除软件包
|
||||
|
||||
要删除通用软件包，请执行 HTTP DELETE 操作。这将同时删除该版本的所有文件。
|
||||
|
||||
```
|
||||
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
|
||||
服务器将使用以下 HTTP 状态代码进行响应。
|
||||
|
||||
```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 状态码 | 意义 |
|
||||
| ---------------- | ------------ |
|
||||
| `204 No Content` | 成功 |
|
||||
| `404 Not Found` | 找不到软件包 |
|
||||
|
||||
## 删除软件包文件
|
||||
|
||||
要删除通用软件包的文件，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。
|
||||
|
||||
```
|
||||
DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
| `filename` | 文件名 |
|
||||
|
||||
使用 HTTP 基本身份验证的示例请求：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
服务器将使用以下 HTTP 状态代码进行响应：
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ---------------- | ------------------ |
|
||||
| `204 No Content` | 成功 |
|
||||
| `404 Not Found` | 找不到软件包或文件 |
|
||||
64
docs/document/usage/packages/go.md
Normal file
64
docs/document/usage/packages/go.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
date: "2023-05-10T00:00:00+00:00"
|
||||
slug: "go"
|
||||
sidebar_position: 45
|
||||
---
|
||||
|
||||
# Go 软件包注册表
|
||||
|
||||
为您的用户或组织发布 Go 软件包。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布 Go 软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。
|
||||
如果已经存在相同名称和版本的软件包，您无法发布软件包。您必须首先删除现有的软件包。
|
||||
该软件包必须遵循[文档中的结构](https://go.dev/ref/mod#zip-files)。
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/go/upload
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
要身份验证到软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证](development/api-usage.md#通过-api-认证)：
|
||||
|
||||
```shell
|
||||
curl --user your_username:your_password_or_token \
|
||||
--upload-file path/to/file.zip \
|
||||
https://gitea.example.com/api/packages/testuser/go/upload
|
||||
```
|
||||
|
||||
如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码进行身份验证。
|
||||
|
||||
服务器将使用以下 HTTP 状态代码进行响应。
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ----------------- | -------------------------- |
|
||||
| `201 Created` | 软件包已发布 |
|
||||
| `400 Bad Request` | 软件包无效 |
|
||||
| `409 Conflict` | 具有相同名称的软件包已存在 |
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要安装Go软件包，请指示Go使用软件包注册表作为代理：
|
||||
|
||||
```shell
|
||||
# 使用最新版本
|
||||
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}
|
||||
# 或者
|
||||
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest
|
||||
# 使用特定版本
|
||||
GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
|
||||
如果软件包的所有者是私有的，则需要[提供凭据](https://go.dev/ref/mod#private-module-proxy-auth)。
|
||||
|
||||
有关 `GOPROXY` 环境变量的更多信息以及如何防止数据泄漏的信息，请[参阅文档](https://go.dev/ref/mod#private-modules)。
|
||||
55
docs/document/usage/packages/helm.md
Normal file
55
docs/document/usage/packages/helm.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
date: "2022-04-14T00:00:00+00:00"
|
||||
slug: "helm"
|
||||
sidebar_position: 50
|
||||
---
|
||||
|
||||
# Helm Chart 注册表
|
||||
|
||||
为您的用户或组织发布 [Helm](https://helm.sh/) charts。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Helm Chart 注册表，可以使用诸如 `curl` 或 [`helm cm-push`](https://github.com/chartmuseum/helm-push/) 插件之类的简单HTTP客户端。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
通过运行以下命令来发布软件包：
|
||||
|
||||
```shell
|
||||
curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts
|
||||
```
|
||||
|
||||
或者使用 `helm cm-push` 插件：
|
||||
|
||||
```shell
|
||||
helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm
|
||||
helm cm-push ./{chart_file}.tgz {repo}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `username` | 您的Gitea用户名 |
|
||||
| `password` | 您的Gitea密码。如果您使用的是2FA或OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码进行身份验证。 |
|
||||
| `repo` | 仓库名称 |
|
||||
| `chart_file` | Helm Chart 归档文件 |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从注册表中安装Helm Chart，请执行以下命令：
|
||||
|
||||
```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}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ---------- | --------------------------- |
|
||||
| `username` | 您的Gitea用户名 |
|
||||
| `password` | 您的Gitea密码或个人访问令牌 |
|
||||
| `repo` | 存储库的名称 |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `name` | 本地名称 |
|
||||
| `chart` | Helm Chart的名称 |
|
||||
154
docs/document/usage/packages/maven.md
Normal file
154
docs/document/usage/packages/maven.md
Normal file
@@ -0,0 +1,154 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "maven"
|
||||
sidebar_position: 60
|
||||
---
|
||||
|
||||
# Maven 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Maven](https://maven.apache.org) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Maven 软件包注册表，您可以使用 [Maven](https://maven.apache.org/install.html) 或 [Gradle](https://gradle.org/install/)。
|
||||
以下示例使用 `Maven` 和 `Gradle Groovy`。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，首先需要将访问令牌添加到 [`settings.xml`](https://maven.apache.org/settings.html) 文件中：
|
||||
|
||||
```xml
|
||||
<settings>
|
||||
<servers>
|
||||
<server>
|
||||
<id>gitea</id>
|
||||
<configuration>
|
||||
<httpHeaders>
|
||||
<property>
|
||||
<name>Authorization</name>
|
||||
<value>token {access_token}</value>
|
||||
</property>
|
||||
</httpHeaders>
|
||||
</configuration>
|
||||
</server>
|
||||
</servers>
|
||||
</settings>
|
||||
```
|
||||
|
||||
然后在项目的 `pom.xml` 文件中添加以下部分：
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ------------------------------------------------------------------------------------- |
|
||||
| `access_token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证) |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
### Gradle variant
|
||||
|
||||
如果您计划在项目中添加来自 Gitea 实例的一些软件包，请将其添加到 repositories 部分中：
|
||||
|
||||
```groovy
|
||||
repositories {
|
||||
// other repositories
|
||||
maven { url "https://gitea.example.com/api/packages/{owner}/maven" }
|
||||
}
|
||||
```
|
||||
|
||||
在 Groovy gradle 中，您可以在发布部分中包含以下脚本：
|
||||
|
||||
```groovy
|
||||
publishing {
|
||||
// 其他发布设置
|
||||
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)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布软件包，只需运行以下命令：
|
||||
|
||||
```shell
|
||||
mvn deploy
|
||||
```
|
||||
|
||||
或者，如果您使用的是 Gradle，请使用 `gradle` 命令和 `publishAllPublicationsToGiteaRepository` 任务：
|
||||
|
||||
```groovy
|
||||
./gradlew publishAllPublicationsToGiteaRepository
|
||||
```
|
||||
|
||||
如果您想要将预构建的软件包发布到注册表中，可以使用 [`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
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
如果存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表中安装 Maven 软件包，请在项目的 `pom.xml` 文件中添加新的依赖项：
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.test.package</groupId>
|
||||
<artifactId>test_project</artifactId>
|
||||
<version>1.0.0</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
在 `Gradle Groovy` 中类似的操作如下：
|
||||
|
||||
```groovy
|
||||
implementation "com.test.package:test_project:1.0.0"
|
||||
```
|
||||
|
||||
然后运行：
|
||||
|
||||
```shell
|
||||
mvn install
|
||||
```
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
mvn install
|
||||
mvn deploy
|
||||
mvn dependency:get:
|
||||
```
|
||||
132
docs/document/usage/packages/npm.md
Normal file
132
docs/document/usage/packages/npm.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "npm"
|
||||
sidebar_position: 70
|
||||
---
|
||||
|
||||
# NPM Package Registry
|
||||
|
||||
为您的用户或组织发布 [npm](https://www.npmjs.com/) 包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 npm 包注册表，您需要安装 [Node.js](https://nodejs.org/en/download/) 以及与之配套的软件包管理器，例如 [Yarn](https://classic.yarnpkg.com/en/docs/install) 或 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) 本身。
|
||||
|
||||
该注册表支持[作用域](https://docs.npmjs.com/misc/scope/)和非作用域软件包。
|
||||
|
||||
以下示例使用具有作用域 `@test` 的 `npm` 工具。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，您需要配置一个新的软件包源。
|
||||
|
||||
```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}"
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | --------------------------------------------------------------------------------------- |
|
||||
| `scope` | 软件包的作用域 |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证)。 |
|
||||
|
||||
例如：
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
或者，不使用作用域：
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
## 发布软件包
|
||||
|
||||
在项目中运行以下命令发布软件包：
|
||||
|
||||
```shell
|
||||
npm publish
|
||||
```
|
||||
|
||||
如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 删除软件包
|
||||
|
||||
通过运行以下命令删除软件包：
|
||||
|
||||
```shell
|
||||
npm unpublish {package_name}[@{package_version}]
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | ---------- |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
|
||||
例如
|
||||
|
||||
```shell
|
||||
npm unpublish @test/test_package
|
||||
npm unpublish @test/test_package@1.0.0
|
||||
```
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表中安装软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
npm install {package_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ---------- |
|
||||
| `package_name` | 软件包名称 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
npm install @test/test_package
|
||||
```
|
||||
|
||||
## 给软件包打标签
|
||||
|
||||
该注册表支持[版本标签](https://docs.npmjs.com/adding-dist-tags-to-packages/)，可以通过 `npm dist-tag` 管理：
|
||||
|
||||
```shell
|
||||
npm dist-tag add {package_name}@{version} {tag}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ---------- |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `version` | 软件包版本 |
|
||||
| `tag` | 软件包标签 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
npm dist-tag add test_package@1.0.2 release
|
||||
```
|
||||
|
||||
标签名称不能是有效的版本。所有可解析为版本的标签名称都将被拒绝。
|
||||
|
||||
## 搜索软件包
|
||||
|
||||
该注册表支持[搜索](https://docs.npmjs.com/cli/v7/commands/npm-search/)，但不支持像 `author:gitea` 这样的特殊搜索限定符。
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
npm install
|
||||
npm ci
|
||||
npm publish
|
||||
npm unpublish
|
||||
npm dist-tag
|
||||
npm view
|
||||
npm search
|
||||
```
|
||||
105
docs/document/usage/packages/nuget.md
Normal file
105
docs/document/usage/packages/nuget.md
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "nuget"
|
||||
sidebar_position: 80
|
||||
---
|
||||
|
||||
# NuGet 软件包注册表
|
||||
|
||||
发布适用于您的用户或组织的 [NuGet](https://www.nuget.org/) 软件包。软件包注册表支持 V2 和 V3 API 协议，并且您还可以使用 [NuGet 符号软件包](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg)。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 NuGet 软件包注册表，您可以使用命令行界面工具，以及各种集成开发环境（IDE）中的 NuGet 功能，如 Visual Studio。有关 NuGet 客户端的更多信息，请参[阅官方文档](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools)。
|
||||
以下示例使用 `dotnet nuget` 工具。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，您需要配置一个新的NuGet源：
|
||||
|
||||
```shell
|
||||
dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `source_name` | 所需源名称 |
|
||||
| `username` | 您的Gitea用户名 |
|
||||
| `password` | 您的Gitea密码。如果您使用2FA或OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)代替密码。 |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json
|
||||
```
|
||||
|
||||
您可以在不提供凭据的情况下添加源，并在发布软件包时使用--api-key参数。在这种情况下，您需要提供[个人访问令牌](development/api-usage.md#通过-api-认证)。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
通过运行以下命令发布软件包：
|
||||
|
||||
```shell
|
||||
dotnet nuget push --source {source_name} {package_file}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ---------------------------- |
|
||||
| `source_name` | 所需源名称 |
|
||||
| `package_file` | 软件包 `.nupkg` 文件的路径。 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
dotnet nuget push --source gitea test_package.1.0.0.nupkg
|
||||
```
|
||||
|
||||
如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。
|
||||
|
||||
### 符号软件包
|
||||
|
||||
NuGet 软件包注册表支持构建用于符号服务器的符号软件包。客户端可以请求嵌入在符号软件包（`.snupkg`）中的 PDB 文件。
|
||||
为此，请将 NuGet 软件包注册表注册为符号源：
|
||||
|
||||
```
|
||||
https://gitea.example.com/api/packages/{owner}/nuget/symbols
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | -------------------- |
|
||||
| `owner` | 软件包注册表的所有者 |
|
||||
|
||||
例如：
|
||||
|
||||
```
|
||||
https://gitea.example.com/api/packages/testuser/nuget/symbols
|
||||
```
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表安装 NuGet 软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
dotnet add package --source {source_name} --version {package_version} {package_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | ------------ |
|
||||
| `source_name` | 所需源名称 |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本。 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
dotnet add package --source gitea --version 1.0.0 test_package
|
||||
```
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
dotnet add
|
||||
dotnet nuget push
|
||||
dotnet nuget delete
|
||||
```
|
||||
96
docs/document/usage/packages/overview.md
Normal file
96
docs/document/usage/packages/overview.md
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "overview"
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# 软件包注册表
|
||||
|
||||
从Gitea **1.17**版本开始，软件包注册表可以用作常见软件包管理器的公共或私有注册表。
|
||||
|
||||
## 支持的软件包管理器
|
||||
|
||||
目前支持以下软件包管理器：
|
||||
|
||||
| Name | Language | Package client |
|
||||
| ------------------------------------------------------------------- | ---------- | ------------------------- |
|
||||
| [Alpine](usage/packages/alpine.md) | - | `apk` |
|
||||
| [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) | - | 任何符合OCI规范的客户端 |
|
||||
| [CRAN](usage/packages/cran.md) | R | - |
|
||||
| [Debian](usage/packages/debian.md) | - | `apt` |
|
||||
| [Generic](usage/packages/generic.md) | - | 任何HTTP客户端 |
|
||||
| [Go](usage/packages/go.md) | Go | `go` |
|
||||
| [Helm](usage/packages/helm.md) | - | 任何HTTP客户端, `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/rubygems.md) | Swift | `swift` |
|
||||
| [Vagrant](usage/packages/vagrant.md) | - | `vagrant` |
|
||||
|
||||
**以下段落仅适用于未全局禁用软件包的情况！**
|
||||
|
||||
## 仓库 x 软件包
|
||||
|
||||
软件包始终属于所有者（用户或组织），而不是仓库。
|
||||
要将（已上传的）软件包链接到仓库，请打开该软件包的设置页面，并选择要将此软件包链接到的仓库。
|
||||
将链接到整个软件包，而不仅是单个版本。
|
||||
|
||||
链接软件包将导致在仓库的软件包列表中显示该软件包，并在软件包页面上显示到仓库的链接（以及到仓库工单的链接）。
|
||||
|
||||
## 访问限制
|
||||
|
||||
| 软件包所有者类型 | 用户 | 组织 |
|
||||
| ---------------- | ---------------------------------------- | ------------------------------------------ |
|
||||
| **读取** 访问 | 公开，如果用户也是公开的；否则仅限此用户 | 公开，如果组织是公开的，否则仅限组织成员 |
|
||||
| **写入** 访问 | 仅软件包所有者 | 具有组织中的管理员或写入访问权限的组织成员 |
|
||||
|
||||
注意：这些访问限制可能会[变化](https://github.com/go-gitea/gitea/issues/19270)，将通过专门的组织团队权限添加更细粒度的控制。
|
||||
|
||||
## 创建或上传软件包
|
||||
|
||||
根据软件包类型，使用相应的软件包管理器。请查看特定软件包管理器的子页面以获取说明。
|
||||
|
||||
## 查看软件包
|
||||
|
||||
您可以在仓库页面上查看仓库的软件包。
|
||||
|
||||
1. 转到仓库主页。
|
||||
2. 在导航栏中选择**软件包**
|
||||
|
||||
要查看有关软件包的更多详细信息，请选择软件包的名称。
|
||||
|
||||
## 下载软件包
|
||||
|
||||
要从仓库下载软件包：
|
||||
|
||||
1. 在导航栏中选择**软件包**
|
||||
2. 选择软件包的名称以查看详细信息。
|
||||
3. 在 **Assets** 部分，选择要下载的软件包文件的名称。
|
||||
|
||||
## 删除软件包
|
||||
|
||||
在将软件包发布到软件包注册表后，您无法编辑软件包。相反，您必须删除并重新创建它。
|
||||
|
||||
要从仓库中删除软件包：
|
||||
|
||||
1. 在导航栏中选择**软件包**
|
||||
2. 选择软件包的名称以查看详细信息。
|
||||
3. 单击**删除软件包**以永久删除软件包。
|
||||
|
||||
## 禁用软件包注册表
|
||||
|
||||
包注册表已自动启用。要在单个存储库中禁用它：
|
||||
|
||||
1. 在导航栏中选择**设置**。
|
||||
2. 禁用**启用仓库软件包注册表**.
|
||||
|
||||
禁用软件包注册表不会删除先前发布的软件包。
|
||||
71
docs/document/usage/packages/pub.md
Normal file
71
docs/document/usage/packages/pub.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
date: "2022-07-31T00:00:00+00:00"
|
||||
slug: "pub"
|
||||
sidebar_position: 90
|
||||
---
|
||||
|
||||
# Pub 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Pub](https://dart.dev/guides/packages) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用Pub软件包注册表，您需要使用 [dart](https://dart.dev/tools/dart-tool) 和/或 [flutter](https://docs.flutter.dev/reference/flutter-cli). 工具。
|
||||
|
||||
以下示例使用 `dart`。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表并提供凭据，请执行以下操作：
|
||||
|
||||
```shell
|
||||
dart pub token add https://gitea.example.com/api/packages/{owner}/pub
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
您需要提供您的[个人访问令牌](development/api-usage.md#通过-api-认证)。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布软件包，请编辑 `pubspec.yaml` 文件，并添加以下行：
|
||||
|
||||
```yaml
|
||||
publish_to: https://gitea.example.com/api/packages/{owner}/pub
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
|
||||
现在，您可以通过运行以下命令来发布软件包：
|
||||
|
||||
```shell
|
||||
dart pub publish
|
||||
```
|
||||
|
||||
如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表安装Pub软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
|
||||
例如：
|
||||
|
||||
```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
docs/document/usage/packages/pypi.md
Normal file
75
docs/document/usage/packages/pypi.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "pypi"
|
||||
sidebar_position: 100
|
||||
---
|
||||
|
||||
# PyPI 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [PyPI](https://pypi.org/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 PyPI 软件包注册表，您需要使用 [pip](https://pypi.org/project/pip/) 工具来消费和使用 [twine](https://pypi.org/project/twine/) 工具来发布软件包。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，您需要编辑本地的 `~/.pypirc` 文件。添加以下内容：
|
||||
|
||||
```ini
|
||||
[distutils]
|
||||
index-servers = gitea
|
||||
|
||||
[gitea]
|
||||
repository = https://gitea.example.com/api/packages/{owner}/pypi
|
||||
username = {username}
|
||||
password = {password}
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `username` | 您的 Gitea 用户名 |
|
||||
| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码 |
|
||||
|
||||
## 发布软件包
|
||||
|
||||
通过运行以下命令来发布软件包：
|
||||
|
||||
```shell
|
||||
python3 -m twine upload --repository gitea /path/to/files/*
|
||||
```
|
||||
|
||||
软件包文件的扩展名为 `.tar.gz` 和 `.whl`。
|
||||
|
||||
如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表安装 PyPI 软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ----------------------------- |
|
||||
| `username` | 您的 Gitea 用户名 |
|
||||
| `password` | 您的 Gitea 密码或个人访问令牌 |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package
|
||||
```
|
||||
|
||||
您可以使用 `--extra-index-url` 替代 `--index-url`，但这样会使您容易受到依赖混淆攻击，因为 `pip` 会先检查官方 PyPi 仓库中的软件包，然后再检查指定的自定义仓库。请阅读 `pip` 文档以获取更多信息。
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
pip install
|
||||
twine upload
|
||||
```
|
||||
108
docs/document/usage/packages/rpm.md
Normal file
108
docs/document/usage/packages/rpm.md
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
date: "2023-03-08T00:00:00+00:00"
|
||||
slug: "packages/rpm"
|
||||
sidebar_position: 105
|
||||
---
|
||||
|
||||
# RPM 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [RPM](https://rpm.org/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用RPM注册表，您需要使用像 `yum`, `dnf` 或 `zypper` 这样的软件包管理器来消费软件包。
|
||||
|
||||
以下示例使用 `dnf`。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册RPM注册表，请将 URL 添加到已知 `apt` 源列表中：
|
||||
|
||||
```shell
|
||||
dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm/{group}.repo
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ------- |--------------------------------------|
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `group` | 任何名称,例如 `centos/7`、`el-7`、`fc38` |
|
||||
|
||||
如果注册表是私有的，请在URL中提供凭据。您可以使用密码或[个人访问令牌](development/api-usage.md#通过-api-认证)：
|
||||
|
||||
```shell
|
||||
dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm/{group}.repo
|
||||
```
|
||||
|
||||
您还必须将凭据添加到 `/etc/yum.repos.d` 中的 `rpm.repo` 文件中的URL中。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
要发布RPM软件包（`*.rpm`），请执行带有软件包内容的 HTTP `PUT` 操作。
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/rpm/{group}/upload
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- |--------------|
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `group` | 软件包自定义分组名称 |
|
||||
|
||||
使用HTTP基本身份验证的示例请求：
|
||||
|
||||
```shell
|
||||
curl --user your_username:your_password_or_token \
|
||||
--upload-file path/to/file.rpm \
|
||||
https://gitea.example.com/api/packages/testuser/rpm/centos/el7/version/upload
|
||||
```
|
||||
|
||||
如果您使用 2FA 或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)替代密码。您无法将具有相同名称的文件两次发布到软件包中。您必须先删除现有的软件包版本。
|
||||
|
||||
服务器将以以下HTTP状态码响应。
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ----------------- | ------------------------------------------------ |
|
||||
| `201 Created` | 软件包已发布 |
|
||||
| `400 Bad Request` | 软件包无效 |
|
||||
| `409 Conflict` | 具有相同参数组合的软件包文件已经存在于该软件包中 |
|
||||
|
||||
## 删除软件包
|
||||
|
||||
要删除 RPM 软件包，请执行 HTTP `DELETE` 操作。如果没有文件剩余，这也将删除软件包版本。
|
||||
|
||||
```
|
||||
DELETE https://gitea.example.com/api/packages/{owner}/rpm/{group}/package/{package_name}/{package_version}/{architecture}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `group` | 软件包自定义分组 |
|
||||
| `package_name` | 软件包名称 |
|
||||
| `package_version` | 软件包版本 |
|
||||
| `architecture` | 软件包架构 |
|
||||
|
||||
使用HTTP基本身份验证的示例请求：
|
||||
|
||||
```shell
|
||||
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
|
||||
```
|
||||
|
||||
服务器将以以下HTTP状态码响应：
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ---------------- | ------------------ |
|
||||
| `204 No Content` | 成功 |
|
||||
| `404 Not Found` | 未找到软件包或文件 |
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从RPM注册表安装软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
# use latest version
|
||||
dnf install {package_name}
|
||||
# use specific version
|
||||
dnf install {package_name}-{package_version}.{architecture}
|
||||
```
|
||||
115
docs/document/usage/packages/rubygems.md
Normal file
115
docs/document/usage/packages/rubygems.md
Normal file
@@ -0,0 +1,115 @@
|
||||
---
|
||||
date: "2021-07-20T00:00:00+00:00"
|
||||
slug: "rubygems"
|
||||
sidebar_position: 110
|
||||
---
|
||||
|
||||
# RubyGems 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [RubyGems](https://guides.rubygems.org/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用RubyGems软件包注册表，您需要使用 [gem](https://guides.rubygems.org/command-reference/) 命令行工具来消费和发布软件包。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表，请编辑 `~/.gem/credentials` 文件并添加：
|
||||
|
||||
```ini
|
||||
---
|
||||
https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ------- | ------------------------------------------------------------------------------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `token` | 您的[个人访问令牌](development/api-usage.md#通过-api-认证) |
|
||||
|
||||
例如：
|
||||
|
||||
```
|
||||
---
|
||||
https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4
|
||||
```
|
||||
|
||||
## 发布软件包
|
||||
|
||||
通过运行以下命令来发布软件包：
|
||||
|
||||
```shell
|
||||
gem push --host {host} {package_file}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | ------------------------ |
|
||||
| `host` | 软件包注册表的URL |
|
||||
| `package_file` | 软件包 `.gem` 文件的路径 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem
|
||||
```
|
||||
|
||||
如果已经存在相同名称和版本的软件包，您将无法发布软件包。您必须先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表安装软件包，您可以使用 [Bundler](https://bundler.io) 或 `gem`。
|
||||
|
||||
### Bundler
|
||||
|
||||
在您的 `Gemfile` 中添加一个新的 `source` 块：
|
||||
|
||||
```
|
||||
source "https://gitea.example.com/api/packages/{owner}/rubygems" do
|
||||
gem "{package_name}"
|
||||
end
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
|
||||
例如：
|
||||
|
||||
```
|
||||
source "https://gitea.example.com/api/packages/testuser/rubygems" do
|
||||
gem "test_package"
|
||||
end
|
||||
```
|
||||
|
||||
之后运行以下命令：
|
||||
|
||||
```shell
|
||||
bundle install
|
||||
```
|
||||
|
||||
### gem
|
||||
|
||||
执行以下命令：
|
||||
|
||||
```shell
|
||||
gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name}
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | -------------- |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包名称 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package
|
||||
```
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
gem install
|
||||
bundle install
|
||||
gem push
|
||||
```
|
||||
72
docs/document/usage/packages/storage.md
Normal file
72
docs/document/usage/packages/storage.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
date: "2022-11-01T00:00:00+00:00"
|
||||
slug: "storage"
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# 存储
|
||||
|
||||
本文档描述了软件包注册表的存储方式以及如何管理存储。
|
||||
|
||||
## 去重
|
||||
|
||||
软件包注册表具有内置的去重功能，可以对上传的 Blob 进行去重处理。
|
||||
如果上传了两个相同的文件，只会在文件系统上保存一个 Blob。
|
||||
这样可以确保不会浪费空间用于重复的文件。
|
||||
|
||||
如果上传了两个具有相同文件的软件包，这两个软件包将显示相同的大小，但在文件系统上，它们只需要一半的大小。
|
||||
每当删除一个软件包时，只会删除对底层 Blob 的引用。
|
||||
此时，Blob 不会被删除，因此它们仍然占用文件系统上的空间。
|
||||
当上传新的软件包时，现有的 Blob 可能会再次被引用。
|
||||
|
||||
这些无引用的 Blob 会在一个清理任务中被删除。
|
||||
配置设置 `OLDER_THAN` 可以配置无引用的 Blob 在被删除之前保留的时间。
|
||||
|
||||
## 清理规则
|
||||
|
||||
软件包注册表可能会随着时间的推移而变得很大，如果不进行清理的话。
|
||||
建议删除不必要的软件包并设置清理规则以自动管理软件包注册表的使用情况。
|
||||
每个软件包所有者（用户或组织）都可以管理应用于其软件包的清理规则。
|
||||
|
||||
| 设置 | 描述 |
|
||||
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 启用 | 打开或关闭清理规则。 |
|
||||
| 类型 | 每个规则管理特定的软件包类型。 |
|
||||
| 将模式应用于完整的软件包名称 | 如果启用，则应用以下模式到完整的软件包名称（`package/version`），否则只使用版本号（`version`）。 |
|
||||
| 保留最近的版本数 | 对于每个软件包要始终保留的版本数量。 |
|
||||
| 保留与以下模式匹配的版本 | 确定要保留哪些版本的正则表达式模式。空模式表示不保留任何版本，而 `.+` 表示保留所有版本。即使未配置，容器注册表也始终保留 `latest` 版本。 |
|
||||
| 删除早于多少天的版本 | 仅删除早于所选天数的版本。 |
|
||||
| 删除与以下模式匹配的版本 | 确定要删除哪些版本的正则表达式模式。空模式或 `.+` 表示如果没有其他设置指定，则删除所有软件包。 |
|
||||
|
||||
每个清理规则都可以显示受影响的软件包的预览。
|
||||
这可以用来检查清理规则是否正确配置。
|
||||
|
||||
### 正则表达式示例
|
||||
|
||||
正则表达式模式会自动使用 `\A` 和 `\z` 锚点进行包围。
|
||||
不要在正则表达式模式中包含任何 `\A`、`\z`、`^` 或 `$` 标记，因为它们不是必要的。
|
||||
模式是不区分大小写的，与 Gitea 中的软件包注册表的行为相匹配。
|
||||
|
||||
| Pattern | Description |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `.*` | 匹配任何可能的版本。 |
|
||||
| `v.+` | 匹配以 `v` 开头的版本。 |
|
||||
| `release` | 仅匹配版本号为 `release`。 |
|
||||
| `release.*` | 匹配以 `release` 命名或以 `release` 开头的版本。 |
|
||||
| `.+-temp-.+` | 匹配包含 `-temp-` 的版本。 |
|
||||
| `v.+\|release` | 匹配以 `v` 开头的版本或版本号为 `release`。 |
|
||||
| `package/v.+\|other/release` | 匹配以 `v` 开头的 package 的版本或 `other` 的版本号为 `release`。需要启用*将模式应用于完整的软件包名称*设置。 |
|
||||
|
||||
### 清理规则的工作原理
|
||||
|
||||
清理规则是清理任务的一部分，定期运行。
|
||||
|
||||
清理规则：
|
||||
|
||||
1. 收集所有属于所有者注册表的特定软件包类型的软件包。
|
||||
2. 对于每个软件包，收集所有版本。
|
||||
3. 根据 *保留最近的版本数* 的值，从列表中排除版本。
|
||||
4. 根据 *保留与以下模式匹配的版本* 的值，从列表中排除任何版本。
|
||||
5. 根据 *删除早于多少天的版本* 的值，从列表中排除比这个值更近的版本。
|
||||
6. 根据 *删除与以下模式匹配的版本* 的值，从列表中排除任何不匹配的版本。
|
||||
7. 删除剩余的版本。
|
||||
81
docs/document/usage/packages/swift.md
Normal file
81
docs/document/usage/packages/swift.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
date: "2023-01-10T00:00:00+00:00"
|
||||
slug: "swift"
|
||||
sidebar_position: 115
|
||||
---
|
||||
|
||||
# Swift 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Swift](https://www.swift.org/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Swift 软件包注册表，您需要使用 [swift](https://www.swift.org/getting-started/) 消费软件包，并使用 HTTP 客户端（如 `curl`）发布软件包。
|
||||
|
||||
## 配置软件包注册表
|
||||
|
||||
要注册软件包注册表并提供凭据，请执行以下命令：
|
||||
|
||||
```shell
|
||||
swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password}
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `owner` | 软件包的所有者。 |
|
||||
| `username` | 您的 Gitea 用户名。 |
|
||||
| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)代替密码。 |
|
||||
|
||||
登录是可选的，只有在软件包注册表是私有的情况下才需要。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
首先，您需要打包软件包的内容：
|
||||
|
||||
```shell
|
||||
swift package archive-source
|
||||
```
|
||||
|
||||
要发布软件包，请执行一个带有软件包内容的 HTTP `PUT` 请求，将内容放在请求正文中。
|
||||
|
||||
```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}
|
||||
```
|
||||
|
||||
| 占位符 | 描述 |
|
||||
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `username` | 您的 Gitea 用户名。 |
|
||||
| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌](development/api-usage.md#通过-api-认证)代替密码。 |
|
||||
| `owner` | 软件包的所有者。 |
|
||||
| `scope` | 软件包的作用域。 |
|
||||
| `name` | 软件包的名称。 |
|
||||
| `version` | 软件包的版本。 |
|
||||
| `metadata` | （可选）软件包的元数据。以 JSON 编码的子集，格式参考 https://schema.org/SoftwareSourceCode |
|
||||
|
||||
如果已经存在相同名称和版本的软件包，则无法发布软件包。您必须首先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表安装 Swift 软件包，请将其添加到 `Package.swift` 文件的依赖项列表中：
|
||||
|
||||
```
|
||||
dependencies: [
|
||||
.package(id: "{scope}.{name}", from:"{version}")
|
||||
]
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| --------- | -------------- |
|
||||
| `scope` | 软件包的作用域 |
|
||||
| `name` | 软件包的名称 |
|
||||
| `version` | 软件包的版本 |
|
||||
|
||||
之后，执行以下命令来安装它：
|
||||
|
||||
```shell
|
||||
swift package resolve
|
||||
```
|
||||
66
docs/document/usage/packages/vagrant.md
Normal file
66
docs/document/usage/packages/vagrant.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
date: "2022-08-23T00:00:00+00:00"
|
||||
slug: "vagrant"
|
||||
sidebar_position: 120
|
||||
---
|
||||
|
||||
# Vagrant 软件包注册表
|
||||
|
||||
为您的用户或组织发布 [Vagrant](https://www.vagrantup.com/) 软件包。
|
||||
|
||||
## 要求
|
||||
|
||||
要使用 Vagrant 软件包注册表，您需要安装 [Vagrant](https://www.vagrantup.com/downloads) 并使用类似于 `curl` 的工具进行 HTTP 请求。
|
||||
|
||||
## 发布软件包
|
||||
|
||||
通过执行 HTTP PUT 请求将 Vagrant box 发布到注册表：
|
||||
|
||||
```
|
||||
PUT https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| ----------------- | ------------------------------------------------------------------ |
|
||||
| `owner` | 软件包的所有者 |
|
||||
| `package_name` | 软件包的名称 |
|
||||
| `package_version` | 软件包的版本，兼容 semver 格式 |
|
||||
| `provider` | [支持的提供程序名称](https://www.vagrantup.com/docs/providers)之一 |
|
||||
|
||||
上传 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
|
||||
```
|
||||
|
||||
如果已经存在相同名称、版本和提供程序的软件包，则无法发布软件包。您必须首先删除现有的软件包。
|
||||
|
||||
## 安装软件包
|
||||
|
||||
要从软件包注册表安装软件包，请执行以下命令：
|
||||
|
||||
```shell
|
||||
vagrant box add "https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}"
|
||||
```
|
||||
|
||||
| 参数 | 描述 |
|
||||
| -------------- | --------------- |
|
||||
| `owner` | 软件包的所有者. |
|
||||
| `package_name` | 软件包的名称 |
|
||||
|
||||
例如：
|
||||
|
||||
```shell
|
||||
vagrant box add "https://gitea.example.com/api/packages/testuser/vagrant/test_system"
|
||||
```
|
||||
|
||||
这将安装软件包的最新版本。要添加特定版本，请使用` --box-version` 参数。
|
||||
如果注册表是私有的，您可以将您的[个人访问令牌](development/api-usage.md#通过-api-认证)传递给 `VAGRANT_CLOUD_TOKEN` 环境变量。
|
||||
|
||||
## 支持的命令
|
||||
|
||||
```
|
||||
vagrant box add
|
||||
```
|
||||
77
docs/document/usage/permissions.md
Normal file
77
docs/document/usage/permissions.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "permissions"
|
||||
sidebar_position: 14
|
||||
aliases:
|
||||
- /zh-cn/permissions
|
||||
---
|
||||
|
||||
# 权限
|
||||
|
||||
Gitea 支持对仓库进行权限管理，这样您就可以为不同的人员提供不同的访问权限。首先，我们需要了解 `单元（Unit）`。
|
||||
|
||||
## 单元（Unit）
|
||||
|
||||
在 Gitea 中，我们将仓库的子模块称为 `单元（Unit）`。现在我们有以下几个单元。
|
||||
|
||||
| 名称 | 描述 | 权限 |
|
||||
| -------------- | ---------------------------------- | --------- |
|
||||
| 代码 | 访问源代码、文件、提交和分支。 | 读取 写入 |
|
||||
| 工单 | 组织缺陷报告、任务和里程碑。 | 读取 写入 |
|
||||
| 合并请求 | 启用合并请求和代码审核。 | 读取 写入 |
|
||||
| 发布 | 跟踪项目版本和下载。 | 读取 写入 |
|
||||
| 百科 | 与协作者编写和共享文档。 | 读取 写入 |
|
||||
| 外部百科 | 链接到外部维基。 | 读取 |
|
||||
| 外部工单跟踪器 | 链接到外部工单跟踪器。 | 读取 |
|
||||
| 项目 | 模板仓库的 URL。 | 读取 写入 |
|
||||
| 包 | 链接到仓库 | 读取 写入 |
|
||||
| Actions | 审查 Actions 日志或重启/取消工作流 | 读取 写入 |
|
||||
| 设置 | 管理仓库。 | 管理员 |
|
||||
|
||||
通过不同的权限，用户可以在这些单元上执行不同的操作。
|
||||
|
||||
| 名称 | 读取 | 写入 | 管理员 |
|
||||
| -------------- | -------------------------------- | ------------------------------ | -------- |
|
||||
| 代码 | 查看代码树、文件、提交、分支等。 | 推送代码。 | - |
|
||||
| 工单 | 查看工单并创建新工单。 | 添加标签、分配、关闭工单。 | - |
|
||||
| 合并请求 | 查看合并请求并创建新合并请求。 | 添加标签、分配、关闭合并请求。 | - |
|
||||
| 发布 | 查看发布和下载文件。 | 创建/编辑发布。 | - |
|
||||
| 百科 | 查看百科页面。克隆百科仓库。 | 创建/编辑百科页面，推送更改。 | - |
|
||||
| 外部百科 | 链接到外部百科。 | - | - |
|
||||
| 外部工单跟踪器 | 链接到外部工单跟踪器。 | - | - |
|
||||
| 项目 | 查看面板。 | 在面板之间移动工单。 | - |
|
||||
| 包 | 查看包 | 上传/删除包 | - |
|
||||
| Actions | 查看 Actions 日志 | 同意 / 取消 / 重启 | - |
|
||||
| 设置 | - | - | 管理仓库 |
|
||||
|
||||
个人仓库和组织仓库之间的权限存在一些差异。
|
||||
|
||||
## 个人仓库
|
||||
|
||||
对于个人仓库，创建者是仓库的唯一所有者，对于该仓库的任何更改或删除没有限制。
|
||||
仓库所有者可以添加协作者来帮助维护仓库。协作者可以拥有 `读取（Read）`、`写入（Write）` 和 `管理员（Admin）` 权限。
|
||||
|
||||
访问私有仓库的体验与访问匿名公共仓库类似。您可以访问仓库中的所有可用内容，包括克隆代码、创建工单、回复工单评论、提交拉取请求等。如果你有 "写"权限，只要分支保护规则允许，你就可以向仓库的特定分支推送代码。此外，你还可以修改百科页面。有了 "管理"权限，你就可以修改仓库的设置。
|
||||
|
||||
但如果你不是该仓库的所有者，就不能删除或转移该仓库。
|
||||
|
||||
## 组织仓库
|
||||
|
||||
对于个人仓库，所有者是创建它的用户。而对于组织仓库，所有者是该组织中的所有者团队成员。对该组织仓库的所有权限都取决于团队权限设置。
|
||||
|
||||
### 所有者团队
|
||||
|
||||
创建组织时将自动创建所有者团队，创建者将成为所有者团队的第一名成员。所有者团队不可删除，且至少有一名成员。
|
||||
|
||||
### 管理员团队
|
||||
|
||||
创建团队时，有两种类型的团队。一种是管理员团队，另一种是普通团队。可以创建一个管理员团队来管理某些版本库，其成员可以对这些版本库做任何事情。只有所有者或管理员团队的成员才能创建新团队。
|
||||
|
||||
### 普通团队
|
||||
|
||||
组织中的普通团队具有可以根据`单元(Unit)`进行权限设置。它可以有成员和存储库范围。
|
||||
|
||||
- 一个团队可以访问所属组织的所有仓库或特殊仓库。
|
||||
- 也可以设置该团队是否有创建新仓库的权限。
|
||||
|
||||
可以通过创建 "普通团队"，并通过权限控制对其行为进行限制。一名成员可以加入多个团队。
|
||||
15
docs/document/usage/profile-readme.md
Normal file
15
docs/document/usage/profile-readme.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "profile-readme"
|
||||
sidebar_position: 12
|
||||
---
|
||||
|
||||
# 个人资料 README
|
||||
|
||||
要在您的 Gitea 个人资料页面显示一个 Markdown 文件，只需创建一个名为 `.profile` 的仓库，并编辑其中的 `README.md` 文件。Gitea 将自动获取该文件并在您的仓库上方显示。
|
||||
|
||||
注意：您可以将此仓库设为私有。这样可以隐藏您的源文件，使其对公众不可见，并允许您将某些文件设为私有。但是，README.md 文件将是您个人资料上唯一存在的文件。如果您希望完全私有化 .profile 仓库，则需删除或重命名 README.md 文件。
|
||||
|
||||
用户示例 `.profile/README.md`:
|
||||
|
||||
|
||||
46
docs/document/usage/protected-tags.md
Normal file
46
docs/document/usage/protected-tags.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "protected-tags"
|
||||
sidebar_position: 45
|
||||
aliases:
|
||||
- /zh-cn/protected-tags
|
||||
---
|
||||
|
||||
# 受保护的标签
|
||||
|
||||
受保护的标签允许控制谁有权限创建或更新 Git 标签。每个规则可以匹配单个标签名称，或者使用适当的模式来同时控制多个标签。
|
||||
|
||||
## 设置受保护的标签
|
||||
|
||||
要保护一个标签，你需要按照以下步骤进行操作：
|
||||
|
||||
1. 进入仓库的**设置** > **标签**页面。
|
||||
2. 输入一个用于匹配名称的模式。你可以使用单个名称、[glob 模式](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正则表达式。
|
||||
3. 选择允许的用户和/或团队。如果将这些字段留空，则不允许任何人创建或修改此标签。
|
||||
4. 选择**保存**以保存配置。
|
||||
|
||||
## 模式受保护的标签
|
||||
|
||||
该模式使用 [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正则表达式来匹配标签名称。对于正则表达式，你需要将模式括在斜杠中。
|
||||
|
||||
示例：
|
||||
|
||||
| 类型 | 模式受保护的标签 | 可能匹配的标签 |
|
||||
| ----- | ------------------------ | --------------------------------------- |
|
||||
| Glob | `v*` | `v`，`v-1`，`version2` |
|
||||
| Glob | `v[0-9]` | `v0`，`v1` 到 `v9` |
|
||||
| Glob | `*-release` | `2.1-release`，`final-release` |
|
||||
| Glob | `gitea` | 仅限 `gitea` |
|
||||
| Glob | `*gitea*` | `gitea`，`2.1-gitea`，`1_gitea-release` |
|
||||
| Glob | `{v,rel}-*` | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` |
|
||||
| Glob | `*` | 匹配所有可能的标签名称 |
|
||||
| Regex | `/\Av/` | `v`，`v-1`，`version2` |
|
||||
| Regex | `/\Av[0-9]\z/` | `v0`，`v1` 到 `v9` |
|
||||
| Regex | `/\Av\d+\.\d+\.\d+\z/` | `v1.0.17`，`v2.1.0` |
|
||||
| Regex | `/\Av\d+(\.\d+){0,2}\z/` | `v1`，`v2.1`，`v1.2.34` |
|
||||
| Regex | `/-release\z/` | `2.1-release`，`final-release` |
|
||||
| Regex | `/gitea/` | `gitea`，`2.1-gitea`，`1_gitea-release` |
|
||||
| Regex | `/\Agitea\z/` | 仅限 `gitea` |
|
||||
| Regex | `/^gitea$/` | 仅限 `gitea` |
|
||||
| Regex | `/\A(v\|rel)-/` | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` |
|
||||
| Regex | `/.+/` | 匹配所有可能的标签名称 |
|
||||
60
docs/document/usage/pull-request.md
Normal file
60
docs/document/usage/pull-request.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
date: "2018-06-01T19:00:00+02:00"
|
||||
slug: "pull-request"
|
||||
sidebar_position: 13
|
||||
aliases:
|
||||
- /zh-cn/pull-request
|
||||
---
|
||||
|
||||
# 合并请求
|
||||
|
||||
合并请求(PR)是一种提出对仓库进行更改的方式。
|
||||
它是一种将一个分支合并到另一个分支的请求，附带有对所做更改的描述。
|
||||
合并请求通常用作贡献者对仓库贡献代码的方式，仓库的维护者可以通过对合并请求进行审查来决定是否接受这些更改。
|
||||
|
||||
## 创建合并请求
|
||||
|
||||
要创建合并请求，您需要遵循以下步骤：
|
||||
|
||||
1. **Fork 仓库** - 如果您没有直接对仓库进行更改的权限，您需要将仓库 fork 到您自己的账户中。
|
||||
这将创建一个您可以对其进行更改的仓库副本。
|
||||
|
||||
2. **创建分支（可选）** - 在 fork 的仓库中创建一个新分支，该分支包含您要提出的更改。
|
||||
给分支取一个描述性的名称，以指示更改的内容。
|
||||
|
||||
3. **进行更改** - 进行您想要的更改，提交并将其推送到 fork 的仓库中。
|
||||
|
||||
4. **创建合并请求** - 转到原始仓库并转到“合并请求”选项卡。单击“新建合并请求”按钮，并将您的新分支选择为源分支。
|
||||
为您的合并请求输入描述性标题和描述，然后单击“创建合并请求”。
|
||||
|
||||
## 评审合并请求
|
||||
|
||||
创建合并请求后，将触发评审流程。仓库的维护者将收到合并请求的通知，并可以审查所做的更改。
|
||||
他们可以留下评论、请求更改或批准更改。
|
||||
|
||||
如果维护者请求更改，您需要在分支中进行这些更改，并将更改推送到 fork 的仓库中。
|
||||
合并请求将自动使用新更改进行更新。
|
||||
|
||||
如果维护者批准更改，他们可以将合并请求合并到仓库中。
|
||||
|
||||
## 关闭合并请求
|
||||
|
||||
如果您不接受该合并请求，您可以关闭它。
|
||||
要关闭合并请求，请转到打开的合并请求并单击“关闭合并请求”按钮。这将关闭合并请求并且不会将其合并。
|
||||
|
||||
## 使用“Work In Progress”标记
|
||||
|
||||
在合并请求中使用“Work In Progress”标记可以防止合并请求被意外合并。
|
||||
要将合并请求标记为“Work In Progress”，您必须在其标题中添加前缀`WIP:`或`[WIP]`（不区分大小写）。
|
||||
标记前缀可以在您的`app.ini`文件中进行配置：
|
||||
|
||||
```
|
||||
[repository.pull-request]
|
||||
WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
|
||||
```
|
||||
|
||||
列表的第一个值将用于 helpers 程序。
|
||||
|
||||
## 合并请求模板
|
||||
|
||||
有关合并请求模板的更多信息请您移步 : [工单与合并请求模板](usage/issue-pull-request-templates.md)
|
||||
61
docs/document/usage/push.md
Normal file
61
docs/document/usage/push.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "push"
|
||||
sidebar_position: 15
|
||||
aliases:
|
||||
- /zh-cn/push-to-create
|
||||
- /zh-cn/push-options
|
||||
---
|
||||
|
||||
# 推送
|
||||
|
||||
在将提交推送到 Gitea 服务器时，还有一些额外的功能。
|
||||
|
||||
## 通过推送打开 PR
|
||||
|
||||
当您第一次将提交推送到非默认分支时，您将收到一个链接，您可以单击该链接访问分支与主分支的比较页面。
|
||||
从那里，您可以轻松创建一个拉取请求，即使您想要将其目标指向另一个分支。
|
||||
|
||||
|
||||
|
||||
## 推送选项
|
||||
|
||||
在 Gitea `1.13` 版本中，添加了对一些 [推送选项](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) 的支持。
|
||||
|
||||
### 支持的选项
|
||||
|
||||
- `repo.private` (true|false) - 更改仓库的可见性。
|
||||
|
||||
这在与 push-to-create 结合使用时特别有用。
|
||||
|
||||
- `repo.template` (true|false) - 更改仓库是否为模板。
|
||||
|
||||
将仓库的可见性更改为公开的示例：
|
||||
|
||||
```shell
|
||||
git push -o repo.private=false -u origin main
|
||||
```
|
||||
|
||||
## 推送创建
|
||||
|
||||
推送创建是一项功能，允许您将提交推送到在 Gitea 中尚不存在的仓库。这对于自动化和允许用户创建仓库而无需通过 Web 界面非常有用。此功能默认处于禁用状态。
|
||||
|
||||
### 启用推送创建
|
||||
|
||||
在 `app.ini` 文件中，将 `ENABLE_PUSH_CREATE_USER` 设置为 `true`，如果您希望允许用户在自己的用户帐户和所属的组织中创建仓库，将 `ENABLE_PUSH_CREATE_ORG` 设置为 `true`。重新启动 Gitea 以使更改生效。您可以在 [配置速查表](../administration/config-cheat-sheet.md#仓库) 中了解有关这两个选项的更多信息。
|
||||
|
||||
### 使用推送创建
|
||||
|
||||
假设您在当前目录中有一个 git 仓库，您可以通过运行以下命令将提交推送到在 Gitea 中尚不存在的仓库：
|
||||
|
||||
```shell
|
||||
# 添加要推送到的远程仓库
|
||||
git remote add origin git@{domain}:{username}/{尚不存在的仓库名称}.git
|
||||
|
||||
# 推送到远程仓库
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
这假设您使用的是 SSH 远程，但您也可以使用 HTTPS 远程。
|
||||
|
||||
推送创建将默认使用 `app.ini` 中定义的可见性 `DEFAULT_PUSH_CREATE_PRIVATE`。
|
||||
98
docs/document/usage/repo-mirror.md
Normal file
98
docs/document/usage/repo-mirror.md
Normal file
@@ -0,0 +1,98 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "repo-mirror"
|
||||
sidebar_position: 45
|
||||
aliases:
|
||||
- /zh-cn/repo-mirror
|
||||
---
|
||||
|
||||
# 仓库镜像
|
||||
|
||||
仓库镜像允许将仓库与外部源之间进行镜像。您可以使用它在仓库之间镜像分支、标签和提交。
|
||||
|
||||
## 使用场景
|
||||
|
||||
以下是一些仓库镜像的可能使用场景：
|
||||
|
||||
- 您迁移到了 Gitea，但仍需要在其他源中保留您的项目。在这种情况下，您可以简单地设置它以进行镜像到 Gitea（拉取），这样您的 Gitea 实例中就可以获取到所有必要的提交历史、标签和分支。
|
||||
- 您在其他源中有一些旧项目，您不再主动使用，但出于归档目的不想删除。在这种情况下，您可以创建一个推送镜像，以便您的活跃的 Gitea 仓库可以将其更改推送到旧位置。
|
||||
|
||||
## 从远程仓库拉取
|
||||
|
||||
对于现有的远程仓库，您可以按照以下步骤设置拉取镜像：
|
||||
|
||||
1. 在右上角的“创建...”菜单中选择“迁移外部仓库”。
|
||||
2. 选择远程仓库服务。
|
||||
3. 输入仓库的 URL。
|
||||
4. 如果仓库需要身份验证，请填写您的身份验证信息。
|
||||
5. 选中“该仓库将是一个镜像”复选框。
|
||||
6. 选择“迁移仓库”以保存配置。
|
||||
|
||||
现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。
|
||||
|
||||
:::warning
|
||||
:exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation:
|
||||
:::
|
||||
|
||||
## 推送到远程仓库
|
||||
|
||||
对于现有的仓库，您可以按照以下步骤设置推送镜像：
|
||||
|
||||
1. 在仓库中，转到**设置** > **仓库**，然后进入**镜像设置**部分。
|
||||
2. 输入一个仓库的 URL。
|
||||
3. 如果仓库需要身份验证，请展开**授权**部分并填写您的身份验证信息。请注意，所请求的**密码**也可以是您的访问令牌。
|
||||
4. 选择**添加推送镜像**以保存配置。
|
||||
|
||||
该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。
|
||||
|
||||
:::warning
|
||||
:exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation:
|
||||
:::
|
||||
|
||||
### 从 Gitea 向 GitHub 设置推送镜像
|
||||
|
||||
要从 Gitea 设置镜像到 GitHub，您需要按照以下步骤进行操作：
|
||||
|
||||
1. 创建一个具有选中 _public_repo_ 选项的 [GitHub 个人访问令牌](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)。
|
||||
2. 在 GitHub 上创建一个同名的仓库。与 Gitea 不同，GitHub 不支持通过推送到远程来创建仓库。如果您的现有远程仓库与您的 Gitea 仓库具有相同的提交历史，您也可以使用现有的远程仓库。
|
||||
3. 在您的 Gitea 仓库设置中，填写**Git 远程仓库 URL**：`https://github.com/<your_github_group>/<your_github_project>.git`。
|
||||
4. 使用您的 GitHub 用户名填写**授权**字段，并将个人访问令牌作为**密码**。
|
||||
5. （可选，适用于 Gitea 1.18+）选择`当推送新提交时同步`，这样一旦有更改，镜像将会及时更新。如果您愿意，您还可以禁用定期同步。
|
||||
6. 选择**添加推送镜像**以保存配置。
|
||||
|
||||
仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
|
||||
|
||||
### 从 Gitea 向 GitLab 设置推送镜像
|
||||
|
||||
要从 Gitea 设置镜像到 GitLab，您需要按照以下步骤进行操作：
|
||||
|
||||
1. 创建具有 _write_repository_ 作用域的 [GitLab 个人访问令牌](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)。
|
||||
2. 填写**Git 远程仓库 URL**：`https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`。
|
||||
3. 在**授权**字段中填写 `oauth2` 作为**用户名**，并将您的 GitLab 个人访问令牌作为**密码**。
|
||||
4. 选择**添加推送镜像**以保存配置。
|
||||
|
||||
仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
|
||||
|
||||
### 从 Gitea 向 Bitbucket 设置推送镜像
|
||||
|
||||
要从 Gitea 设置镜像到 Bitbucket，您需要按照以下步骤进行操作：
|
||||
|
||||
1. 创建一个具有选中 _Repository Write_ 选项的 [Bitbucket 应用密码](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/)。
|
||||
2. 填写**Git 远程仓库 URL**：`https://bitbucket.org/<your_bitbucket_group_or_name>/<your_bitbucket_project>.git`。
|
||||
3. 使用您的 Bitbucket 用户名填写**授权**字段，并将应用密码作为**密码**。
|
||||
4. 选择**添加推送镜像**以保存配置。
|
||||
|
||||
仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
|
||||
|
||||
### 镜像现有的 ssh 仓库
|
||||
|
||||
当前，Gitea 不支持从 ssh 仓库进行镜像。如果您想要镜像一个 ssh 仓库，您需要将其转换为 http 仓库。您可以使用以下命令将现有的 ssh 仓库转换为 http 仓库：
|
||||
|
||||
1. 确保运行 gitea 的用户有权限访问您试图从 shell 镜像到的 git 仓库。
|
||||
2. 在 Web 界面的版本库设置 > git 钩子中为镜像添加一个接收后钩子。
|
||||
|
||||
```
|
||||
#!/usr/bin/env bash
|
||||
git push --mirror --quiet git@github.com:username/repository.git &>/dev/null &
|
||||
echo "GitHub mirror initiated .."
|
||||
```
|
||||
76
docs/document/usage/template-repositories.md
Normal file
76
docs/document/usage/template-repositories.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "template-repositories"
|
||||
sidebar_position: 14
|
||||
aliases:
|
||||
- /zh-cn/template-repositories
|
||||
---
|
||||
|
||||
# 模板仓库
|
||||
|
||||
Gitea `1.11.0` 及以上版本引入了模板仓库，并且其中一个实现的功能是自动展开模板文件中的特定变量。
|
||||
|
||||
要告诉 Gitea 哪些文件需要展开，您必须在模板仓库的 `.gitea` 目录中包含一个 `template` 文件。
|
||||
|
||||
Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。它与传统的 `.gitignore` 语法非常相似，但可能存在细微的差异。
|
||||
|
||||
## `.gitea/template` 文件示例
|
||||
|
||||
所有路径都是相对于仓库的根目录
|
||||
|
||||
```gitignore
|
||||
# 仓库中的所有 .go 文件
|
||||
**.go
|
||||
|
||||
# text 目录中的所有文本文件
|
||||
text/*.txt
|
||||
|
||||
# 特定文件
|
||||
a/b/c/d.json
|
||||
|
||||
# 匹配批处理文件的大小写变体
|
||||
**.[bB][aA][tT]
|
||||
```
|
||||
|
||||
**注意：** 当从模板生成仓库时，`.gitea` 目录中的 `template` 文件将被删除。
|
||||
|
||||
## 参数展开
|
||||
|
||||
在与上述通配符匹配的任何文件中，将会扩展某些变量。
|
||||
|
||||
文件名和路径的匹配也可以被扩展，并且会经过谨慎的清理处理，以支持跨平台的文件系统。
|
||||
|
||||
所有变量都必须采用`$VAR`或`${VAR}`的形式。要转义扩展，使用双重`$$`，例如`$$VAR`或`$${VAR}`。
|
||||
|
||||
| 变量 | 扩展为 | 可转换 |
|
||||
| -------------------- | ----------------------------- | ------ |
|
||||
| REPO_NAME | 生成的仓库名称 | ✓ |
|
||||
| TEMPLATE_NAME | 模板仓库名称 | ✓ |
|
||||
| REPO_DESCRIPTION | 生成的仓库描述 | ✘ |
|
||||
| TEMPLATE_DESCRIPTION | 模板仓库描述 | ✘ |
|
||||
| REPO_OWNER | 生成的仓库所有者 | ✓ |
|
||||
| TEMPLATE_OWNER | 模板仓库所有者 | ✓ |
|
||||
| REPO_LINK | 生成的仓库链接 | ✘ |
|
||||
| TEMPLATE_LINK | 模板仓库链接 | ✘ |
|
||||
| REPO_HTTPS_URL | 生成的仓库的 HTTP(S) 克隆链接 | ✘ |
|
||||
| TEMPLATE_HTTPS_URL | 模板仓库的 HTTP(S) 克隆链接 | ✘ |
|
||||
| REPO_SSH_URL | 生成的仓库的 SSH 克隆链接 | ✘ |
|
||||
| TEMPLATE_SSH_URL | 模板仓库的 SSH 克隆链接 | ✘ |
|
||||
|
||||
## 转换器 :robot:
|
||||
|
||||
Gitea `1.12.0` 添加了一些转换器以应用于上述适用的变量。
|
||||
|
||||
例如，要以 `PASCAL`-case 获取 `REPO_NAME`，你的模板应使用 `${REPO_NAME_PASCAL}`
|
||||
|
||||
将 `go-sdk` 传递给可用的转换器的效果如下...
|
||||
|
||||
| 转换器 | 效果 |
|
||||
| ------ | ------ |
|
||||
| SNAKE | go_sdk |
|
||||
| KEBAB | go-sdk |
|
||||
| CAMEL | goSdk |
|
||||
| PASCAL | GoSdk |
|
||||
| LOWER | go-sdk |
|
||||
| UPPER | GO-SDK |
|
||||
| TITLE | Go-Sdk |
|
||||
185
docs/document/usage/webhooks.md
Normal file
185
docs/document/usage/webhooks.md
Normal file
@@ -0,0 +1,185 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
slug: "webhooks"
|
||||
sidebar_position: 30
|
||||
aliases:
|
||||
- /zh-cn/webhooks
|
||||
---
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
|
||||
所有事件推送都是 POST 请求。目前支持：
|
||||
|
||||
- Gitea (也可以是 GET 请求)
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk（钉钉）
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork（企业微信）
|
||||
- Packagist
|
||||
|
||||
### 事件信息
|
||||
|
||||
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
|
||||
|
||||
以下是 Gitea 将发送给 payload URL 的事件信息示例：
|
||||
|
||||
```http
|
||||
X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
|
||||
X-GitHub-Event: push
|
||||
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
|
||||
X-Gogs-Event: push
|
||||
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
|
||||
X-Gitea-Event: push
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
|
||||
"ref": "refs/heads/develop",
|
||||
"before": "28e1879d029cb852e4844d9c718537df08844e03",
|
||||
"after": "bffeb74224043ba2feb48d137756c8a9331c449a",
|
||||
"compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
|
||||
"commits": [
|
||||
{
|
||||
"id": "bffeb74224043ba2feb48d137756c8a9331c449a",
|
||||
"message": "Webhooks Yay!",
|
||||
"url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
|
||||
"author": {
|
||||
"name": "Gitea",
|
||||
"email": "someone@gitea.io",
|
||||
"username": "gitea"
|
||||
},
|
||||
"committer": {
|
||||
"name": "Gitea",
|
||||
"email": "someone@gitea.io",
|
||||
"username": "gitea"
|
||||
},
|
||||
"timestamp": "2017-03-13T13:52:11-04:00"
|
||||
}
|
||||
],
|
||||
"repository": {
|
||||
"id": 140,
|
||||
"owner": {
|
||||
"id": 1,
|
||||
"login": "gitea",
|
||||
"full_name": "Gitea",
|
||||
"email": "someone@gitea.io",
|
||||
"avatar_url": "https://localhost:3000/avatars/1",
|
||||
"username": "gitea"
|
||||
},
|
||||
"name": "webhooks",
|
||||
"full_name": "gitea/webhooks",
|
||||
"description": "",
|
||||
"private": false,
|
||||
"fork": false,
|
||||
"html_url": "http://localhost:3000/gitea/webhooks",
|
||||
"ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
|
||||
"clone_url": "http://localhost:3000/gitea/webhooks.git",
|
||||
"website": "",
|
||||
"stars_count": 0,
|
||||
"forks_count": 1,
|
||||
"watchers_count": 1,
|
||||
"open_issues_count": 7,
|
||||
"default_branch": "master",
|
||||
"created_at": "2017-02-26T04:29:06-05:00",
|
||||
"updated_at": "2017-03-13T13:51:58-04:00"
|
||||
},
|
||||
"pusher": {
|
||||
"id": 1,
|
||||
"login": "gitea",
|
||||
"full_name": "Gitea",
|
||||
"email": "someone@gitea.io",
|
||||
"avatar_url": "https://localhost:3000/avatars/1",
|
||||
"username": "gitea"
|
||||
},
|
||||
"sender": {
|
||||
"id": 1,
|
||||
"login": "gitea",
|
||||
"full_name": "Gitea",
|
||||
"email": "someone@gitea.io",
|
||||
"avatar_url": "https://localhost:3000/avatars/1",
|
||||
"username": "gitea"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
|
||||
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
|
||||
|
||||
- 目标 URL：http://mydomain.com/webhook.php
|
||||
- HTTP 方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 触发条件：推送事件
|
||||
- 激活：勾选
|
||||
|
||||
现在在你的服务器上创建 php 文件 webhook.php。
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
$secret_key = '123';
|
||||
|
||||
// check for POST request
|
||||
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
|
||||
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
|
||||
exit();
|
||||
}
|
||||
|
||||
// get content type
|
||||
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
|
||||
|
||||
if ($content_type != 'application/json') {
|
||||
error_log('FAILED - not application/json - '. $content_type);
|
||||
exit();
|
||||
}
|
||||
|
||||
// get payload
|
||||
$payload = trim(file_get_contents("php://input"));
|
||||
|
||||
if (empty($payload)) {
|
||||
error_log('FAILED - no payload');
|
||||
exit();
|
||||
}
|
||||
|
||||
// get header signature
|
||||
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
||||
|
||||
if (empty($header_signature)) {
|
||||
error_log('FAILED - header signature missing');
|
||||
exit();
|
||||
}
|
||||
|
||||
// calculate payload signature
|
||||
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
|
||||
|
||||
// check payload signature against header signature
|
||||
if ($header_signature !== $payload_signature) {
|
||||
error_log('FAILED - payload signature');
|
||||
exit();
|
||||
}
|
||||
|
||||
// convert json to array
|
||||
$decoded = json_decode($payload, true);
|
||||
|
||||
// check for json decode errors
|
||||
if (json_last_error() !== JSON_ERROR_NONE) {
|
||||
error_log('FAILED - json decode - '. json_last_error());
|
||||
exit();
|
||||
}
|
||||
|
||||
// success, do something
|
||||
```
|
||||
|
||||
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
|
||||
|
||||
### 授权头（Authorization header）
|
||||
|
||||
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
|
||||
Reference in New Issue
Block a user