mirror of
https://github.com/go-gitea/gitea
synced 2025-08-11 03:58:20 +00:00
Docusaurus-ify 1.19 (#26053)
See https://github.com/go-gitea/gitea/pull/26051 --------- Signed-off-by: jolheiser <john.olheiser@gmail.com> Co-authored-by: Giteabot <teabot@gitea.io>
This commit is contained in:
John Olheiser
GitHub
47
docs/content/usage/agit-support.en-us.md
Normal file
47
docs/content/usage/agit-support.en-us.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
date: " 2022-09-01T20:50:42+0000"
|
||||
title: "Agit Setup"
|
||||
slug: "agit-setup"
|
||||
sidebar_position: 12
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Agit Setup"
|
||||
sidebar_position: 12
|
||||
identifier: "agit-setup"
|
||||
---
|
||||
|
||||
# Agit Setup
|
||||
|
||||
In Gitea `1.13`, support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added.
|
||||
|
||||
## 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/master
|
||||
```
|
||||
|
||||
The command has the following structure:
|
||||
|
||||
- `HEAD`: The target branch
|
||||
- `refs/<for|draft|for-review>/<branch>`: The target PR type
|
||||
- `for`: Create a normal PR with `<branch>` as the target branch
|
||||
- `draft`/ `for-review`: Currently ignored silently
|
||||
- `<branch>/<session>`: The target branch to open the PR
|
||||
- `-o <topic|title|description>`: Options for the PR
|
||||
- `title`: The PR title
|
||||
- `topic`: The branch name the PR should be opened for
|
||||
- `description`: The PR description
|
||||
- `force-push`: confirm force update the target branch
|
||||
|
||||
Here's another advanced example for creating a new PR targeting `master` with `topic`, `title`, and `description`:
|
||||
|
||||
```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"
|
||||
```
|
||||
49
docs/content/usage/agit-support.zh-cn.md
Normal file
49
docs/content/usage/agit-support.zh-cn.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "Agit 设置"
|
||||
slug: "agit-setup"
|
||||
sidebar_position: 12
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/agit-setup
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Agit 设置"
|
||||
sidebar_position: 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/<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`：确认强制更新目标分支
|
||||
|
||||
下面是另一个高级示例，用于创建一个以 `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"
|
||||
```
|
||||
348
docs/content/usage/authentication.en-us.md
Normal file
348
docs/content/usage/authentication.en-us.md
Normal file
@@ -0,0 +1,348 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
title: "Authentication"
|
||||
slug: "authentication"
|
||||
sidebar_position: 10
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Authentication"
|
||||
sidebar_position: 10
|
||||
identifier: "authentication"
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
## LDAP (Lightweight Directory Access Protocol)
|
||||
|
||||
Both the LDAP via BindDN and the simple auth LDAP share the following fields:
|
||||
|
||||
- Authorization Name **(required)**
|
||||
|
||||
- A name to assign to the new method of authorization.
|
||||
|
||||
- Host **(required)**
|
||||
|
||||
- The address where the LDAP server can be reached.
|
||||
- Example: `mydomain.com`
|
||||
|
||||
- Port **(required)**
|
||||
|
||||
- The port to use when connecting to the server.
|
||||
- Example: `389` for LDAP or `636` for LDAP SSL
|
||||
|
||||
- Enable TLS Encryption (optional)
|
||||
|
||||
- Whether to use TLS when connecting to the LDAP server.
|
||||
|
||||
- Admin Filter (optional)
|
||||
|
||||
- An LDAP filter specifying if a user should be given administrator
|
||||
privileges. If a user account passes the filter, the user will be
|
||||
privileged as an administrator.
|
||||
- Example: `(objectClass=adminAccount)`
|
||||
- Example for Microsoft Active Directory (AD): `(memberOf=CN=admin-group,OU=example,DC=example,DC=org)`
|
||||
|
||||
- Username attribute (optional)
|
||||
|
||||
- The attribute of the user's LDAP record containing the user name. Given
|
||||
attribute value will be used for new Gitea account user name after first
|
||||
successful sign-in. Leave empty to use login name given on sign-in form.
|
||||
- This is useful when supplied login name is matched against multiple
|
||||
attributes, but only single specific attribute should be used for Gitea
|
||||
account name, see "User Filter".
|
||||
- Example: `uid`
|
||||
- Example for Microsoft Active Directory (AD): `sAMAccountName`
|
||||
|
||||
- First name attribute (optional)
|
||||
|
||||
- The attribute of the user's LDAP record containing the user's first name.
|
||||
This will be used to populate their account information.
|
||||
- Example: `givenName`
|
||||
|
||||
- Surname attribute (optional)
|
||||
|
||||
- The attribute of the user's LDAP record containing the user's surname.
|
||||
This will be used to populate their account information.
|
||||
- Example: `sn`
|
||||
|
||||
- E-mail attribute **(required)**
|
||||
- The attribute of the user's LDAP record containing the user's email
|
||||
address. This will be used to populate their account information.
|
||||
- Example: `mail`
|
||||
|
||||
### LDAP via BindDN
|
||||
|
||||
Adds the following fields:
|
||||
|
||||
- Bind DN (optional)
|
||||
|
||||
- The DN to bind to the LDAP server with when searching for the user. This
|
||||
may be left blank to perform an anonymous search.
|
||||
- Example: `cn=Search,dc=mydomain,dc=com`
|
||||
|
||||
- Bind Password (optional)
|
||||
|
||||
- The password for the Bind DN specified above, if any. _Note: The password
|
||||
is stored encrypted with the SECRET_KEY on the server. It is still recommended
|
||||
to ensure that the Bind DN has as few privileges as possible._
|
||||
|
||||
- User Search Base **(required)**
|
||||
|
||||
- The LDAP base at which user accounts will be searched for.
|
||||
- Example: `ou=Users,dc=mydomain,dc=com`
|
||||
|
||||
- User Filter **(required)**
|
||||
- An LDAP filter declaring how to find the user record that is attempting to
|
||||
authenticate. The `%s` matching parameter will be substituted with login
|
||||
name given on sign-in form.
|
||||
- Example: `(&(objectClass=posixAccount)(uid=%s))`
|
||||
- Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
|
||||
- To substitute more than once, `%[1]s` should be used instead, e.g. when
|
||||
matching supplied login name against multiple attributes such as user
|
||||
identifier, email or even phone number.
|
||||
- Example: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
|
||||
- Enable user synchronization
|
||||
- This option enables a periodic task that synchronizes the Gitea users with
|
||||
the LDAP server. The default period is every 24 hours but that can be
|
||||
changed in the app.ini file. See the _cron.sync_external_users_ section in
|
||||
the [sample
|
||||
app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
|
||||
for detailed comments about that section. The _User Search Base_ and _User
|
||||
Filter_ settings described above will limit which users can use Gitea and
|
||||
which users will be synchronized. When initially run the task will create
|
||||
all LDAP users that match the given settings so take care if working with
|
||||
large Enterprise LDAP directories.
|
||||
|
||||
### LDAP using simple auth
|
||||
|
||||
Adds the following fields:
|
||||
|
||||
- User DN **(required)**
|
||||
|
||||
- A template to use as the user's DN. The `%s` matching parameter will be
|
||||
substituted with login name given on sign-in form.
|
||||
- Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
|
||||
- Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
|
||||
|
||||
- User Search Base (optional)
|
||||
|
||||
- The LDAP base at which user accounts will be searched for.
|
||||
- Example: `ou=Users,dc=mydomain,dc=com`
|
||||
|
||||
- User Filter **(required)**
|
||||
- An LDAP filter declaring when a user should be allowed to log in. The `%s`
|
||||
matching parameter will be substituted with login name given on sign-in
|
||||
form.
|
||||
- Example: `(&(objectClass=posixAccount)(cn=%s))`
|
||||
- Example: `(&(objectClass=posixAccount)(uid=%s))`
|
||||
|
||||
### Verify group membership in LDAP
|
||||
|
||||
Uses the following fields:
|
||||
|
||||
- Group Search Base (optional)
|
||||
|
||||
- The LDAP DN used for groups.
|
||||
- Example: `ou=group,dc=mydomain,dc=com`
|
||||
|
||||
- Group Name Filter (optional)
|
||||
|
||||
- An LDAP filter declaring how to find valid groups in the above DN.
|
||||
- Example: `(|(cn=gitea_users)(cn=admins))`
|
||||
|
||||
- User Attribute in Group (optional)
|
||||
|
||||
- Which user LDAP attribute is listed in the group.
|
||||
- Example: `uid`
|
||||
|
||||
- Group Attribute for User (optional)
|
||||
- Which group LDAP attribute contains an array above user attribute names.
|
||||
- Example: `memberUid`
|
||||
|
||||
## PAM (Pluggable Authentication Module)
|
||||
|
||||
This procedure enables PAM authentication. Users may still be added to the
|
||||
system manually using the user administration. PAM provides a mechanism to
|
||||
automatically add users to the current database by testing them against PAM
|
||||
authentication. To work with normal Linux passwords, the user running Gitea
|
||||
must also have read access to `/etc/shadow` in order to check the validity of
|
||||
the account when logging in using a public key.
|
||||
|
||||
**Note**: If a user has added SSH public keys into Gitea, the use of these
|
||||
keys _may_ bypass the login check system. Therefore, if you wish to disable a user who
|
||||
authenticates with PAM, you _should_ also manually disable the account in Gitea using the
|
||||
built-in user manager.
|
||||
|
||||
1. Configure and prepare the installation.
|
||||
- It is recommended that you create an administrative user.
|
||||
- Deselecting automatic sign-up may also be desired.
|
||||
1. Once the database has been initialized, log in as the newly created
|
||||
administrative user.
|
||||
1. Navigate to the user setting (icon in top-right corner), and select
|
||||
`Site Administration` -> `Authentication Sources`, and select
|
||||
`Add Authentication Source`.
|
||||
1. Fill out the field as follows:
|
||||
- `Authentication Type` : `PAM`
|
||||
- `Name` : Any value should be valid here, use "System Authentication" if
|
||||
you'd like.
|
||||
- `PAM Service Name` : Select the appropriate file listed under `/etc/pam.d/`
|
||||
that performs the authentication desired.[^1]
|
||||
- `PAM Email Domain` : The e-mail suffix to append to user authentication.
|
||||
For example, if the login system expects a user called `gituser`, and this
|
||||
field is set to `mail.com`, then Gitea will expect the `user email` field
|
||||
for an authenticated GIT instance to be `gituser@mail.com`.[^2]
|
||||
|
||||
**Note**: PAM support is added via [build-time flags](https://docs.gitea.io/en-us/install-from-source/#build),
|
||||
and the official binaries provided do not have this enabled. PAM requires that
|
||||
the necessary libpam dynamic library be available and the necessary PAM
|
||||
development headers be accessible to the compiler.
|
||||
|
||||
[^1]: For example, using standard Linux log-in on Debian "Bullseye" use
|
||||
`common-session-noninteractive` - this value may be valid for other flavors of
|
||||
Debian including Ubuntu and Mint, consult your distribution's documentation.
|
||||
[^2]: **This is a required field for PAM**. Be aware: In the above example, the
|
||||
user will log into the Gitea web interface as `gituser` and not `gituser@mail.com`
|
||||
|
||||
## SMTP (Simple Mail Transfer Protocol)
|
||||
|
||||
This option allows Gitea to log in to an SMTP host as a Gitea user. To
|
||||
configure this, set the fields below:
|
||||
|
||||
- Authentication Name **(required)**
|
||||
|
||||
- A name to assign to the new method of authorization.
|
||||
|
||||
- SMTP Authentication Type **(required)**
|
||||
|
||||
- Type of authentication to use to connect to SMTP host, PLAIN or LOGIN.
|
||||
|
||||
- Host **(required)**
|
||||
|
||||
- The address where the SMTP host can be reached.
|
||||
- Example: `smtp.mydomain.com`
|
||||
|
||||
- Port **(required)**
|
||||
|
||||
- The port to use when connecting to the server.
|
||||
- Example: `587`
|
||||
|
||||
- Allowed Domains
|
||||
|
||||
- Restrict what domains can log in if using a public SMTP host or SMTP host
|
||||
with multiple domains.
|
||||
- Example: `gitea.io,mydomain.com,mydomain2.com`
|
||||
|
||||
- Force SMTPS
|
||||
|
||||
- SMTPS will be used by default for connections to port 465, if you wish to use SMTPS
|
||||
for other ports. Set this value.
|
||||
- Otherwise if the server provides the `STARTTLS` extension this will be used.
|
||||
|
||||
- Skip TLS Verify
|
||||
|
||||
- Disable TLS verify on authentication.
|
||||
|
||||
- This Authentication Source is Activated
|
||||
- Enable or disable this authentication source.
|
||||
|
||||
## FreeIPA
|
||||
|
||||
- In order to log in to Gitea using FreeIPA credentials, a bind account needs to
|
||||
be created for Gitea:
|
||||
|
||||
- On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com`
|
||||
with your DN, and provide an appropriately secure password:
|
||||
|
||||
```sh
|
||||
dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
|
||||
changetype: add
|
||||
objectclass: account
|
||||
objectclass: simplesecurityobject
|
||||
uid: gitea
|
||||
userPassword: secure password
|
||||
passwordExpirationTime: 20380119031407Z
|
||||
nsIdleTimeout: 0
|
||||
```
|
||||
|
||||
- Import the LDIF (change localhost to an IPA server if needed). A prompt for
|
||||
Directory Manager password will be presented:
|
||||
|
||||
```sh
|
||||
ldapmodify -h localhost -p 389 -x -D \
|
||||
"cn=Directory Manager" -W -f gitea.ldif
|
||||
```
|
||||
|
||||
- Add an IPA group for gitea_users :
|
||||
|
||||
```sh
|
||||
ipa group-add --desc="Gitea Users" gitea_users
|
||||
```
|
||||
|
||||
- Note: For errors about IPA credentials, run `kinit admin` and provide the
|
||||
domain admin account password.
|
||||
|
||||
- Log in to Gitea as an Administrator and click on "Authentication" under Admin Panel.
|
||||
Then click `Add New Source` and fill in the details, changing all where appropriate.
|
||||
|
||||
## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
|
||||
|
||||
Gitea supports SPNEGO single sign-on authentication (the scheme defined by RFC4559) for the web part of the server via the Security Support Provider Interface (SSPI) built in Windows. SSPI works only in Windows environments - when both the server and the clients are running Windows.
|
||||
|
||||
Before activating SSPI single sign-on authentication (SSO) you have to prepare your environment:
|
||||
|
||||
- Create a separate user account in active directory, under which the `gitea.exe` process will be running (eg. `user` under domain `domain.local`):
|
||||
|
||||
- Create a service principal name for the host where `gitea.exe` is running with class `HTTP`:
|
||||
|
||||
- Start `Command Prompt` or `PowerShell` as a privileged domain user (eg. Domain Administrator)
|
||||
- Run the command below, replacing `host.domain.local` with the fully qualified domain name (FQDN) of the server where the web application will be running, and `domain\user` with the name of the account created in the previous step:
|
||||
|
||||
```sh
|
||||
setspn -A HTTP/host.domain.local domain\user
|
||||
```
|
||||
|
||||
- Sign in (_sign out if you were already signed in_) with the user created
|
||||
|
||||
- Make sure that `ROOT_URL` in the `[server]` section of `custom/conf/app.ini` is the fully qualified domain name of the server where the web application will be running - the same you used when creating the service principal name (eg. `host.domain.local`)
|
||||
|
||||
- Start the web server (`gitea.exe web`)
|
||||
|
||||
- Enable SSPI authentication by adding an `SPNEGO with SSPI` authentication source in `Site Administration -> Authentication Sources`
|
||||
|
||||
- Sign in to a client computer in the same domain with any domain user (client computer, different from the server running `gitea.exe`)
|
||||
|
||||
- If you are using Chrome or Edge, add the URL of the web app to the Local intranet sites (`Internet Options -> Security -> Local intranet -> Sites`)
|
||||
|
||||
- Start Chrome or Edge and navigate to the FQDN URL of Gitea (eg. `http://host.domain.local:3000`)
|
||||
|
||||
- Click the `Sign In` button on the dashboard and choose SSPI to be automatically logged in with the same user that is currently logged on to the computer
|
||||
|
||||
- If it does not work, make sure that:
|
||||
- You are not running the web browser on the same server where Gitea is running. You should be running the web browser on a domain joined computer (client) that is different from the server. If both the client and server are running on the same computer NTLM will be preferred over Kerberos.
|
||||
- There is only one `HTTP/...` SPN for the host
|
||||
- The SPN contains only the hostname, without the port
|
||||
- You have added the URL of the web app to the `Local intranet zone`
|
||||
- The clocks of the server and client should not differ with more than 5 minutes (depends on group policy)
|
||||
- `Integrated Windows Authentication` should be enabled in Internet Explorer (under `Advanced settings`)
|
||||
|
||||
## Reverse Proxy
|
||||
|
||||
Gitea supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with
|
||||
|
||||
```ini
|
||||
[service]
|
||||
ENABLE_REVERSE_PROXY_AUTHENTICATION = true
|
||||
```
|
||||
|
||||
The default login user name is in the `X-WEBAUTH-USER` header, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_USER` in app.ini. If the user doesn't exist, you can enable automatic registration with `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true`.
|
||||
|
||||
The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_EMAIL` in app.ini, this could also be disabled with `ENABLE_REVERSE_PROXY_EMAIL`
|
||||
|
||||
If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
|
||||
|
||||
You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
|
||||
|
||||
Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests.
|
||||
35
docs/content/usage/authentication.zh-cn.md
Normal file
35
docs/content/usage/authentication.zh-cn.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
title: "认证"
|
||||
slug: "authentication"
|
||||
sidebar_position: 10
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "认证"
|
||||
sidebar_position: 10
|
||||
identifier: "authentication"
|
||||
---
|
||||
|
||||
# 认证
|
||||
|
||||
## 反向代理认证
|
||||
|
||||
Gitea 支持通过读取反向代理传递的 HTTP 头中的登录名或者 email 地址来支持反向代理来认证。默认是不启用的，你可以用以下配置启用。
|
||||
|
||||
```ini
|
||||
[service]
|
||||
ENABLE_REVERSE_PROXY_AUTHENTICATION = true
|
||||
```
|
||||
|
||||
默认的登录用户名的 HTTP 头是 `X-WEBAUTH-USER`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_USER` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。
|
||||
|
||||
默认的登录用户 Email 的 HTTP 头是 `X-WEBAUTH-EMAIL`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_EMAIL` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。你也可以通过修改 `ENABLE_REVERSE_PROXY_EMAIL` 来启用或停用这个 HTTP 头。
|
||||
|
||||
如果设置了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，则用户的全名会从 `X-WEBAUTH-FULLNAME` 读取，这样在自动创建用户时将使用这个字段作为用户全名，你也可以通过修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 来变更 HTTP 头。
|
||||
|
||||
你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的IP地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
|
||||
|
||||
注意：反向代理认证不支持认证 API，API 仍旧需要用 access token 来进行认证。
|
||||
18
docs/content/usage/authentication.zh-tw.md
Normal file
18
docs/content/usage/authentication.zh-tw.md
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
title: "認證"
|
||||
slug: "authentication"
|
||||
sidebar_position: 10
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "認證"
|
||||
sidebar_position: 10
|
||||
identifier: "authentication"
|
||||
---
|
||||
|
||||
# 認證
|
||||
|
||||
## TBD
|
||||
37
docs/content/usage/clone-filter.en-us.md
Normal file
37
docs/content/usage/clone-filter.en-us.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
date: "2021-02-02"
|
||||
title: "Clone filters (partial clone)"
|
||||
slug: "clone-filters"
|
||||
sidebar_position: 25
|
||||
draft: false
|
||||
toc: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Clone filters"
|
||||
sidebar_position: 25
|
||||
identifier: "clone-filters"
|
||||
---
|
||||
|
||||
# Clone filters (partial clone)
|
||||
|
||||
Git introduces `--filter` option to `git clone` command, which filters out
|
||||
large files and objects (such as blobs) to create partial clone of a repo.
|
||||
Clone filters are especially useful for large repo and/or metered connection,
|
||||
where full clone (without `--filter`) can be expensive (as all history data
|
||||
must be downloaded).
|
||||
|
||||
This requires Git version 2.22 or later, both on the Gitea server and on the
|
||||
client. For clone filters to work properly, make sure that Git version
|
||||
on the client is at least the same as on the server (or later). Login to
|
||||
Gitea server as admin and head to Site Administration -> Configuration to
|
||||
see Git version of the server.
|
||||
|
||||
By default, clone filters are enabled, unless `DISABLE_PARTIAL_CLONE` under
|
||||
`[git]` is set to `true`.
|
||||
|
||||
See [GitHub blog post: Get up to speed with partial clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/)
|
||||
for common use cases of clone filters (blobless and treeless clones), and
|
||||
[GitLab docs for partial clone](https://docs.gitlab.com/ee/topics/git/partial_clone.html)
|
||||
for more advanced use cases (such as filter by file size and remove
|
||||
filters to turn partial clone into full clone).
|
||||
26
docs/content/usage/clone-filter.zh-cn.md
Normal file
26
docs/content/usage/clone-filter.zh-cn.md
Normal file
@@ -0,0 +1,26 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "克隆过滤器 (部分克隆)"
|
||||
slug: "clone-filters"
|
||||
sidebar_position: 25
|
||||
draft: false
|
||||
toc: false
|
||||
aliases:
|
||||
- /zh-cn/clone-filters
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "克隆过滤器"
|
||||
sidebar_position: 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) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。
|
||||
44
docs/content/usage/incoming-email.en-us.md
Normal file
44
docs/content/usage/incoming-email.en-us.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
date: "2022-12-01T00:00:00+00:00"
|
||||
title: "Incoming Email"
|
||||
slug: "incoming-email"
|
||||
sidebar_position: 13
|
||||
draft: false
|
||||
toc: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Incoming Email"
|
||||
sidebar_position: 13
|
||||
identifier: "incoming-email"
|
||||
---
|
||||
|
||||
# Incoming Email
|
||||
|
||||
Gitea supports the execution of several actions through incoming mails. This page describes how to set this up.
|
||||
|
||||
## Requirements
|
||||
|
||||
Handling incoming email messages requires an IMAP-enabled email account.
|
||||
The recommended strategy is to use [email sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) but a catch-all mailbox does work too.
|
||||
The receiving email address contains a user/action specific token which tells Gitea which action should be performed.
|
||||
This token is expected in the `To` and `Delivered-To` header fields.
|
||||
|
||||
Gitea tries to detect automatic responses to skip and the email server should be configured to reduce the incoming noise too (spam, newsletter).
|
||||
|
||||
## Configuration
|
||||
|
||||
To activate the handling of incoming email messages you have to configure the `email.incoming` section in the configuration file.
|
||||
|
||||
The `REPLY_TO_ADDRESS` contains the address an email client will respond to.
|
||||
This address needs to contain the `%{token}` placeholder which will be replaced with a token describing the user/action.
|
||||
This placeholder must only appear once in the address and must be in the user part of the address (before the `@`).
|
||||
|
||||
An example using email sub-addressing may look like this: `incoming+%{token}@example.com`
|
||||
|
||||
If a catch-all mailbox is used, the placeholder may be used anywhere in the user part of the address: `incoming+%{token}@example.com`, `incoming_%{token}@example.com`, `%{token}@example.com`
|
||||
|
||||
## Security
|
||||
|
||||
Be careful when choosing the domain used for receiving incoming email.
|
||||
It's recommended receiving incoming email on a subdomain, such as `incoming.example.com` to prevent potential security problems with other services running on `example.com`.
|
||||
46
docs/content/usage/incoming-email.zh-cn.md
Normal file
46
docs/content/usage/incoming-email.zh-cn.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "邮件接收"
|
||||
slug: "incoming-email"
|
||||
sidebar_position: 13
|
||||
draft: false
|
||||
toc: false
|
||||
aliases:
|
||||
- /zh-cn/incoming-email
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "邮件接收"
|
||||
sidebar_position: 13
|
||||
identifier: "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` 上的其他服务可能存在的安全问题。
|
||||
265
docs/content/usage/issue-pull-request-templates.en-us.md
Normal file
265
docs/content/usage/issue-pull-request-templates.en-us.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
date: "2018-05-10T16:00:00+02:00"
|
||||
title: "Issue and Pull Request templates"
|
||||
slug: "issue-pull-request-templates"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Issue and Pull Request templates"
|
||||
sidebar_position: 15
|
||||
identifier: "issue-pull-request-templates"
|
||||
---
|
||||
|
||||
# Issue and Pull Request Templates
|
||||
|
||||
Some projects have a standard list of questions that users need to answer
|
||||
when creating an issue or pull request. Gitea supports adding templates to the
|
||||
main branch of the repository so that they can autopopulate the form when users are
|
||||
creating issues and pull requests. This will cut down on the initial back and forth
|
||||
of getting some clarifying details.
|
||||
|
||||
Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
|
||||
|
||||
## File names
|
||||
|
||||
Possible file names for issue templates:
|
||||
|
||||
- `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`
|
||||
|
||||
Possible file names for PR templates:
|
||||
|
||||
- `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`
|
||||
|
||||
## Directory names
|
||||
|
||||
Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically
|
||||
addresses their problem.
|
||||
|
||||
Possible directory names for issue templates:
|
||||
|
||||
- `ISSUE_TEMPLATE`
|
||||
- `issue_template`
|
||||
- `.gitea/ISSUE_TEMPLATE`
|
||||
- `.gitea/issue_template`
|
||||
- `.github/ISSUE_TEMPLATE`
|
||||
- `.github/issue_template`
|
||||
- `.gitlab/ISSUE_TEMPLATE`
|
||||
- `.gitlab/issue_template`
|
||||
|
||||
Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) issue templates of the form.
|
||||
|
||||
## Syntax for markdown template
|
||||
|
||||
```md
|
||||
---
|
||||
|
||||
name: "Template Name"
|
||||
about: "This template is for testing!"
|
||||
title: "[TEST] "
|
||||
ref: "main"
|
||||
labels:
|
||||
|
||||
- bug
|
||||
- "help needed"
|
||||
|
||||
---
|
||||
|
||||
This is the template!
|
||||
```
|
||||
|
||||
In the above example, when a user is presented with the list of issues they can submit, this would show as `Template Name` with the description
|
||||
`This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with
|
||||
`[TEST] ` while the issue body would be pre-populated with `This is the template!`. The issue would also be assigned two labels,
|
||||
`bug` and `help needed`, and the issue will have a reference to `main`.
|
||||
|
||||
## Syntax for yaml template
|
||||
|
||||
This example YAML configuration file defines an issue form using several inputs to report a 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
|
||||
|
||||
You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted.
|
||||
|
||||
Attributes:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|-------|--------------------------------------------------------------|----------|--------|---------|--------------|
|
||||
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
|
||||
|
||||
### Textarea
|
||||
|
||||
You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields.
|
||||
|
||||
Attributes:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|--------------|---------------------------|
|
||||
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
|
||||
| description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
|
||||
| placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - |
|
||||
| value | Text that is pre-filled in the text area. | Optional | String | - | - |
|
||||
| render | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | - | Languages known to Gitea. |
|
||||
|
||||
Validations:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|----------|------------------------------------------------------|----------|---------|---------|--------------|
|
||||
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
|
||||
|
||||
### Input
|
||||
|
||||
You can use an `input` element to add a single-line text field to your form.
|
||||
|
||||
Attributes:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|-------------|--------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
|
||||
| label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - |
|
||||
| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
|
||||
| placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - |
|
||||
| value | Text that is pre-filled in the field. | Optional | String | - | - |
|
||||
|
||||
Validations:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------|
|
||||
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
|
||||
| is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - |
|
||||
| regex | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String | - | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
|
||||
|
||||
### Dropdown
|
||||
|
||||
You can use a `dropdown` element to add a dropdown menu in your form.
|
||||
|
||||
Attributes:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
|
||||
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
|
||||
| description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - |
|
||||
| multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - |
|
||||
| options | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | Required | String array | - | - |
|
||||
|
||||
Validations:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|----------|------------------------------------------------------|----------|---------|---------|--------------|
|
||||
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
|
||||
|
||||
### Checkboxes
|
||||
|
||||
You can use the `checkboxes` element to add a set of checkboxes to your form.
|
||||
|
||||
Attributes:
|
||||
|
||||
| Key | Description | Required | Type | Default | Valid values |
|
||||
|-------------|-------------------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
|
||||
| label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - |
|
||||
| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - |
|
||||
| options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - |
|
||||
|
||||
For each value in the options array, you can set the following keys.
|
||||
|
||||
| Key | Description | Required | Type | Default | Options |
|
||||
|----------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|---------|---------|
|
||||
| label | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String | - | - |
|
||||
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
|
||||
292
docs/content/usage/issue-pull-request-templates.zh-cn.md
Normal file
292
docs/content/usage/issue-pull-request-templates.zh-cn.md
Normal file
@@ -0,0 +1,292 @@
|
||||
---
|
||||
date: "2022-09-07T16:00:00+08:00"
|
||||
title: "从模板创建工单与合并请求"
|
||||
slug: "issue-pull-request-templates"
|
||||
sidebar_position: 15
|
||||
toc: true
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "从模板创建工单与合并请求"
|
||||
sidebar_position: 15
|
||||
identifier: "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 还会被分配两个标签，`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 | - |
|
||||
40
docs/content/usage/labels.en-us.md
Normal file
40
docs/content/usage/labels.en-us.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
date: "2023-03-04T19:00:00+00:00"
|
||||
title: "Labels"
|
||||
slug: "labels"
|
||||
sidebar_position: 13
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Labels"
|
||||
sidebar_position: 13
|
||||
identifier: "labels"
|
||||
---
|
||||
|
||||
# Labels
|
||||
|
||||
You can use labels to classify issues and pull requests and to improve your overview over them.
|
||||
|
||||
## Creating Labels
|
||||
|
||||
For repositories, labels can be created by going to `Issues` and clicking on `Labels`.
|
||||
|
||||
For organizations, you can define organization-wide labels that are shared with all organization repositories, including both already-existing repositories as well as newly created ones. Organization-wide labels can be created in the organization `Settings`.
|
||||
|
||||
Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
|
||||
|
||||
When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](./customizing-gitea/#labels). Its contained labels will all be created as well while creating the repository.
|
||||
|
||||
## Scoped Labels
|
||||
|
||||
Scoped labels are used to ensure at most a single label with the same scope is assigned to an issue or pull request. For example, if labels `kind/bug` and `kind/enhancement` have the Exclusive option set, an issue can only be classified as a bug or an enhancement.
|
||||
|
||||
A scoped label must contain `/` in its name (not at either end of the name). The scope of a label is determined based on the **last** `/`, so for example the scope of label `scope/subscope/item` is `scope/subscope`.
|
||||
|
||||
## Filtering by Label
|
||||
|
||||
Issue and pull request lists can be filtered by label. Selecting multiple labels shows issues and pull requests that have all selected labels assigned.
|
||||
|
||||
By holding alt to click the label, issues and pull requests with the chosen label are excluded from the list.
|
||||
42
docs/content/usage/labels.zh-cn.md
Normal file
42
docs/content/usage/labels.zh-cn.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "标签"
|
||||
slug: "labels"
|
||||
sidebar_position: 13
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/labels
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "标签"
|
||||
sidebar_position: 13
|
||||
identifier: "labels"
|
||||
---
|
||||
|
||||
# 标签
|
||||
|
||||
您可以使用标签对工单和合并请求进行分类，并提高对它们的概览。
|
||||
|
||||
## 创建标签
|
||||
|
||||
对于仓库，可以在 `工单（Issues）` 中点击 `标签（Labels）` 来创建标签。
|
||||
|
||||
对于组织，您可以定义组织级别的标签，这些标签与所有组织仓库共享，包括已存在的仓库和新创建的仓库。可以在组织的 `设置（Settings）` 中创建组织级别的标签。
|
||||
|
||||
标签具有必填的名称和颜色，可选的描述，以及必须是独占的或非独占的（见下面的“作用域标签”）。
|
||||
|
||||
当您创建一个仓库时，可以通过使用 `工单标签（Issue Labels）` 选项来选择标签集。该选项列出了一些在您的实例上 [全局配置的可用标签集](../customizing-gitea/#labels)。在创建仓库时，这些标签也将被创建。
|
||||
|
||||
## 作用域标签
|
||||
|
||||
作用域标签用于确保将至多一个具有相同作用域的标签分配给工单或合并请求。例如，如果标签 `kind/bug` 和 `kind/enhancement` 的独占选项被设置，那么工单只能被分类为 bug 或 enhancement 中的一个。
|
||||
|
||||
作用域标签的名称必须包含 `/`（不能在名称的任一端）。标签的作用域是基于最后一个 `/` 决定的，因此例如标签 `scope/subscope/item` 的作用域是 `scope/subscope`。
|
||||
|
||||
## 按标签筛选
|
||||
|
||||
工单和合并请求列表可以按标签进行筛选。选择多个标签将显示具有所有选定标签的工单和合并请求。
|
||||
|
||||
通过按住 alt 键并单击标签，可以将具有所选标签的工单和合并请求从列表中排除。
|
||||
199
docs/content/usage/linked-references.en-us.md
Normal file
199
docs/content/usage/linked-references.en-us.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
date: "2019-11-21T17:00:00-03:00"
|
||||
title: "Automatically Linked References"
|
||||
slug: "automatically-linked-references"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Automatically Linked References"
|
||||
sidebar_position: 15
|
||||
identifier: "automatically-linked-references"
|
||||
---
|
||||
|
||||
# Automatically Linked References in Issues, Pull Requests and Commit Messages
|
||||
|
||||
When an issue, pull request or comment is posted, the text description is parsed
|
||||
in search for references. These references will be shown as links in the Issue View
|
||||
and, in some cases, produce certain _actions_.
|
||||
|
||||
Likewise, commit messages are parsed when they are listed, and _actions_
|
||||
can be triggered when they are pushed to the main branch.
|
||||
|
||||
To prevent the creation of unintended references, there are certain rules
|
||||
for them to be recognized. For example, they should not be included inside code
|
||||
text. They should also be reasonably cleared from their surrounding text
|
||||
(for example, using spaces).
|
||||
|
||||
## User, Team and Organization Mentions
|
||||
|
||||
When a text in the form `@username` is found and `username` matches the name
|
||||
of an existing user, a _mention_ reference is created. This will be shown
|
||||
by changing the text into a link to said user's profile, and possibly create
|
||||
a notification for the mentioned user depending on whether they have
|
||||
the necessary permission to access the contents.
|
||||
|
||||
Example:
|
||||
|
||||
> [@John](#), can you give this a look?
|
||||
|
||||
This is also valid for teams and organizations:
|
||||
|
||||
> [@Documenters](#), we need to plan for this.
|
||||
> [@CoolCompanyInc](#), this issue concerns us all!
|
||||
|
||||
Teams will receive mail notifications when appropriate, but whole organizations won't.
|
||||
|
||||
Commit messages do not produce user notifications.
|
||||
|
||||
## Commits
|
||||
|
||||
Commits can be referenced using their SHA1 hash, or a portion of it of
|
||||
at least seven characters. They will be shown as a link to the corresponding
|
||||
commit.
|
||||
|
||||
Example:
|
||||
|
||||
> This bug was introduced in [e59ff077](#)
|
||||
|
||||
## Issues and Pull Requests
|
||||
|
||||
A reference to another issue or pull request can be created using the simple
|
||||
notation `#1234`, where _1234_ is the number of an issue or pull request
|
||||
in the same repository. These references will be shown as links to the
|
||||
referenced content.
|
||||
|
||||
The effect of creating this type of reference is that a _notice_ will be
|
||||
created in the referenced document, provided the creator of the reference
|
||||
has reading permissions on it.
|
||||
|
||||
Example:
|
||||
|
||||
> This seems related to [#1234](#)
|
||||
|
||||
Issues and pull requests in other repositories can be referred to as well
|
||||
using the form `owner/repository#1234`:
|
||||
|
||||
> This seems related to [mike/compiler#1234](#)
|
||||
|
||||
Alternatively, the `!1234` notation can be used as well. Even when in Gitea
|
||||
a pull request is a form of issue, the `#1234` form will always link to
|
||||
an issue; if the linked entry happens to be a pull request instead, Gitea
|
||||
will redirect as appropriate. With the `!1234` notation, a pull request
|
||||
link will be created, which will be redirected to an issue if required.
|
||||
However, this distinction could be important if an external tracker is
|
||||
used, where links to issues and pull requests are not interchangeable.
|
||||
|
||||
## Actionable References in Pull Requests and Commit Messages
|
||||
|
||||
Sometimes a commit or pull request may fix or bring back a problem documented
|
||||
in a particular issue. Gitea supports closing and reopening the referenced
|
||||
issues by preceding the reference with a particular _keyword_. Common keywords
|
||||
include "closes", "fixes", "reopens", etc. This list can be
|
||||
[customized]({{< ref "doc/administration/config-cheat-sheet.en-us.md" >}}) by the
|
||||
site administrator.
|
||||
|
||||
Example:
|
||||
|
||||
> This PR _closes_ [#1234](#)
|
||||
|
||||
If the actionable reference is accepted, this will create a notice on the
|
||||
referenced issue announcing that it will be closed when the referencing PR
|
||||
is merged.
|
||||
|
||||
For an actionable reference to be accepted, _at least one_ of the following
|
||||
conditions must be met:
|
||||
|
||||
- The commenter has permissions to close or reopen the issue at the moment
|
||||
of creating the reference.
|
||||
- The reference is inside a commit message.
|
||||
- The reference is posted as part of the pull request description.
|
||||
|
||||
In the last case, the issue will be closed or reopened only if the merger
|
||||
of the pull request has permissions to do so.
|
||||
|
||||
Additionally, only pull requests and commit messages can create an action,
|
||||
and only issues can be closed or reopened this way.
|
||||
|
||||
The default _keywords_ are:
|
||||
|
||||
- **Closing**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
|
||||
- **Reopening**: reopen, reopens, reopened
|
||||
|
||||
## Time tracking in Pull Requests and Commit Messages
|
||||
|
||||
When commit or merging of pull request results in automatic closing of issue
|
||||
it is possible to also add spent time resolving this issue through commit message.
|
||||
|
||||
To specify spent time on resolving issue you need to specify time in format
|
||||
`@<number><time-unit>` after issue number. In one commit message you can specify
|
||||
multiple fixed issues and spent time for each of them.
|
||||
|
||||
Supported time units (`<time-unit>`):
|
||||
|
||||
- `m` - minutes
|
||||
- `h` - hours
|
||||
- `d` - days (equals to 8 hours)
|
||||
- `w` - weeks (equals to 5 days)
|
||||
- `mo` - months (equals to 4 weeks)
|
||||
|
||||
Numbers to specify time (`<number>`) can be also decimal numbers, ex. `@1.5h` would
|
||||
result in one and half hours. Multiple time units can be combined, ex. `@1h10m` would
|
||||
mean 1 hour and 10 minutes.
|
||||
|
||||
Example of commit message:
|
||||
|
||||
> Fixed #123 spent @1h, refs #102, fixes #124 @1.5h
|
||||
|
||||
This would result in 1 hour added to issue #123 and 1 and half hours added to issue #124.
|
||||
|
||||
## External Trackers
|
||||
|
||||
Gitea supports the use of external issue trackers, and references to issues
|
||||
hosted externally can be created in pull requests. However, if the external
|
||||
tracker uses numbers to identify issues, they will be indistinguishable from
|
||||
the pull requests hosted in Gitea. To address this, Gitea allows the use of
|
||||
the `!` marker to identify pull requests. For example:
|
||||
|
||||
> This is issue [#1234](#), and links to the external tracker.
|
||||
> This is pull request [!1234](#), and links to a pull request in Gitea.
|
||||
|
||||
The `!` and `#` can be used interchangeably for issues and pull request _except_
|
||||
for this case, where a distinction is required. If the repository uses external
|
||||
tracker, commit message for squash merge will use `!` as reference by default.
|
||||
|
||||
## Issues and Pull Requests References Summary
|
||||
|
||||
This table illustrates the different kinds of cross-reference for issues and pull requests.
|
||||
In the examples, `User1/Repo1` refers to the repository where the reference is used, while
|
||||
`UserZ/RepoZ` indicates a different repository.
|
||||
|
||||
| Reference in User1/Repo1 | Repo1 issues are external | RepoZ issues are external | Should render |
|
||||
| --------------------------- | :-----------------------: | :-----------------------: | ------------------------------------------------------- |
|
||||
| `#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
|
||||
| `!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
|
||||
| `#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` |
|
||||
| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
|
||||
| `User1/Repo1#1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
|
||||
| `User1/Repo1!1234` | no | N/A | A link to issue/pull 1234 in `User1/Repo1` |
|
||||
| `User1/Repo1#1234` | yes | N/A | A link to _external issue_ 1234 for `User1/Repo1` |
|
||||
| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
|
||||
| `UserZ/RepoZ#1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
|
||||
| `UserZ/RepoZ!1234` | N/A | no | A link to issue/pull 1234 in `UserZ/RepoZ` |
|
||||
| `UserZ/RepoZ#1234` | N/A | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` |
|
||||
| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 for `UserZ/RepoZ` |
|
||||
| **Alphanumeric issue IDs:** | - | - | - |
|
||||
| `AAA-1234` | yes | N/A | A link to _external issue_ `AAA-1234` for `User1/Repo1` |
|
||||
| `!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
|
||||
| `User1/Repo1!1234` | yes | N/A | A link to _PR_ 1234 for `User1/Repo1` |
|
||||
| _Not supported_ | N/A | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` |
|
||||
| `UserZ/RepoZ!1234` | N/A | yes | A link to _PR_ 1234 in `UserZ/RepoZ` |
|
||||
|
||||
_The last section is for repositories with external issue trackers that use alphanumeric format._
|
||||
|
||||
_**N/A**: not applicable._
|
||||
|
||||
Note: automatic references between repositories with different types of issues (external vs. internal) are not fully supported
|
||||
and may render invalid links.
|
||||
152
docs/content/usage/linked-references.zh-cn.md
Normal file
152
docs/content/usage/linked-references.zh-cn.md
Normal file
@@ -0,0 +1,152 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "自动链接引用"
|
||||
slug: "automatically-linked-references"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/automatically-linked-references
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "自动链接引用s"
|
||||
sidebar_position: 15
|
||||
identifier: "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”等。这个列表可以由站点管理员进行 [自定义]({{< ref "doc/administration/config-cheat-sheet.zh-cn.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. 内部）的仓库之间的自动引用，可能会导致无效链接。
|
||||
44
docs/content/usage/merge-message-templates.en-us.md
Normal file
44
docs/content/usage/merge-message-templates.en-us.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
date: "2022-08-31T17:35:40+08:00"
|
||||
title: "Merge Message templates"
|
||||
slug: "merge-message-templates"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Merge Message templates"
|
||||
sidebar_position: 15
|
||||
identifier: "merge-message-templates"
|
||||
---
|
||||
|
||||
# Merge Message templates
|
||||
|
||||
## File names
|
||||
|
||||
Possible file names for PR default merge message templates:
|
||||
|
||||
- `.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`
|
||||
|
||||
## Variables
|
||||
|
||||
You can use the following variables enclosed in `${}` inside these templates which follow [os.Expand](https://pkg.go.dev/os#Expand) syntax:
|
||||
|
||||
- BaseRepoOwnerName: Base repository owner name of this pull request
|
||||
- BaseRepoName: Base repository name of this pull request
|
||||
- BaseBranch: Base repository target branch name of this pull request
|
||||
- HeadRepoOwnerName: Head repository owner name of this pull request
|
||||
- HeadRepoName: Head repository name of this pull request
|
||||
- HeadBranch: Head repository branch name of this pull request
|
||||
- PullRequestTitle: Pull request's title
|
||||
- PullRequestDescription: Pull request's description
|
||||
- PullRequestPosterName: Pull request's poster name
|
||||
- PullRequestIndex: Pull request's index number
|
||||
- PullRequestReference: Pull request's reference char with index number. i.e. #1, !2
|
||||
- ClosingIssues: return a string contains all issues which will be closed by this pull request i.e. `close #1, close #2`
|
||||
53
docs/content/usage/merge-message-templates.zh-cn.md
Normal file
53
docs/content/usage/merge-message-templates.zh-cn.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "合并消息模板"
|
||||
slug: "merge-message-templates"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/merge-message-templates
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "合并消息模板"
|
||||
sidebar_position: 15
|
||||
identifier: "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`
|
||||
|
||||
## 变基（Rebase）
|
||||
|
||||
在没有合并提交的情况下进行变基时，`REBASE_TEMPLATE.md` 修改最后一次提交的消息。此模板还提供以下附加变量：
|
||||
|
||||
- CommitTitle：提交的标题
|
||||
- CommitBody：提交的正文文本
|
||||
84
docs/content/usage/permissions.en-us.md
Normal file
84
docs/content/usage/permissions.en-us.md
Normal file
@@ -0,0 +1,84 @@
|
||||
---
|
||||
date: "2021-12-13:10:10+08:00"
|
||||
title: "Permissions"
|
||||
slug: "permissions"
|
||||
sidebar_position: 14
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Permissions"
|
||||
sidebar_position: 14
|
||||
identifier: "permissions"
|
||||
---
|
||||
|
||||
# Permissions
|
||||
|
||||
Gitea supports permissions for repository so that you can give different access for different people. At first, we need to know about `Unit`.
|
||||
|
||||
## Unit
|
||||
|
||||
In Gitea, we call a sub module of a repository `Unit`. Now we have following possible units.
|
||||
|
||||
| Name | Description | Permissions |
|
||||
| --------------- | ---------------------------------------------------- | ----------- |
|
||||
| Code | Access source code, files, commits and branches. | Read Write |
|
||||
| Issues | Organize bug reports, tasks and milestones. | Read Write |
|
||||
| PullRequests | Enable pull requests and code reviews. | Read Write |
|
||||
| Releases | Track project versions and downloads. | Read Write |
|
||||
| Wiki | Write and share documentation with collaborators. | Read Write |
|
||||
| ExternalWiki | Link to an external wiki | Read |
|
||||
| ExternalTracker | Link to an external issue tracker | Read |
|
||||
| Projects | The URL to the template repository | Read Write |
|
||||
| Packages | Packages which linked to this repository | Read Write |
|
||||
| Actions | Review actions logs or restart/cacnel pipelines | Read Write |
|
||||
| Settings | Manage the repository | Admin |
|
||||
|
||||
With different permissions, people could do different things with these units.
|
||||
|
||||
| Name | Read | Write | Admin |
|
||||
| --------------- | ------------------------------------------------- | ---------------------------- | ------------------------- |
|
||||
| Code | View code trees, files, commits, branches and etc. | Push codes. | - |
|
||||
| Issues | View issues and create new issues. | Add labels, assign, close | - |
|
||||
| PullRequests | View pull requests and create new pull requests. | Add labels, assign, close | - |
|
||||
| Releases | View releases and download files. | Create/Edit releases | - |
|
||||
| Wiki | View wiki pages. Clone the wiki repository. | Create/Edit wiki pages, push | - |
|
||||
| ExternalWiki | Link to an external wiki | - | - |
|
||||
| ExternalTracker | Link to an external issue tracker | - | - |
|
||||
| Projects | View the boards | Change issues across boards | - |
|
||||
| Packages | View the packages | Upload/Delete packages | - |
|
||||
| Actions | View the Actions logs | Approve / Cancel / Restart | - |
|
||||
| Settings | - | - | Manage the repository |
|
||||
|
||||
And there are some differences for permissions between individual repositories and organization repositories.
|
||||
|
||||
## Individual Repository
|
||||
|
||||
For individual repositories, the creators are the only owners of repositories and have no limit to change anything of this
|
||||
repository or delete it. Repositories owners could add collaborators to help maintain the repositories. Collaborators could have `Read`, `Write` and `Admin` permissions.
|
||||
|
||||
For a private repository, the experience is similar to visiting an anonymous public repository. You have access to all the available content within the repository, including the ability to clone the code, create issues, respond to issue comments, submit pull requests, and more. If you have 'Write' permission, you can push code to specific branches of the repository, provided it's permitted by the branch protection rules. Additionally, you can make changes to the wiki pages. With 'Admin' permission, you have the ability to modify the repository's settings.
|
||||
|
||||
But you cannot delete or transfer this repository if you are not that repository's owner.
|
||||
|
||||
## Organization Repository
|
||||
|
||||
For individual repositories, the owner is the user who created it. For organization repositories, the owners are the members of the owner team on this organization. All the permissions depends on the team permission settings.
|
||||
|
||||
### Owner Team
|
||||
|
||||
The owner team will be created when the organization is created, and the creator will become the first member of the owner team. The owner team cannot be deleted and there is at least one member.
|
||||
|
||||
### Admin Team
|
||||
|
||||
When creating teams, there are two types of teams. One is the admin team, another is the general team. An admin team can be created to manage some of the repositories, whose members can do anything with these repositories. Only members of the owner or admin team can create a new team.
|
||||
|
||||
### General Team
|
||||
|
||||
A general team in an organization has unit permissions settings. It can have members and repositories scope.
|
||||
|
||||
- A team could access all the repositories in this organization or special repositories.
|
||||
- A team could also be allowed to create new repositories or not.
|
||||
|
||||
The General team can be created to do the operations allowed by their permissions. One member could join multiple teams.
|
||||
67
docs/content/usage/permissions.zh-cn.md
Normal file
67
docs/content/usage/permissions.zh-cn.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "权限"
|
||||
slug: "permissions"
|
||||
sidebar_position: 14
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/permissions
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "权限"
|
||||
sidebar_position: 14
|
||||
identifier: "permissions"
|
||||
---
|
||||
|
||||
# 权限
|
||||
|
||||
Gitea 支持对仓库进行权限管理，这样您就可以为不同的人员提供不同的访问权限。首先，我们需要了解 `单元（Unit）`。
|
||||
|
||||
## 单元（Unit）
|
||||
|
||||
在 Gitea 中，我们将仓库的子模块称为 `单元（Unit）`。现在我们有以下几个单元。
|
||||
|
||||
| 名称 | 描述 | 权限 |
|
||||
| ----------------- | --------------------------------------------------- | ------------ |
|
||||
| 代码 | 访问源代码、文件、提交和分支。 | 读取 写入 |
|
||||
| 工单 | 组织缺陷报告、任务和里程碑。 | 读取 写入 |
|
||||
| 合并请求 | 启用合并请求和代码审核。 | 读取 写入 |
|
||||
| 发布 | 跟踪项目版本和下载。 | 读取 写入 |
|
||||
| 维基 | 与协作者编写和共享文档。 | 读取 写入 |
|
||||
| 外部维基 | 链接到外部维基。 | 读取 |
|
||||
| 外部工单跟踪器 | 链接到外部工单跟踪器。 | 读取 |
|
||||
| 项目 | 模板仓库的 URL。 | 读取 写入 |
|
||||
| 设置 | 管理仓库。 | 管理员 |
|
||||
|
||||
通过不同的权限，用户可以在这些单元上执行不同的操作。
|
||||
|
||||
| 名称 | 读取 | 写入 | 管理员 |
|
||||
| ----------------- | -------------------------------------------------- | ------------------------------ | ------------------------- |
|
||||
| 代码 | 查看代码树、文件、提交、分支等。 | 推送代码。 | - |
|
||||
| 工单 | 查看工单并创建新工单。 | 添加标签、分配、关闭工单。 | - |
|
||||
| 合并请求 | 查看合并请求并创建新合并请求。 | 添加标签、分配、关闭合并请求。 | - |
|
||||
| 发布 | 查看发布和下载文件。 | 创建/编辑发布。 | - |
|
||||
| 维基 | 查看维基页面。克隆维基仓库。 | 创建/编辑维基页面，推送更改。 | - |
|
||||
| 外部维基 | 链接到外部维基。 | - | - |
|
||||
| 外部工单跟踪器 | 链接到外部工单跟踪器。 | - | - |
|
||||
| 项目 | 查看面板。 | 在面板之间移动工单。 | - |
|
||||
| 设置 | - | - | 管理仓库 |
|
||||
|
||||
个人仓库和组织仓库之间的权限存在一些差异。
|
||||
|
||||
## 个人仓库
|
||||
|
||||
对于个人仓库，创建者是仓库的唯一所有者，对于该仓库的任何更改或删除没有限制。仓库所有者可以添加协作者来帮助维护仓库。协作者可以拥有 `读取（Read）`、`写入（Write）` 和 `管理员（Admin）` 权限。
|
||||
|
||||
## 组织仓库
|
||||
|
||||
与个人仓库不同，组织仓库的所有者是组织的所有者团队。
|
||||
|
||||
### 团队
|
||||
|
||||
组织中的一个团队具有单元权限设置。它可以拥有成员和仓库的范围。团队可以访问组织中的所有仓库或者由所有者团队授权访问的特定仓库。团队也可以被允许创建新的仓库。
|
||||
|
||||
所有者团队（Owners）将在创建组织时自动创建，并且创建者将成为所有者团队的第一个成员。
|
||||
组织的每个成员必须至少属于一个团队。所有者团队不能被删除，只有所有者团队的成员可以创建新的团队。可以创建一个管理员团队来管理某些仓库，该团队的成员可以对这些仓库进行任何操作。可以由所有者团队创建一个生成团队来执行其权限允许的操作。
|
||||
20
docs/content/usage/profile-readme.zh-cn.md
Normal file
20
docs/content/usage/profile-readme.zh-cn.md
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "个人资料 README"
|
||||
slug: "profile-readme"
|
||||
sidebar_position: 12
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "个人资料 README"
|
||||
sidebar_position: 12
|
||||
identifier: "profile-readme"
|
||||
---
|
||||
|
||||
# 个人资料 README
|
||||
|
||||
要在您的 Gitea 个人资料页面显示一个 Markdown 文件，只需创建一个名为 ".profile" 的仓库，并编辑其中的 README.md 文件。Gitea 将自动获取该文件并在您的仓库上方显示。
|
||||
|
||||
注意：您可以将此仓库设为私有。这样可以隐藏您的源文件，使其对公众不可见，并允许您将某些文件设为私有。但是，README.md 文件将是您个人资料上唯一存在的文件。如果您希望完全私有化 .profile 仓库，则需删除或重命名 README.md 文件。
|
||||
53
docs/content/usage/protected-tags.en-us.md
Normal file
53
docs/content/usage/protected-tags.en-us.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
date: "2021-05-14T00:00:00-00:00"
|
||||
title: "Protected tags"
|
||||
slug: "protected-tags"
|
||||
sidebar_position: 45
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Protected tags"
|
||||
sidebar_position: 45
|
||||
identifier: "protected-tags"
|
||||
---
|
||||
|
||||
# Protected tags
|
||||
|
||||
Protected tags allow control over who has permission to create or update Git tags. Each rule allows you to match either an individual tag name, or use an appropriate pattern to control multiple tags at once.
|
||||
|
||||
## Setting up protected tags
|
||||
|
||||
To protect a tag, you need to follow these steps:
|
||||
|
||||
1. Go to the repository’s **Settings** > **Tags** page.
|
||||
1. Type a pattern to match a name. You can use a single name, a [glob pattern](https://pkg.go.dev/github.com/gobwas/glob#Compile) or a regular expression.
|
||||
1. Choose the allowed users and/or teams. If you leave these fields empty no one is allowed to create or modify this tag.
|
||||
1. Select **Save** to save the configuration.
|
||||
|
||||
## Pattern protected tags
|
||||
|
||||
The pattern uses [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) or regular expressions to match a tag name. For regular expressions you need to enclose the pattern in slashes.
|
||||
|
||||
Examples:
|
||||
|
||||
| Type | Pattern Protected Tag | Possible Matching Tags |
|
||||
| ----- | ------------------------ | --------------------------------------- |
|
||||
| Glob | `v*` | `v`, `v-1`, `version2` |
|
||||
| Glob | `v[0-9]` | `v0`, `v1` up to `v9` |
|
||||
| Glob | `*-release` | `2.1-release`, `final-release` |
|
||||
| Glob | `gitea` | only `gitea` |
|
||||
| Glob | `*gitea*` | `gitea`, `2.1-gitea`, `1_gitea-release` |
|
||||
| Glob | `{v,rel}-*` | `v-`, `v-1`, `v-final`, `rel-`, `rel-x` |
|
||||
| Glob | `*` | matches all possible tag names |
|
||||
| Regex | `/\Av/` | `v`, `v-1`, `version2` |
|
||||
| Regex | `/\Av[0-9]\z/` | `v0`, `v1` up to `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/` | only `gitea` |
|
||||
| Regex | `/^gitea$/` | only `gitea` |
|
||||
| Regex | `/\A(v\|rel)-/` | `v-`, `v-1`, `v-final`, `rel-`, `rel-x` |
|
||||
| Regex | `/.+/` | matches all possible tag names |
|
||||
55
docs/content/usage/protected-tags.zh-cn.md
Normal file
55
docs/content/usage/protected-tags.zh-cn.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "受保护的标签"
|
||||
slug: "protected-tags"
|
||||
sidebar_position: 45
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/protected-tags
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "受保护的标签"
|
||||
sidebar_position: 45
|
||||
identifier: "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 | `/.+/` | 匹配所有可能的标签名称 |
|
||||
31
docs/content/usage/pull-request.en-us.md
Normal file
31
docs/content/usage/pull-request.en-us.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
date: "2018-06-01T19:00:00+02:00"
|
||||
title: "Pull Request"
|
||||
slug: "pull-request"
|
||||
sidebar_position: 13
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Pull Request"
|
||||
sidebar_position: 13
|
||||
identifier: "pull-request"
|
||||
---
|
||||
|
||||
# Pull Request
|
||||
|
||||
## "Work In Progress" pull requests
|
||||
|
||||
Marking a pull request as being a work in progress will prevent that pull request from being accidentally merged. To mark a pull request as being a work in progress, you must prefix its title by `WIP:` or `[WIP]` (case insensitive). Those values are configurable in your `app.ini` file :
|
||||
|
||||
```ini
|
||||
[repository.pull-request]
|
||||
WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
|
||||
```
|
||||
|
||||
The first value of the list will be used in helpers.
|
||||
|
||||
## Pull Request Templates
|
||||
|
||||
You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates).
|
||||
31
docs/content/usage/pull-request.zh-cn.md
Normal file
31
docs/content/usage/pull-request.zh-cn.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
date: "2018-06-01T19:00:00+02:00"
|
||||
title: "合并请求"
|
||||
slug: "pull-request"
|
||||
sidebar_position: 13
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "合并请求"
|
||||
sidebar_position: 13
|
||||
identifier: "pull-request"
|
||||
---
|
||||
|
||||
# 合并请求
|
||||
|
||||
## 在合并请求中使用“Work In Progress”标记
|
||||
|
||||
您可以通过在一个进行中的 pull request 的标题上添加前缀 `WIP:` 或者 `[WIP]`（此处大小写敏感）来防止它被意外合并，具体的前缀设置可以在配置文件 `app.ini` 中找到：
|
||||
|
||||
```
|
||||
[repository.pull-request]
|
||||
WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
|
||||
```
|
||||
|
||||
列表的第一个值将用于 helpers 程序。
|
||||
|
||||
## 合并请求模板
|
||||
|
||||
有关合并请求模板的更多信息请您移步 : [工单和合并请求模板](issue-pull-request-templates)
|
||||
32
docs/content/usage/pull-request.zh-tw.md
Normal file
32
docs/content/usage/pull-request.zh-tw.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
date: "2018-06-01T19:00:00+02:00"
|
||||
title: "使用: 合併請求"
|
||||
slug: "pull-request"
|
||||
sidebar_position: 13
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "合併請求"
|
||||
sidebar_position: 13
|
||||
identifier: "pull-request"
|
||||
---
|
||||
|
||||
# 合併請求
|
||||
|
||||
## 「還在進行中（WIP）」的合併請求
|
||||
|
||||
將合併請求標記為還在進行中（Work In Progress, WIP）可避免意外地被合併。
|
||||
要將合併請求標記為還在進行中請在標題中使用 `WIP:` 或 `[WIP]` 前綴（不分大小寫）。這些值可在您的 `app.ini` 中設定：
|
||||
|
||||
```ini
|
||||
[repository.pull-request]
|
||||
WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
|
||||
```
|
||||
|
||||
網頁提示會使用第一個值作為範例。
|
||||
|
||||
## 合併請求範本
|
||||
|
||||
您可以在[問題與合併請求範本](issue-pull-request-templates)找到更多關於合併請求範本的資訊。
|
||||
67
docs/content/usage/push.en-us.md
Normal file
67
docs/content/usage/push.en-us.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
date: "2020-07-06T16:00:00+02:00"
|
||||
title: "Push"
|
||||
slug: "push"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Push"
|
||||
sidebar_position: 15
|
||||
identifier: "push"
|
||||
---
|
||||
|
||||
There are some additional features when pushing commits to Gitea server.
|
||||
|
||||
# Open PR through Push
|
||||
|
||||
When you push commits to a non-default branch for the first time,
|
||||
you will receive a link you can click on to visit the compare page of your branch compared to your main branch.
|
||||
From there, it's easy to create a pull request, even if you want to target another branch.
|
||||
|
||||
|
||||
|
||||
# Push Options
|
||||
|
||||
In Gitea `1.13`, support for some [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)
|
||||
were added.
|
||||
|
||||
## Supported Options
|
||||
|
||||
- `repo.private` (true|false) - Change the repository's visibility.
|
||||
|
||||
This is particularly useful when combined with push-to-create.
|
||||
|
||||
- `repo.template` (true|false) - Change whether the repository is a template.
|
||||
|
||||
Example of changing a repository's visibility to public:
|
||||
|
||||
```shell
|
||||
git push -o repo.private=false -u origin main
|
||||
```
|
||||
|
||||
# Push To Create
|
||||
|
||||
Push to create is a feature that allows you to push to a repository that does not exist yet in Gitea. This is useful for automation and for allowing users to create repositories without having to go through the web interface. This feature is disabled by default.
|
||||
|
||||
## Enabling Push To Create
|
||||
|
||||
In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](administration/config-cheat-sheet.md#repository-repository).
|
||||
|
||||
## Using Push To Create
|
||||
|
||||
Assuming you have a git repository in the current directory, you can push to a repository that does not exist yet in Gitea by running the following command:
|
||||
|
||||
```shell
|
||||
# Add the remote you want to push to
|
||||
git remote add origin git@{domain}:{username}/{repo name that does not exist yet}.git
|
||||
|
||||
# push to the remote
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
This assumes you are using an SSH remote, but you can also use HTTPS remotes as well.
|
||||
|
||||
Push-to-create will default to the visibility defined by `DEFAULT_PUSH_CREATE_PRIVATE` in `app.ini`.
|
||||
68
docs/content/usage/push.zh-cn.md
Normal file
68
docs/content/usage/push.zh-cn.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "推送"
|
||||
slug: "push"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/push-to-create
|
||||
- /zh-cn/push-options
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "推送"
|
||||
sidebar_position: 15
|
||||
identifier: "push"
|
||||
---
|
||||
|
||||
在将提交推送到 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#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`。
|
||||
65
docs/content/usage/push.zh-tw.md
Normal file
65
docs/content/usage/push.zh-tw.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
date: "2020-07-06T16:00:00+02:00"
|
||||
title: "使用: Push"
|
||||
slug: "push"
|
||||
sidebar_position: 15
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Push"
|
||||
sidebar_position: 15
|
||||
identifier: "push"
|
||||
---
|
||||
|
||||
There are some additional features when pushing commits to Gitea server.
|
||||
|
||||
# Push Merge Hint
|
||||
|
||||
When you pushing commits to a non-default branch, you will get an information from
|
||||
Gitea which is a link, you can click the link and go to a compare page. It's a quick
|
||||
way to create a pull request or a code review yourself in the Gitea UI.
|
||||
|
||||
|
||||
|
||||
# Push Options
|
||||
|
||||
Gitea 從 `1.13` 版開始支援某些 [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)
|
||||
。
|
||||
|
||||
## 支援的 Options
|
||||
|
||||
- `repo.private` (true|false) - 修改儲存庫的可見性。
|
||||
|
||||
與 push-to-create 一起使用時特別有用。
|
||||
|
||||
- `repo.template` (true|false) - 修改儲存庫是否為範本儲存庫。
|
||||
|
||||
以下範例修改儲存庫的可見性為公開：
|
||||
|
||||
```shell
|
||||
git push -o repo.private=false -u origin main
|
||||
```
|
||||
|
||||
# Push To Create
|
||||
|
||||
Push to create is a feature that allows you to push to a repository that does not exist yet in Gitea. This is useful for automation and for allowing users to create repositories without having to go through the web interface. This feature is disabled by default.
|
||||
|
||||
## Enabling Push To Create
|
||||
|
||||
In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](administration/config-cheat-sheet.md#repository-repository).
|
||||
|
||||
## Using Push To Create
|
||||
|
||||
Assuming you have a git repository in the current directory, you can push to a repository that does not exist yet in Gitea by running the following command:
|
||||
|
||||
```shell
|
||||
# Add the remote you want to push to
|
||||
git remote add origin git@{domain}:{username}/{repo name that does not exist yet}.git
|
||||
|
||||
# push to the remote
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
This assumes you are using an SSH remote, but you can also use HTTPS remotes as well.
|
||||
88
docs/content/usage/repo-mirror.en-us.md
Normal file
88
docs/content/usage/repo-mirror.en-us.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
date: "2021-05-13T00:00:00-00:00"
|
||||
title: "Repository Mirror"
|
||||
slug: "repo-mirror"
|
||||
sidebar_position: 45
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Repository Mirror"
|
||||
sidebar_position: 45
|
||||
identifier: "repo-mirror"
|
||||
---
|
||||
|
||||
# Repository Mirror
|
||||
|
||||
Repository mirroring allows for the mirroring of repositories to and from external sources. You can use it to mirror branches, tags, and commits between repositories.
|
||||
|
||||
## Use cases
|
||||
|
||||
The following are some possible use cases for repository mirroring:
|
||||
|
||||
- You migrated to Gitea but still need to keep your project in another source. In that case, you can simply set it up to mirror to Gitea (pull) and all the essential history of commits, tags, and branches are available in your Gitea instance.
|
||||
- You have old projects in another source that you don’t use actively anymore, but don’t want to remove for archiving purposes. In that case, you can create a push mirror so that your active Gitea repository can push its changes to the old location.
|
||||
|
||||
## Pulling from a remote repository
|
||||
|
||||
For an existing remote repository, you can set up pull mirroring as follows:
|
||||
|
||||
1. Select **New Migration** in the **Create...** menu on the top right.
|
||||
2. Select the remote repository service.
|
||||
3. Enter a repository URL.
|
||||
4. If the repository needs authentication fill in your authentication information.
|
||||
5. Check the box **This repository will be a mirror**.
|
||||
6. Select **Migrate repository** to save the configuration.
|
||||
|
||||
The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings.
|
||||
|
||||
:exclamation::exclamation: **NOTE:** You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation:
|
||||
|
||||
## Pushing to a remote repository
|
||||
|
||||
For an existing repository, you can set up push mirroring as follows:
|
||||
|
||||
1. In your repository, go to **Settings** > **Repository**, and then the **Mirror Settings** section.
|
||||
2. Enter a repository URL.
|
||||
3. If the repository needs authentication expand the **Authorization** section and fill in your authentication information. Note that the requested **password** can also be your access token.
|
||||
4. Select **Add Push Mirror** to save the configuration.
|
||||
|
||||
The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it.
|
||||
|
||||
:exclamation::exclamation: **NOTE:** This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation:
|
||||
|
||||
### Setting up a push mirror from Gitea to GitHub
|
||||
|
||||
To set up a mirror from Gitea to GitHub, you need to follow these steps:
|
||||
|
||||
1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the *public_repo* box checked.
|
||||
2. Create a repository with that name on GitHub. Unlike Gitea, GitHub does not support creating repositories by pushing to the remote. You can also use an existing remote repo if it has the same commit history as your Gitea repo.
|
||||
3. In the settings of your Gitea repo, fill in the **Git Remote Repository URL**: `https://github.com/<your_github_group>/<your_github_project>.git`.
|
||||
4. Fill in the **Authorization** fields with your GitHub username and the personal access token as **Password**.
|
||||
5. (Optional, available on Gitea 1.18+) Select `Sync when new commits are pushed` so that the mirror will be updated as well as soon as there are changes. You can also disable the periodic sync if you like.
|
||||
6. Select **Add Push Mirror** to save the configuration.
|
||||
|
||||
The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
|
||||
|
||||
### Setting up a push mirror from Gitea to GitLab
|
||||
|
||||
To set up a mirror from Gitea to GitLab, you need to follow these steps:
|
||||
|
||||
1. Create a [GitLab personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with *write_repository* scope.
|
||||
2. Fill in the **Git Remote Repository URL**: `https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`.
|
||||
3. Fill in the **Authorization** fields with `oauth2` as **Username** and your GitLab personal access token as **Password**.
|
||||
4. Select **Add Push Mirror** to save the configuration.
|
||||
|
||||
The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
|
||||
|
||||
### Setting up a push mirror from Gitea to Bitbucket
|
||||
|
||||
To set up a mirror from Gitea to Bitbucket, you need to follow these steps:
|
||||
|
||||
1. Create a [Bitbucket app password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) with the *Repository Write* box checked.
|
||||
2. Fill in the **Git Remote Repository URL**: `https://bitbucket.org/<your_bitbucket_group_or_name>/<your_bitbucket_project>.git`.
|
||||
3. Fill in the **Authorization** fields with your Bitbucket username and the app password as **Password**.
|
||||
4. Select **Add Push Mirror** to save the configuration.
|
||||
|
||||
The repository pushes shortly thereafter. To force a push, select the **Synchronize Now** button.
|
||||
90
docs/content/usage/repo-mirror.zh-cn.md
Normal file
90
docs/content/usage/repo-mirror.zh-cn.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "仓库镜像"
|
||||
slug: "repo-mirror"
|
||||
sidebar_position: 45
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/repo-mirror
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "仓库镜像"
|
||||
sidebar_position: 45
|
||||
identifier: "repo-mirror"
|
||||
---
|
||||
|
||||
# 仓库镜像
|
||||
|
||||
仓库镜像允许将仓库与外部源之间进行镜像。您可以使用它在仓库之间镜像分支、标签和提交。
|
||||
|
||||
## 使用场景
|
||||
|
||||
以下是一些仓库镜像的可能使用场景：
|
||||
|
||||
- 您迁移到了 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/<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. 选择**添加推送镜像**以保存配置。
|
||||
|
||||
仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。
|
||||
37
docs/content/usage/secrets.en-us.md
Normal file
37
docs/content/usage/secrets.en-us.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
date: "2022-12-19T21:26:00+08:00"
|
||||
title: "Secrets"
|
||||
slug: "usage/secrets"
|
||||
sidebar_position: 50
|
||||
draft: false
|
||||
toc: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Secrets"
|
||||
sidebar_position: 50
|
||||
identifier: "usage-secrets"
|
||||
---
|
||||
|
||||
# Secrets
|
||||
|
||||
Secrets allow you to store sensitive information in your user, organization or repository.
|
||||
Secrets are available on Gitea 1.19+.
|
||||
|
||||
# Naming your secrets
|
||||
|
||||
The following rules apply to secret names:
|
||||
|
||||
- Secret names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
|
||||
|
||||
- Secret names must not start with the `GITHUB_` and `GITEA_` prefix.
|
||||
|
||||
- Secret names must not start with a number.
|
||||
|
||||
- Secret names are not case-sensitive.
|
||||
|
||||
- Secret names must be unique at the level they are created at.
|
||||
|
||||
For example, a secret created at the repository level must have a unique name in that repository, and a secret created at the organization level must have a unique name at that level.
|
||||
|
||||
If a secret with the same name exists at multiple levels, the secret at the lowest level takes precedence. For example, if an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence.
|
||||
39
docs/content/usage/secrets.zh-cn.md
Normal file
39
docs/content/usage/secrets.zh-cn.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "密钥管理"
|
||||
slug: "secrets"
|
||||
sidebar_position: 50
|
||||
draft: false
|
||||
toc: false
|
||||
aliases:
|
||||
- /zh-cn/secrets
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "密钥管理"
|
||||
sidebar_position: 50
|
||||
identifier: "usage-secrets"
|
||||
---
|
||||
|
||||
# 密钥管理
|
||||
|
||||
密钥管理允许您在用户、组织或仓库中存储敏感信息。
|
||||
密钥管理在 Gitea 1.19+ 版本中可用。
|
||||
|
||||
# 设置密钥名称
|
||||
|
||||
以下规则适用于密钥名称：
|
||||
|
||||
- 密钥名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
|
||||
|
||||
- 密钥名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
|
||||
|
||||
- 密钥名称不能以数字开头。
|
||||
|
||||
- 密钥名称不区分大小写。
|
||||
|
||||
- 密钥名称在创建它们的级别上必须是唯一的。
|
||||
|
||||
例如，对于在仓库级别创建的密钥，它在该仓库中必须具有唯一的名称；对于在组织级别创建的密钥，它在该级别上必须具有唯一的名称。
|
||||
|
||||
如果在多个级别上存在具有相同名称的密钥，则最低级别的密钥优先生效。例如，如果组织级别的密钥与仓库级别的密钥具有相同的名称，则仓库级别的密钥将优先生效。
|
||||
81
docs/content/usage/template-repositories.en-us.md
Normal file
81
docs/content/usage/template-repositories.en-us.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
date: "2019-11-28:00:00+02:00"
|
||||
title: "Template Repositories"
|
||||
slug: "template-repositories"
|
||||
sidebar_position: 14
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Template Repositories"
|
||||
sidebar_position: 14
|
||||
identifier: "template-repositories"
|
||||
---
|
||||
|
||||
# Template Repositories
|
||||
|
||||
Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
|
||||
|
||||
To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
|
||||
|
||||
Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
|
||||
|
||||
## Example `.gitea/template` file
|
||||
|
||||
All paths are relative to the base of the repository
|
||||
|
||||
```gitignore
|
||||
# All .go files, anywhere in the repository
|
||||
**.go
|
||||
|
||||
# All text files in the text directory
|
||||
text/*.txt
|
||||
|
||||
# A specific file
|
||||
a/b/c/d.json
|
||||
|
||||
# Batch files in both upper or lower case can be matched
|
||||
**.[bB][aA][tT]
|
||||
```
|
||||
|
||||
**NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template.
|
||||
|
||||
## Variable Expansion
|
||||
|
||||
In any file matched by the above globs, certain variables will be expanded.
|
||||
|
||||
All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
|
||||
|
||||
| Variable | Expands To | Transformable |
|
||||
| -------------------- | --------------------------------------------------- | ------------- |
|
||||
| REPO_NAME | The name of the generated repository | ✓ |
|
||||
| TEMPLATE_NAME | The name of the template repository | ✓ |
|
||||
| REPO_DESCRIPTION | The description of the generated repository | ✘ |
|
||||
| TEMPLATE_DESCRIPTION | The description of the template repository | ✘ |
|
||||
| REPO_OWNER | The owner of the generated repository | ✓ |
|
||||
| TEMPLATE_OWNER | The owner of the template repository | ✓ |
|
||||
| REPO_LINK | The URL to the generated repository | ✘ |
|
||||
| TEMPLATE_LINK | The URL to the template repository | ✘ |
|
||||
| REPO_HTTPS_URL | The HTTP(S) clone link for the generated repository | ✘ |
|
||||
| TEMPLATE_HTTPS_URL | The HTTP(S) clone link for the template repository | ✘ |
|
||||
| REPO_SSH_URL | The SSH clone link for the generated repository | ✘ |
|
||||
| TEMPLATE_SSH_URL | The SSH clone link for the template repository | ✘ |
|
||||
|
||||
## Transformers :robot:
|
||||
|
||||
Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
|
||||
|
||||
For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}`
|
||||
|
||||
Feeding `go-sdk` to the available transformers yields...
|
||||
|
||||
| Transformer | Effect |
|
||||
| ----------- | ------ |
|
||||
| SNAKE | go_sdk |
|
||||
| KEBAB | go-sdk |
|
||||
| CAMEL | goSdk |
|
||||
| PASCAL | GoSdk |
|
||||
| LOWER | go-sdk |
|
||||
| UPPER | GO-SDK |
|
||||
| TITLE | Go-Sdk |
|
||||
83
docs/content/usage/template-repositories.zh-cn.md
Normal file
83
docs/content/usage/template-repositories.zh-cn.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
title: "模板仓库"
|
||||
slug: "template-repositories"
|
||||
sidebar_position: 14
|
||||
toc: false
|
||||
draft: false
|
||||
aliases:
|
||||
- /zh-cn/template-repositories
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "模板仓库"
|
||||
sidebar_position: 14
|
||||
identifier: "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 |
|
||||
194
docs/content/usage/webhooks.en-us.md
Normal file
194
docs/content/usage/webhooks.en-us.md
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
title: "Webhooks"
|
||||
slug: "webhooks"
|
||||
sidebar_position: 30
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Webhooks"
|
||||
sidebar_position: 30
|
||||
identifier: "webhooks"
|
||||
---
|
||||
|
||||
# Webhooks
|
||||
|
||||
Gitea supports webhooks for repository events. This can be configured in the settings
|
||||
page `/:username/:reponame/settings/hooks` by a repository admin. Webhooks can also be configured on a per-organization and whole system basis.
|
||||
All event pushes are POST requests. The methods currently supported are:
|
||||
|
||||
- Gitea (can also be a GET request)
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### Event information
|
||||
|
||||
**WARNING**: The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755
|
||||
|
||||
The following is an example of event information that will be sent by Gitea to
|
||||
a 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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
This is an example of how to use webhooks to run a php script upon push requests to the repository.
|
||||
In your repository Settings, under Webhooks, Setup a Gitea webhook as follows:
|
||||
|
||||
- Target URL: http://mydomain.com/webhook.php
|
||||
- HTTP Method: POST
|
||||
- POST Content Type: application/json
|
||||
- Secret: 123
|
||||
- Trigger On: Push Events
|
||||
- Active: Checked
|
||||
|
||||
Now on your server create the php file webhook.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
|
||||
```
|
||||
|
||||
There is a Test Delivery button in the webhook settings that allows to test the configuration as well as a list of the most Recent Deliveries.
|
||||
|
||||
### Authorization header
|
||||
|
||||
**With 1.19**, Gitea hooks can be configured to send an [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) to the webhook target.
|
||||
192
docs/content/usage/webhooks.zh-cn.md
Normal file
192
docs/content/usage/webhooks.zh-cn.md
Normal file
@@ -0,0 +1,192 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
title: "Webhooks"
|
||||
slug: "webhooks"
|
||||
sidebar_position: 30
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Webhooks"
|
||||
sidebar_position: 30
|
||||
identifier: "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的事件信息示例：
|
||||
|
||||
```
|
||||
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
|
||||
|
||||
$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)。
|
||||
188
docs/content/usage/webhooks.zh-tw.md
Normal file
188
docs/content/usage/webhooks.zh-tw.md
Normal file
@@ -0,0 +1,188 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
title: "Webhook"
|
||||
slug: "webhooks"
|
||||
sidebar_position: 30
|
||||
toc: false
|
||||
draft: false
|
||||
menu:
|
||||
sidebar:
|
||||
parent: "usage"
|
||||
name: "Webhook"
|
||||
sidebar_position: 30
|
||||
identifier: "webhooks"
|
||||
---
|
||||
|
||||
# Webhook
|
||||
|
||||
Gitea 的儲存庫事件支援 web hook。這可以有儲存庫管理員在設定頁 `/:username/:reponame/settings/hooks` 中調整。Webhook 也可以按照組織調整或按照全系統調整。
|
||||
所有的事件推送都是 POST 請求。此方法目前被下列服務支援：
|
||||
|
||||
- Gitea (也可以是 GET 請求)
|
||||
- Gogs
|
||||
- Slack
|
||||
- Discord
|
||||
- Dingtalk
|
||||
- Telegram
|
||||
- Microsoft Teams
|
||||
- Feishu
|
||||
- Wechatwork
|
||||
- Packagist
|
||||
|
||||
### 事件資訊
|
||||
|
||||
**警告**： Payload 中的 `secret` 欄位已經在 Gitea 1.13.0 棄用，並且將在 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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 範例
|
||||
|
||||
此範例示範在發生推送事件時，如何使用 webhook 觸發 php 程式。
|
||||
使用下列參數在您的儲存庫設定 Webhook 中建立一個 Gitea webhook：
|
||||
|
||||
- 目標 URL： http://mydomain.com/webhook.php
|
||||
- HTTP 請求方法：POST
|
||||
- POST Content Type：application/json
|
||||
- Secret：123
|
||||
- 觸發條件：推送事件
|
||||
- 啟用：勾選
|
||||
|
||||
現在請到您的伺服器上建立 webhook.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 設定中有一個傳送測試資料按鈕，它可讓你測試您的設定並將結果顯示於最近傳送記錄。
|
||||
Reference in New Issue
Block a user