diff --git a/docs/content/doc/usage/agit-support.zh-cn.md b/docs/content/doc/usage/agit-support.zh-cn.md new file mode 100644 index 0000000000..de6eba24b2 --- /dev/null +++ b/docs/content/doc/usage/agit-support.zh-cn.md @@ -0,0 +1,49 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "Agit 设置" +slug: "agit-setup" +weight: 12 +toc: false +draft: false +aliases: + - /zh-cn/agit-setup +menu: + sidebar: + parent: "usage" + name: "Agit 设置" + weight: 12 + identifier: "agit-setup" +--- + +# Agit 设置 + +在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。 + +## 使用 Agit 创建 PR + +Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。 +通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。 +下面的示例说明了这一点： + +```shell +git push origin HEAD:refs/for/master +``` + +该命令的结构如下： + +- `HEAD`：目标分支 +- `refs//`：目标 PR 类型 + - `for`：创建一个以 `` 为目标分支的普通 PR + - `draft`/`for-review`：目前被静默忽略 +- `/`：要打开 PR 的目标分支 +- `-o `：PR 的选项 + - `title`：PR 的标题 + - `topic`：PR 应该打开的分支名称 + - `description`：PR 的描述 + - `force-push`：确认强制更新目标分支 + +下面是另一个高级示例，用于创建一个以 `topic`、`title` 和 `description` 为参数的新 PR，目标分支是 `master`： + +```shell +git push origin HEAD:refs/for/master -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" +``` diff --git a/docs/content/doc/usage/clone-filter.zh-cn.md b/docs/content/doc/usage/clone-filter.zh-cn.md new file mode 100644 index 0000000000..fc174fcb38 --- /dev/null +++ b/docs/content/doc/usage/clone-filter.zh-cn.md @@ -0,0 +1,26 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "克隆过滤器 (部分克隆)" +slug: "clone-filters" +weight: 25 +draft: false +toc: false +aliases: + - /zh-cn/clone-filters +menu: + sidebar: + parent: "usage" + name: "克隆过滤器" + weight: 25 + identifier: "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) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。 diff --git a/docs/content/doc/usage/incoming-email.zh-cn.md b/docs/content/doc/usage/incoming-email.zh-cn.md new file mode 100644 index 0000000000..335e6aa9e2 --- /dev/null +++ b/docs/content/doc/usage/incoming-email.zh-cn.md @@ -0,0 +1,50 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "邮件接收" +slug: "incoming-email" +weight: 13 +draft: false +toc: false +aliases: + - /zh-cn/incoming-email +menu: + sidebar: + parent: "usage" + name: "邮件接收" + weight: 13 + identifier: "incoming-email" +--- + +# 邮件接收 + +Gitea 支持通过接收邮件执行多种操作。本页面描述了如何进行设置。 + +**目录** + +{{< toc >}} + +## 要求 + +处理接收的电子邮件需要启用 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` 上的其他服务可能存在的安全问题。 diff --git a/docs/content/doc/usage/labels.zh-cn.md b/docs/content/doc/usage/labels.zh-cn.md new file mode 100644 index 0000000000..10fef72e75 --- /dev/null +++ b/docs/content/doc/usage/labels.zh-cn.md @@ -0,0 +1,42 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "标签" +slug: "labels" +weight: 13 +toc: false +draft: false +aliases: + - /zh-cn/labels +menu: + sidebar: + parent: "usage" + name: "标签" + weight: 13 + identifier: "labels" +--- + +# 标签 + +您可以使用标签对工单和合并请求进行分类，并提高对它们的概览。 + +## 创建标签 + +对于仓库，可以在 `工单（Issues）` 中点击 `标签（Labels）` 来创建标签。 + +对于组织，您可以定义组织级别的标签，这些标签与所有组织仓库共享，包括已存在的仓库和新创建的仓库。可以在组织的 `设置（Settings）` 中创建组织级别的标签。 + +标签具有必填的名称和颜色，可选的描述，以及必须是独占的或非独占的（见下面的“作用域标签”）。 + +当您创建一个仓库时，可以通过使用 `工单标签（Issue Labels）` 选项来选择标签集。该选项列出了一些在您的实例上 [全局配置的可用标签集](../customizing-gitea/#labels)。在创建仓库时，这些标签也将被创建。 + +## 作用域标签 + +作用域标签用于确保将至多一个具有相同作用域的标签分配给工单或合并请求。例如，如果标签 `kind/bug` 和 `kind/enhancement` 的独占选项被设置，那么工单只能被分类为 bug 或 enhancement 中的一个。 + +作用域标签的名称必须包含 `/`（不能在名称的任一端）。标签的作用域是基于最后一个 `/` 决定的，因此例如标签 `scope/subscope/item` 的作用域是 `scope/subscope`。 + +## 按标签筛选 + +工单和合并请求列表可以按标签进行筛选。选择多个标签将显示具有所有选定标签的工单和合并请求。 + +通过按住 alt 键并单击标签，可以将具有所选标签的工单和合并请求从列表中排除。 diff --git a/docs/content/doc/usage/linked-references.zh-cn.md b/docs/content/doc/usage/linked-references.zh-cn.md new file mode 100644 index 0000000000..e565847387 --- /dev/null +++ b/docs/content/doc/usage/linked-references.zh-cn.md @@ -0,0 +1,156 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "自动链接引用" +slug: "automatically-linked-references" +weight: 15 +toc: false +draft: false +aliases: + - /zh-cn/automatically-linked-references +menu: + sidebar: + parent: "usage" + name: "自动链接引用s" + weight: 15 + identifier: "automatically-linked-references" +--- + +# 在工单、合并请求和提交消息中的自动链接引用 + +**目录** + +{{< toc >}} + +当发布工单、合并请求或评论时，文本描述会被解析以查找引用。这些引用将显示为工单视图中的链接，并且在某些情况下会触发特定的“操作”。 + +类似地，当列出提交消息时，它们也会被解析，并且当它们被推送到主分支时可以触发“操作”。 + +为了防止意外创建引用，对于引用的识别有一定的规则。例如，它们不应该包含在代码文本内部。它们还应该在周围的文本中合理清晰（例如，使用空格）。 + +## 用户、团队和组织提及 + +当找到形式为 `@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”等。这个列表可以由站点管理员进行 [自定义]({{< ref "doc/administration/config-cheat-sheet.zh-cn.md" >}})。 + +示例： + +> 这个合并请求 _closes_ [#1234](#) + +如果可操作的引用被接受，这将在被引用的工单上创建一个通知，宣布当引用的合并请求被合并时该工单将被关闭。 + +为了接受可操作的引用，必须满足以下至少一项条件之一： + +- 评论者在创建引用时具有关闭或重新打开工单的权限。 +- 引用位于提交消息中。 +- 引用作为合并请求描述的一部分发布。 + +在最后一种情况下，只有当合并合并请求的人具有相应权限时，工单才会被关闭或重新打开。 + +此外，只有合并请求和提交消息可以创建一个操作，只有工单可以通过这种方式被关闭或重新打开。 + +默认的关键字如下： + +- **关闭工单**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved +- **重新打开工单**: reopen, reopens, reopened + +## 合并请求和提交消息中的时间跟踪 + +当提交或合并合并请求导致自动关闭工单时，还可以通过提交消息添加解决此工单所花费的时间。 + +要指定解决工单所花费的时间，需要在工单编号后面以 `@` 的格式指定时间。在一个提交消息中，可以指定多个已解决的工单，并为每个工单指定花费的时间。 + +支持的时间单位（``）： + +- `m` - 分钟 +- `h` - 小时 +- `d` - 天（相当于8小时） +- `w` - 周（相当于5天） +- `mo` - 月（相当于4周） + +用于指定时间的数字（``）也可以是小数，例如 `@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. 内部）的仓库之间的自动引用，可能会导致无效链接。 diff --git a/docs/content/doc/usage/merge-message-templates.zh-cn.md b/docs/content/doc/usage/merge-message-templates.zh-cn.md new file mode 100644 index 0000000000..0ec4eee483 --- /dev/null +++ b/docs/content/doc/usage/merge-message-templates.zh-cn.md @@ -0,0 +1,57 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "合并消息模板" +slug: "merge-message-templates" +weight: 15 +toc: false +draft: false +aliases: + - /zh-cn/merge-message-templates +menu: + sidebar: + parent: "usage" + name: "合并消息模板" + weight: 15 + identifier: "merge-message-templates" +--- + +# 合并消息模板 + +**目录** + +{{< toc >}} + +## 文件名 + +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` + +## 变基（Rebase） + +在没有合并提交的情况下进行变基时，`REBASE_TEMPLATE.md` 修改最后一次提交的消息。此模板还提供以下附加变量： + +- CommitTitle：提交的标题 +- CommitBody：提交的正文文本 diff --git a/docs/content/doc/usage/permissions.zh-cn.md b/docs/content/doc/usage/permissions.zh-cn.md new file mode 100644 index 0000000000..3163633589 --- /dev/null +++ b/docs/content/doc/usage/permissions.zh-cn.md @@ -0,0 +1,71 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "权限" +slug: "permissions" +weight: 14 +toc: false +draft: false +aliases: + - /zh-cn/permissions +menu: + sidebar: + parent: "usage" + name: "权限" + weight: 14 + identifier: "permissions" +--- + +# 权限 + +**目录** + +{{< toc >}} + +Gitea 支持对仓库进行权限管理，这样您就可以为不同的人员提供不同的访问权限。首先，我们需要了解 `单元（Unit）`。 + +## 单元（Unit） + +在 Gitea 中，我们将仓库的子模块称为 `单元（Unit）`。现在我们有以下几个单元。 + +| 名称 | 描述 | 权限 | +| ----------------- | --------------------------------------------------- | ------------ | +| 代码 | 访问源代码、文件、提交和分支。 | 读取 写入 | +| 工单 | 组织缺陷报告、任务和里程碑。 | 读取 写入 | +| 合并请求 | 启用合并请求和代码审核。 | 读取 写入 | +| 发布 | 跟踪项目版本和下载。 | 读取 写入 | +| 维基 | 与协作者编写和共享文档。 | 读取 写入 | +| 外部维基 | 链接到外部维基。 | 读取 | +| 外部工单跟踪器 | 链接到外部工单跟踪器。 | 读取 | +| 项目 | 模板仓库的 URL。 | 读取 写入 | +| 设置 | 管理仓库。 | 管理员 | + +通过不同的权限，用户可以在这些单元上执行不同的操作。 + +| 名称 | 读取 | 写入 | 管理员 | +| ----------------- | -------------------------------------------------- | ------------------------------ | ------------------------- | +| 代码 | 查看代码树、文件、提交、分支等。 | 推送代码。 | - | +| 工单 | 查看工单并创建新工单。 | 添加标签、分配、关闭工单。 | - | +| 合并请求 | 查看合并请求并创建新合并请求。 | 添加标签、分配、关闭合并请求。 | - | +| 发布 | 查看发布和下载文件。 | 创建/编辑发布。 | - | +| 维基 | 查看维基页面。克隆维基仓库。 | 创建/编辑维基页面，推送更改。 | - | +| 外部维基 | 链接到外部维基。 | - | - | +| 外部工单跟踪器 | 链接到外部工单跟踪器。 | - | - | +| 项目 | 查看面板。 | 在面板之间移动工单。 | - | +| 设置 | - | - | 管理仓库 | + +个人仓库和组织仓库之间的权限存在一些差异。 + +## 个人仓库 + +对于个人仓库，创建者是仓库的唯一所有者，对于该仓库的任何更改或删除没有限制。仓库所有者可以添加协作者来帮助维护仓库。协作者可以拥有 `读取（Read）`、`写入（Write）` 和 `管理员（Admin）` 权限。 + +## 组织仓库 + +与个人仓库不同，组织仓库的所有者是组织的所有者团队。 + +### 团队 + +组织中的一个团队具有单元权限设置。它可以拥有成员和仓库的范围。团队可以访问组织中的所有仓库或者由所有者团队授权访问的特定仓库。团队也可以被允许创建新的仓库。 + +所有者团队（Owners）将在创建组织时自动创建，并且创建者将成为所有者团队的第一个成员。 +组织的每个成员必须至少属于一个团队。所有者团队不能被删除，只有所有者团队的成员可以创建新的团队。可以创建一个管理员团队来管理某些仓库，该团队的成员可以对这些仓库进行任何操作。可以由所有者团队创建一个生成团队来执行其权限允许的操作。 diff --git a/docs/content/doc/usage/profile-readme.zh-cn.md b/docs/content/doc/usage/profile-readme.zh-cn.md new file mode 100644 index 0000000000..a253fcaf24 --- /dev/null +++ b/docs/content/doc/usage/profile-readme.zh-cn.md @@ -0,0 +1,20 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "个人资料 README" +slug: "profile-readme" +weight: 12 +toc: false +draft: false +menu: + sidebar: + parent: "usage" + name: "个人资料 README" + weight: 12 + identifier: "profile-readme" +--- + +# 个人资料 README + +要在您的 Gitea 个人资料页面显示一个 Markdown 文件，只需创建一个名为 ".profile" 的仓库，并编辑其中的 README.md 文件。Gitea 将自动获取该文件并在您的仓库上方显示。 + +注意：您可以将此仓库设为私有。这样可以隐藏您的源文件，使其对公众不可见，并允许您将某些文件设为私有。但是，README.md 文件将是您个人资料上唯一存在的文件。如果您希望完全私有化 .profile 仓库，则需删除或重命名 README.md 文件。 diff --git a/docs/content/doc/usage/protected-tags.zh-cn.md b/docs/content/doc/usage/protected-tags.zh-cn.md new file mode 100644 index 0000000000..7d43462d32 --- /dev/null +++ b/docs/content/doc/usage/protected-tags.zh-cn.md @@ -0,0 +1,59 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "受保护的标签" +slug: "protected-tags" +weight: 45 +toc: false +draft: false +aliases: + - /zh-cn/protected-tags +menu: + sidebar: + parent: "usage" + name: "受保护的标签" + weight: 45 + identifier: "protected-tags" +--- + +# 受保护的标签 + +受保护的标签允许控制谁有权限创建或更新 Git 标签。每个规则可以匹配单个标签名称，或者使用适当的模式来同时控制多个标签。 + +**目录** + +{{< toc >}} + +## 设置受保护的标签 + +要保护一个标签，你需要按照以下步骤进行操作： + +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 | `/.+/` | 匹配所有可能的标签名称 | diff --git a/docs/content/doc/usage/push.zh-cn.md b/docs/content/doc/usage/push.zh-cn.md new file mode 100644 index 0000000000..a12e1b5349 --- /dev/null +++ b/docs/content/doc/usage/push.zh-cn.md @@ -0,0 +1,72 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "推送" +slug: "push" +weight: 15 +toc: false +draft: false +aliases: + - /zh-cn/push-to-create + - /zh-cn/push-options +menu: + sidebar: + parent: "usage" + name: "推送" + weight: 15 + identifier: "push" +--- + +**目录** + +{{< toc >}} + +在将提交推送到 Gitea 服务器时，还有一些额外的功能。 + +# 通过推送打开 PR + +当您第一次将提交推送到非默认分支时，您将收到一个链接，您可以单击该链接访问分支与主分支的比较页面。 +从那里，您可以轻松创建一个拉取请求，即使您想要将其目标指向另一个分支。 + +![Gitea 推送提示](/gitea-push-hint.png) + +# 推送选项 + +在 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 以使更改生效。您可以在 [配置速查表]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#repository-repository" >}}) 中了解有关这两个选项的更多信息。 + +## 使用推送创建 + +假设您在当前目录中有一个 git 仓库，您可以通过运行以下命令将提交推送到在 Gitea 中尚不存在的仓库： + +```shell +# 添加要推送到的远程仓库 +git remote add origin git@{domain}:{username}/{尚不存在的仓库名称}.git + +# 推送到远程仓库 +git push -u origin main +``` + +这假设您使用的是 SSH 远程，但您也可以使用 HTTPS 远程。 + +推送创建将默认使用 `app.ini` 中定义的可见性 `DEFAULT_PUSH_CREATE_PRIVATE`。 diff --git a/docs/content/doc/usage/repo-mirror.zh-cn.md b/docs/content/doc/usage/repo-mirror.zh-cn.md new file mode 100644 index 0000000000..d327338bad --- /dev/null +++ b/docs/content/doc/usage/repo-mirror.zh-cn.md @@ -0,0 +1,94 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "仓库镜像" +slug: "repo-mirror" +weight: 45 +toc: false +draft: false +aliases: + - /zh-cn/repo-mirror +menu: + sidebar: + parent: "usage" + name: "仓库镜像" + weight: 45 + identifier: "repo-mirror" +--- + +# 仓库镜像 + +仓库镜像允许将仓库与外部源之间进行镜像。您可以使用它在仓库之间镜像分支、标签和提交。 + +**目录** + +{{< toc >}} + +## 使用场景 + +以下是一些仓库镜像的可能使用场景： + +- 您迁移到了 Gitea，但仍需要在其他源中保留您的项目。在这种情况下，您可以简单地设置它以进行镜像到 Gitea（拉取），这样您的 Gitea 实例中就可以获取到所有必要的提交历史、标签和分支。 +- 您在其他源中有一些旧项目，您不再主动使用，但出于归档目的不想删除。在这种情况下，您可以创建一个推送镜像，以便您的活跃的 Gitea 仓库可以将其更改推送到旧位置。 + +## 从远程仓库拉取 + +对于现有的远程仓库，您可以按照以下步骤设置拉取镜像： + +1. 在右上角的“创建...”菜单中选择“迁移外部仓库”。 +2. 选择远程仓库服务。 +3. 输入仓库的 URL。 +4. 如果仓库需要身份验证，请填写您的身份验证信息。 +5. 选中“该仓库将是一个镜像”复选框。 +6. 选择“迁移仓库”以保存配置。 + +现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。 + +:exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation: + +## 推送到远程仓库 + +对于现有的仓库，您可以按照以下步骤设置推送镜像： + +1. 在仓库中，转到**设置** > **仓库**，然后进入**镜像设置**部分。 +2. 输入一个仓库的 URL。 +3. 如果仓库需要身份验证，请展开**授权**部分并填写您的身份验证信息。请注意，所请求的**密码**也可以是您的访问令牌。 +4. 选择**添加推送镜像**以保存配置。 + +该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。 + +: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//.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:////.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//.git`。 +3. 使用您的 Bitbucket 用户名填写**授权**字段，并将应用密码作为**密码**。 +4. 选择**添加推送镜像**以保存配置。 + +仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。 diff --git a/docs/content/doc/usage/secrets.zh-cn.md b/docs/content/doc/usage/secrets.zh-cn.md new file mode 100644 index 0000000000..534fc52eeb --- /dev/null +++ b/docs/content/doc/usage/secrets.zh-cn.md @@ -0,0 +1,39 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "密钥管理" +slug: "secrets" +weight: 50 +draft: false +toc: false +aliases: + - /zh-cn/secrets +menu: + sidebar: + parent: "usage" + name: "密钥管理" + weight: 50 + identifier: "usage-secrets" +--- + +# 密钥管理 + +密钥管理允许您在用户、组织或仓库中存储敏感信息。 +密钥管理在 Gitea 1.19+ 版本中可用。 + +# 设置密钥名称 + +以下规则适用于密钥名称： + +- 密钥名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。 + +- 密钥名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。 + +- 密钥名称不能以数字开头。 + +- 密钥名称不区分大小写。 + +- 密钥名称在创建它们的级别上必须是唯一的。 + +例如，对于在仓库级别创建的密钥，它在该仓库中必须具有唯一的名称；对于在组织级别创建的密钥，它在该级别上必须具有唯一的名称。 + +如果在多个级别上存在具有相同名称的密钥，则最低级别的密钥优先生效。例如，如果组织级别的密钥与仓库级别的密钥具有相同的名称，则仓库级别的密钥将优先生效。 diff --git a/docs/content/doc/usage/template-repositories.zh-cn.md b/docs/content/doc/usage/template-repositories.zh-cn.md new file mode 100644 index 0000000000..f8dfe1064d --- /dev/null +++ b/docs/content/doc/usage/template-repositories.zh-cn.md @@ -0,0 +1,87 @@ +--- +date: "2023-05-23T09:00:00+08:00" +title: "模板仓库" +slug: "template-repositories" +weight: 14 +toc: false +draft: false +aliases: + - /zh-cn/template-repositories +menu: + sidebar: + parent: "usage" + name: "模板仓库" + weight: 14 + identifier: "template-repositories" +--- + +# 模板仓库 + +**目录** + +{{< toc >}} + +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 | diff --git a/docs/content/doc/usage/webhooks.zh-cn.md b/docs/content/doc/usage/webhooks.zh-cn.md index 9e9f2bf502..740304e1ad 100644 --- a/docs/content/doc/usage/webhooks.zh-cn.md +++ b/docs/content/doc/usage/webhooks.zh-cn.md @@ -15,18 +15,178 @@ menu: # Webhooks -Gitea 的存储 webhook。这可以有存储库管路设定页 `/:username/:reponame/settings/hooks` 中的。Webhook 也可以按照组织调整或全系统调整，所有时间的推送都是POST请求 -。此方法目前被下列服务支援： +Gitea支持用于仓库事件的Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks还可以基于组织和整个系统进行配置。 +所有事件推送都是 POST 请求。目前支持： -- Gitea (也可以是 GET 請求) +- Gitea (也可以是 GET 请求) - Gogs - Slack - Discord -- Dingtalk +- Dingtalk（钉钉） - Telegram - Microsoft Teams - Feishu -- Wechatwork +- Wechatwork（企业微信） - Packagist -## TBD +### 事件信息 + +**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755 + +以下是 Gitea 将发送给 payload URL的事件信息示例： + +``` +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。 + +``` +