diff options
| author | John Olheiser <john.olheiser@gmail.com> | 2023-07-25 23:53:13 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-07-26 04:53:13 +0000 |
| commit | bd4c7ce578956d9839309b16753bd5505b63b2e3 (patch) | |
| tree | 1d3074ef542cee11707bc4985ce54dc40facb9b6 /docs/content/doc/usage | |
| parent | 5dc37ef97a30628027a723ee944225a33a6511f8 (diff) | |
| download | gitea-bd4c7ce578956d9839309b16753bd5505b63b2e3.tar.gz gitea-bd4c7ce578956d9839309b16753bd5505b63b2e3.zip | |
Docusaurus-ify (#26051)
This PR cleans up the docs in a way to make them simpler to ingest by
our [docs repo](https://gitea.com/gitea/gitea-docusaurus).
1. It includes all of the sed invocations our ingestion did, removing
the need to do it at build time.
2. It replaces the shortcode variable replacement method with
`@variable@` style, simply for easier sed invocations when required.
3. It removes unused files and moves the docs up a level as cleanup.
---------
Signed-off-by: jolheiser <john.olheiser@gmail.com>
Diffstat (limited to 'docs/content/doc/usage')
101 files changed, 0 insertions, 10743 deletions
diff --git a/docs/content/doc/usage/_index.en-us.md b/docs/content/doc/usage/_index.en-us.md deleted file mode 100644 index e69de29bb2..0000000000 --- a/docs/content/doc/usage/_index.en-us.md +++ /dev/null diff --git a/docs/content/doc/usage/_index.zh-cn.md b/docs/content/doc/usage/_index.zh-cn.md deleted file mode 100644 index e69de29bb2..0000000000 --- a/docs/content/doc/usage/_index.zh-cn.md +++ /dev/null diff --git a/docs/content/doc/usage/_index.zh-tw.md b/docs/content/doc/usage/_index.zh-tw.md deleted file mode 100644 index e69de29bb2..0000000000 --- a/docs/content/doc/usage/_index.zh-tw.md +++ /dev/null diff --git a/docs/content/doc/usage/actions/act-runner.en-us.md b/docs/content/doc/usage/actions/act-runner.en-us.md deleted file mode 100644 index 1f4475508f..0000000000 --- a/docs/content/doc/usage/actions/act-runner.en-us.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -date: "2023-04-27T15:00:00+08:00" -title: "Act Runner" -slug: "act-runner" -weight: 20 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "Act Runner" - weight: 20 - identifier: "actions-runner" ---- - -# Act Runner - -This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner of Gitea Actions. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -It is recommended to run jobs in a docker container, so you need to install docker first. -And make sure that the docker daemon is running. - -Other OCI container engines which are compatible with Docker's API should also work, but are untested. - -However, if you are sure that you want to run jobs directly on the host only, then docker is not required. - -## Installation - -There are multiple ways to install the act runner. - -### Download the binary - -You can download the binary from the [release page](https://gitea.com/gitea/act_runner/releases). -However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/act_runner/). - -When you download the binary, please make sure that you have downloaded the correct one for your platform. -You can check it by running the following command: - -```bash -chmod +x act_runner -./act_runner --version -``` - -If you see the version information, it means that you have downloaded the correct binary. - -### Use the docker image - -You can use the docker image from the [docker hub](https://hub.docker.com/r/gitea/act_runner/tags). -Just like the binary, you can use the latest nightly build by using the `nightly` tag, while the `latest` tag is the latest stable release. - -```bash -docker pull gitea/act_runner:latest # for the latest stable release -docker pull gitea/act_runner:nightly # for the latest nightly build -``` - -## Configuration - -Configuration is done via a configuration file. It is optional, and the default configuration will be used when no configuration file is specified. - -You can generate a configuration file by running the following command: - -```bash -./act_runner generate-config -``` - -The default configuration is safe to use without any modification, so you can just use it directly. - -```bash -./act_runner generate-config > config.yaml -./act_runner --config config.yaml [command] -``` - -You could also generate config file with docker: - -```bash -docker run --entrypoint="" --rm -it gitea/act_runner:latest act_runner generate-config > config.yaml -``` - -When you are using the docker image, you can specify the configuration file by using the `CONFIG_FILE` environment variable. Make sure that the file is mounted into the container as a volume: - -```bash -docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ... -``` - -You may notice the commands above are both incomplete, because it is not the time to run the act runner yet. -Before running the act runner, we need to register it to your Gitea instance first. - -## Registration - -Registration is required before running the act runner, because the runner needs to know where to get jobs from. -And it is also important to Gitea instance to identify the runner. - -### Runner levels - -You can register a runner in different levels, it can be: - -- Instance level: The runner will run jobs for all repositories in the instance. -- Organization level: The runner will run jobs for all repositories in the organization. -- Repository level: The runner will run jobs for the repository it belongs to. - -Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this. - -### Obtain a registration token - -The level of the runner determines where to obtain the registration token. - -- Instance level: The admin settings page, like `<your_gitea.com>/admin/actions/runners`. -- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`. -- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`. - -If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled. - -The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`. - -### Register the runner - -The act runner can be registered by running the following command: - -```bash -./act_runner register -``` - -Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section. - -```bash -./act_runner --config config.yaml register -``` - -You will be asked to input the registration information step by step. Includes: - -- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`. -- The registration token. -- The runner name, which is optional. If you leave it blank, the hostname will be used. -- The runner labels, which is optional. If you leave it blank, the default labels will be used. - -You may be confused about the runner labels, which will be explained later. - -If you want to register the runner in a non-interactive way, you can use arguments to do it. - -```bash -./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels> -``` - -When you have registered the runner, you can find a new file named `.runner` in the current directory. -This file stores the registration information. -Please do not edit it manually. -If this file is missing or corrupted, you can simply remove it and register again. - -If you want to store the registration information in another place, you can specify it in the configuration file, -and don't forget to specify the `--config` option. - -### Register the runner with docker - -If you are using the docker image, behaviour will be slightly different. Registration and running are combined into one step in this case, so you need to specify the registration information when running the act runner. - -```bash -docker run \ - -v $(pwd)/config.yaml:/config.yaml \ - -v $(pwd)/data:/data \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -e CONFIG_FILE=/config.yaml \ - -e GITEA_INSTANCE_URL=<instance_url> \ - -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \ - -e GITEA_RUNNER_NAME=<runner_name> \ - -e GITEA_RUNNER_LABELS=<runner_labels> \ - --name my_runner \ - -d gitea/act_runner:nightly -``` - -You may notice that we have mounted the `/var/run/docker.sock` into the container. -It is because the act runner will run jobs in docker containers, so it needs to communicate with the docker daemon. -As mentioned, you can remove it if you want to run jobs in the host directly. -To be clear, the "host" actually means the container which is running the act runner now, instead of the host machine. - -### Set up the runner using docker compose - -You could also set up the runner using the following `docker-compose.yml`: - -```yml -version: "3.8" -services: - runner: - image: gitea/act_runner:nightly - environment: - CONFIG_FILE: /config.yaml - GITEA_INSTANCE_URL: "${INSTANCE_URL}" - GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}" - GITEA_RUNNER_NAME: "${RUNNER_NAME}" - GITEA_RUNNER_LABELS: "${RUNNER_LABELS}" - volumes: - - ./config.yaml:/config.yaml - - ./data:/data - - /var/run/docker.sock:/var/run/docker.sock -``` - -### Configuring cache when starting a Runner using docker image - -If you do not intend to use `actions/cache` in workflow, you can ignore this section. - -If you use `actions/cache` without any additional configuration, it will return the following error: -> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT - -The error occurs because the runner container and job container are on different networks, so the job container cannot access the runner container. - -Therefore, it is essential to configure the cache action to ensure its proper functioning. Follow these steps: - -- 1.Obtain the LAN IP address of the host machine where the runner container is running. -- 2.Find an available port number on the host machine where the runner container is running. -- 3.Configure the following settings in the configuration file: - -```yaml -cache: - enabled: true - dir: "" - # Use the LAN IP obtained in step 1 - host: "192.168.8.17" - # Use the port number obtained in step 2 - port: 8088 -``` - -- 4.When starting the container, map the cache port to the host machine: - -```bash -docker run \ - --name gitea-docker-runner \ - -p 8088:8088 \ - -d gitea/act_runner:nightly -``` - -### Labels - -The labels of a runner are used to determine which jobs the runner can run, and how to run them. - -The default labels are `ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`. -It is a comma-separated list, and each item is a label. - -Let's take `ubuntu-22.04:docker://node:16-bullseye` as an example. -It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job will be run in a docker container with the image `node:16-bullseye`. - -If the default image is insufficient for your needs, and you have enough disk space to use a better and bigger one, you can change it to `ubuntu-22.04:docker://<the image you like>`. -You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md). - -If you want to run jobs in the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`, the `:host` is optional. -However, we suggest you to use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it. - -One more thing is that it is recommended to register the runner if you want to change the labels. -It may be annoying to do this, so we may provide a better way to do it in the future. - -## Running - -After you have registered the runner, you can run it by running the following command: - -```bash -./act_runner daemon -# or -./act_runner daemon --config config.yaml -``` - -The runner will fetch jobs from the Gitea instance and run them automatically. - -Since act runner is still in development, it is recommended to check the latest version and upgrade it regularly. diff --git a/docs/content/doc/usage/actions/act-runner.zh-cn.md b/docs/content/doc/usage/actions/act-runner.zh-cn.md deleted file mode 100644 index cc57282900..0000000000 --- a/docs/content/doc/usage/actions/act-runner.zh-cn.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -date: "2023-05-24T15:00:00+08:00" -title: "Act Runner" -slug: "act-runner" -weight: 20 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "Act Runner" - weight: 20 - identifier: "actions-runner" ---- - -# Act Runner - -本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)，这是Gitea Actions的Runner。 - -**目录** - -{{< toc >}} - -## 要求 - -建议在Docker容器中运行Job，因此您需要首先安装Docker。 -并确保Docker守护进程正在运行。 - -其他与Docker API兼容的OCI容器引擎也应该可以正常工作，但尚未经过测试。 - -但是，如果您确定要直接在主机上运行Job，则不需要Docker。 - -## 安装 - -有多种安装Act Runner的方法。 - -### 下载二进制文件 - -您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。 -然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/act_runner/)下载。 - -下载二进制文件时，请确保您已经下载了适用于您的平台的正确版本。 -您可以通过运行以下命令进行检查： - -```bash -chmod +x act_runner -./act_runner --version -``` - -如果看到版本信息，则表示您已经下载了正确的二进制文件。 - -### 使用 Docker 镜像 - -您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。 -与二进制文件类似，您可以使用`nightly`标签使用最新的夜间构建版本，而`latest`标签是最新的稳定版本。 - -```bash -docker pull gitea/act_runner:latest # for the latest stable release -docker pull gitea/act_runner:nightly # for the latest nightly build -``` - -## 配置 - -配置通过配置文件进行。它是可选的，当没有指定配置文件时，将使用默认配置。 - -您可以通过运行以下命令生成配置文件： - -```bash -./act_runner generate-config -``` - -默认配置是安全的，可以直接使用。 - -```bash -./act_runner generate-config > config.yaml -./act_runner --config config.yaml [command] -``` - -您亦可以如下使用 docker 创建配置文件： - -```bash -docker run --entrypoint="" --rm -it gitea/act_runner:latest act_runner generate-config > config.yaml -``` - -当使用Docker镜像时，可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中： - -```bash -docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ... -``` - -您可能注意到上面的命令都是不完整的，因为现在还不是运行Act Runner的时候。 -在运行Act Runner之前，我们需要首先将其注册到您的Gitea实例中。 - -## 注册 - -在运行Act Runner之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。 - -### Runner级别 - -您可以在不同级别上注册Runner，它可以是： - -- 实例级别：Runner将为实例中的所有存储库运行Job。 -- 组织级别：Runner将为组织中的所有存储库运行Job。 -- 存储库级别：Runner将为其所属的存储库运行Job。 - -请注意，即使存储库具有自己的存储库级别Runner，它仍然可以使用实例级别或组织级别Runner。未来的版本可能提供更多对此进行更好控制的选项。 - -### 获取注册令牌 - -Runner级别决定了从哪里获取注册令牌。 - -- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。 -- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。 -- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。 - -如果您无法看到设置页面，请确保您具有正确的权限并且已启用 Actions。 - -注册令牌的格式是一个随机字符串 `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`。 - -### 注册Runner - -可以通过运行以下命令来注册Act Runner： - -```bash -./act_runner register -``` - -或者，您可以使用 `--config` 选项来指定前面部分提到的配置文件。 - -```bash -./act_runner --config config.yaml register -``` - -您将逐步输入注册信息，包括： - -- Gitea 实例的 URL，例如 `https://gitea.com/` 或 `http://192.168.8.8:3000/`。 -- 注册令牌。 -- Runner名称（可选）。如果留空，将使用主机名。 -- Runner标签（可选）。如果留空，将使用默认标签。 - -您可能对Runner标签感到困惑，稍后将对其进行解释。 - -如果您想以非交互方式注册Runner，可以使用参数执行以下操作。 - -```bash -./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels> -``` - -注册Runner后，您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。 -请不要手动编辑该文件。 -如果此文件丢失或损坏，可以直接删除它并重新注册。 - -如果您想将注册信息存储在其他位置，请在配置文件中指定，并不要忘记指定 `--config` 选项。 - -### 使用Docker注册Runner - -如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行Act Runner时指定注册信息。 - -```bash -docker run \ - -v $(pwd)/config.yaml:/config.yaml \ - -v $(pwd)/data:/data \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -e CONFIG_FILE=/config.yaml \ - -e GITEA_INSTANCE_URL=<instance_url> \ - -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \ - -e GITEA_RUNNER_NAME=<runner_name> \ - -e GITEA_RUNNER_LABELS=<runner_labels> \ - --name my_runner \ - -d gitea/act_runner:nightly -``` - -您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。 -这是因为Act Runner将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。 -如前所述，如果要在主机上直接运行Job，可以将其移除。 -需要明确的是，这里的 "主机" 实际上指的是当前运行 Act Runner的容器，而不是主机机器本身。 - -### 使用 Docker compose 运行 Runner - -您亦可使用如下的 `docker-compose.yml`: - -```yml -version: "3.8" -services: - runner: - image: gitea/act_runner:nightly - environment: - CONFIG_FILE: /config.yaml - GITEA_INSTANCE_URL: "${INSTANCE_URL}" - GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}" - GITEA_RUNNER_NAME: "${RUNNER_NAME}" - GITEA_RUNNER_LABELS: "${RUNNER_LABELS}" - volumes: - - ./config.yaml:/config.yaml - - ./data:/data - - /var/run/docker.sock:/var/run/docker.sock -``` - -### 当您使用 Docker 镜像启动 Runner，如何配置 Cache - -如果你不打算在工作流中使用 `actions/cache`，你可以忽略本段。 - -如果您在使用 `actions/cache` 时没有进行额外的配置，将会返回以下错误信息： -> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT - -这个错误的原因是 runner 容器和作业容器位于不同的网络中，因此作业容器无法访问 runner 容器。 -因此，配置 cache 动作以确保其正常运行是非常重要的。请按照以下步骤操作： - -- 1.获取 Runner 容器所在主机的 LAN（本地局域网） IP 地址。 -- 2.获取一个 Runner 容器所在主机的空闲端口号。 -- 3.在配置文件中如下配置： - -```yaml -cache: -enabled: true -dir: "" -# 使用步骤 1. 获取的 LAN IP -host: "192.168.8.17" -# 使用步骤 2. 获取的端口号 -port: 8088 -``` - -- 4.启动容器时, 将 Cache 端口映射至主机。 - -```bash -docker run \ - --name gitea-docker-runner \ - -p 8088:8088 \ - -d gitea/act_runner:nightly -``` - -### 标签 - -Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们。 - -默认标签为`ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`。 -它们是逗号分隔的列表，每个项目都是一个标签。 - -让我们以 `ubuntu-22.04:docker://node:16-bullseye` 为例。 -它意味着Runner可以运行带有`runs-on: ubuntu-22.04`的Job，并且该Job将在使用`node:16-bullseye`镜像的Docker容器中运行。 - -如果默认镜像无法满足您的需求，并且您有足够的磁盘空间可以使用更好、更大的镜像，您可以将其更改为`ubuntu-22.04:docker://<您喜欢的镜像>`。 -您可以在[act 镜像](https://github.com/nektos/act/blob/master/IMAGES.md)上找到更多有用的镜像。 - -如果您想直接在主机上运行Job，您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04`，`:host`是可选的。 -然而，我们建议您使用类似`linux_amd64:host`或`windows:host`的特殊名称，以避免误用。 - -还有一点需要注意的是，建议在更改标签时注册Runner。 -这可能会有些麻烦，所以我们可能会在将来提供更好的方法来处理。 - -## 运行 - -注册完Runner后，您可以通过运行以下命令来运行它： - -```bash -./act_runner daemon -# or -./act_runner daemon --config config.yaml -``` - -Runner将从Gitea实例获取Job并自动运行它们。 - -由于Act Runner仍处于开发中，建议定期检查最新版本并进行升级。 diff --git a/docs/content/doc/usage/actions/comparison.en-us.md b/docs/content/doc/usage/actions/comparison.en-us.md deleted file mode 100644 index a8545fba44..0000000000 --- a/docs/content/doc/usage/actions/comparison.en-us.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -date: "2023-04-27T15:00:00+08:00" -title: "Compared to GitHub Actions" -slug: "comparison" -weight: 30 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "Comparison" - weight: 30 - identifier: "actions-comparison" ---- - -# Compared to GitHub Actions - -Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them. - -**Table of Contents** - -{{< toc >}} - -## Additional features - -### Absolute action URLs - -Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository. -Like `uses: https://github.com/actions/checkout@v3` or `uses: http://your_gitea.com/owner/repo@branch`. - -### Actions written in Go - -Gitea Actions supports writing actions in Go. -See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/). - -## Unsupported workflows syntax - -### `concurrency` - -It's used to run a single job at a time. -See [Using concurrency](https://docs.github.com/en/actions/using-jobs/using-concurrency). - -It's ignored by Gitea Actions now. - -### `run-name` - -The name for workflow runs generated from the workflow. -See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name). - -It's ignored by Gitea Actions now. - -### `permissions` and `jobs.<job_id>.permissions` - -See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions). - -It's ignored by Gitea Actions now. - -### `jobs.<job_id>.timeout-minutes` - -See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes). - -It's ignored by Gitea Actions now. - -### `jobs.<job_id>.continue-on-error` - -See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error). - -It's ignored by Gitea Actions now. - -### `jobs.<job_id>.environment` - -See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment). - -It's ignored by Gitea Actions now. - -### Complex `runs-on` - -See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on). - -Gitea Actions only supports `runs-on: xyz` or `runs-on: [xyz]` now. - -### `workflow_dispatch` - -See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch). - -It's ignored by Gitea Actions now. - -### `hashFiles` expression - -See [Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles) - -Gitea Actions doesn't support it now, if you use it, the result will always be empty string. - -As a workaround, you can use [go-hashfiles](https://gitea.com/actions/go-hashfiles) instead. - -## Missing features - -### Variables - -See [Variables](https://docs.github.com/en/actions/learn-github-actions/variables). - -It's under development. - -### Problem Matchers - -Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI. -See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md). - -It's ignored by Gitea Actions now. - -### Create an error annotation - -See [Creating an annotation for an error](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) - -It's ignored by Gitea Actions now. - -## Missing UI features - -### Pre and Post steps - -Pre and Post steps don't have their own section in the job log user interface. - -## Different behavior - -### Downloading actions - -Gitea Actions doesn't download actions from GitHub by default. -"By default" means that you don't specify the host in the `uses` field, like `uses: actions/checkout@v3`. -As a contrast, `uses: https://github.com/actions/checkout@v3` has specified host. - -The missing host will be filled with `https://gitea.com` if you don't configure it. -That means `uses: actions/checkout@v3` will download the action from [gitea.com/actions/checkout](https://gitea.com/actions/checkout), instead of [github.com/actions/checkout](https://github.com/actions/checkout). - -As mentioned, it's configurable. -If you want your runners to download actions from GitHub or your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`. See [Configuration Cheat Sheet]({{< relref "doc/administration/config-cheat-sheet.en-us.md#actions-actions" >}}). - -### Context availability - -Context availability is not checked, so you can use the env context on more places. -See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability). - -## Known issues - -### `docker/build-push-action@v4` - -See [act_runner#119](https://gitea.com/gitea/act_runner/issues/119#issuecomment-738294). - -`ACTIONS_RUNTIME_TOKEN` is a random string in Gitea Actions, not a JWT. -But the `docker/build-push-action@v4` tries to parse the token as JWT and doesn't handle the error, so the job fails. - -There are two workarounds: - -Set the `ACTIONS_RUNTIME_TOKEN` to empty manually, like: - -``` yml -- name: Build and push - uses: docker/build-push-action@v4 - env: - ACTIONS_RUNTIME_TOKEN: '' - with: -... -``` - -The bug has been fixed in a newer [commit](https://gitea.com/docker/build-push-action/commit/d8823bfaed2a82c6f5d4799a2f8e86173c461aba?style=split&whitespace=show-all#diff-1af9a5bdf96ddff3a2f3427ed520b7005e9564ad), but it has not been released. So you could use the latest version by specifying the branch name, like: - -``` yml -- name: Build and push - uses: docker/build-push-action@master - with: -... -``` diff --git a/docs/content/doc/usage/actions/comparison.zh-cn.md b/docs/content/doc/usage/actions/comparison.zh-cn.md deleted file mode 100644 index 2fc3a23167..0000000000 --- a/docs/content/doc/usage/actions/comparison.zh-cn.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -date: "2023-05-24T15:00:00+08:00" -title: "与GitHub Actions的对比" -slug: "comparison" -weight: 30 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "对比" - weight: 30 - identifier: "actions-comparison" ---- - -# 与GitHub Actions的对比 - -尽管Gitea Actions旨在与GitHub Actions兼容，但它们之间存在一些差异。 - -**目录** - -{{< toc >}} - -## 额外功能 - -### Action URL绝对路径 - -Gitea Actions支持通过URL绝对路径定义actions，这意味着您可以使用来自任何Git存储库的Actions。 -例如，`uses: https://github.com/actions/checkout@v3`或`uses: http://your_gitea.com/owner/repo@branch`。 - -### 使用Go编写Actions - -Gitea Actions支持使用Go编写Actions。 -请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。 - -## 不支持的工作流语法 - -### `concurrency` - -这是用于一次运行一个Job。 -请参阅[使用并发](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。 - -Gitea Actions目前不支持此功能。 - -### `run-name` - -这是工作流生成的工作流运行的名称。 -请参阅[GitHub Actions 的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。 - -Gitea Actions目前不支持此功能。 - -### `permissions`和`jobs.<job_id>.permissions` - -请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。 - -Gitea Actions目前不支持此功能。 - -### `jobs.<job_id>.timeout-minutes` - -请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。 - -Gitea Actions目前不支持此功能。 - -### `jobs.<job_id>.continue-on-error` - -请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。 - -Gitea Actions目前不支持此功能。 - -### `jobs.<job_id>.environment` - -请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。 - -Gitea Actions 目前不支持此功能。 - -### 复杂的`runs-on` - -请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。 - -Gitea Actions目前只支持`runs-on: xyz`或`runs-on: [xyz]`。 - -### `workflow_dispatch` - -请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch)。 - -Gitea Actions目前不支持此功能。 - -### `hashFiles`表达式 - -请参阅[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。 - -Gitea Actions目前不支持此功能，如果使用它，结果将始终为空字符串。 - -作为解决方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。 - -## 缺失的功能 - -### 变量 - -请参阅[变量](https://docs.github.com/zh/actions/learn-github-actions/variables)。 - -目前变量功能正在开发中。 - -### 问题匹配器 - -问题匹配器是一种扫描Actions输出以查找指定正则表达式模式并在用户界面中突出显示该信息的方法。 -请参阅[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。 - -Gitea Actions目前不支持此功能。 - -### 为错误创建注释 - -请参阅[为错误创建注释](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。 - -Gitea Actions目前不支持此功能。 - -## 缺失的UI功能 - -### 预处理和后处理步骤 - -预处理和后处理步骤在Job日志用户界面中没有自己的用户界面。 - -## 不一样的行为 - -### 下载Actions - -Gitea Actions默认不从GitHub下载Actions。 -"默认" 意味着您在`uses` 字段中不指定主机，如`uses: actions/checkout@v3`。 -相反，`uses: https://github.com/actions/checkout@v3`是有指定主机的。 - -如果您不进行配置，缺失的主机将填充为`https://gitea.com`。 -这意味着`uses: actions/checkout@v3`将从[gitea.com/actions/checkout](https://gitea.com/actions/checkout)下载该Action，而不是[github.com/actions/checkout](https://github.com/actions/checkout)。 - -正如前面提到的，这是可配置的。 -如果您希望您的运行程序默认从GitHub或您自己的Gitea实例下载动作，您可以通过设置`[actions].DEFAULT_ACTIONS_URL`进行配置。请参阅[配置备忘单]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#actions-actions" >}})。 - -### 上下文可用性 - -不检查上下文可用性，因此您可以在更多地方使用env上下文。 -请参阅[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。 - -## 已知问题 - -### `docker/build-push-action@v4` - -请参阅[act_runner#119](https://gitea.com/gitea/act_runner/issues/119#issuecomment-738294)。 - -`ACTIONS_RUNTIME_TOKEN`在Gitea Actions中是一个随机字符串，而不是JWT。 -但是`DOCKER/BUILD-PUSH-ACTION@V4尝试将令牌解析为JWT，并且不处理错误，因此Job失败。 - -有两种解决方法： - -手动将`ACTIONS_RUNTIME_TOKEN`设置为空字符串，例如： - -``` yml -- name: Build and push - uses: docker/build-push-action@v4 - env: - ACTIONS_RUNTIME_TOKEN: '' - with: -... -``` - -该问题已在较新的[提交](https://gitea.com/docker/build-push-action/commit/d8823bfaed2a82c6f5d4799a2f8e86173c461aba?style=split&whitespace=show-all#diff-1af9a5bdf96ddff3a2f3427ed520b7005e9564ad)中修复，但尚未发布。因此，您可以通过指定分支名称来使用最新版本，例如： - -``` yml -- name: Build and push - uses: docker/build-push-action@master - with: -... -``` diff --git a/docs/content/doc/usage/actions/design.en-us.md b/docs/content/doc/usage/actions/design.en-us.md deleted file mode 100644 index c996185fe6..0000000000 --- a/docs/content/doc/usage/actions/design.en-us.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -date: "2023-04-27T15:00:00+08:00" -title: "Design of Gitea Actions" -slug: "design" -weight: 40 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "Design" - weight: 40 - identifier: "actions-design" ---- - -# Design of Gitea Actions - -Gitea Actions has multiple components. This document describes them individually. - -**Table of Contents** - -{{< toc >}} - -## Act - -The [nektos/act](https://github.com/nektos/act) project is an excellent tool that allows you to run your GitHub Actions locally. -We were inspired by this and wondered if it would be possible to run actions for Gitea. - -However, while [nektos/act](https://github.com/nektos/act) is designed as a command line tool, what we actually needed was a Go library with modifications specifically for Gitea. -So we forked it as [gitea/act](https://gitea.com/gitea/act). - -This is a soft fork that will periodically follow the upstream. -Although some custom commits have been added, we will try our best to avoid changing too much of the original code. - -The forked act is just a shim or adapter for Gitea's specific usage. -There are some additional commits that have been made, such as: - -- Outputting execution logs to logger hook so they can be reported to Gitea -- Disabling the GraphQL URL, since Gitea doesn't support it -- Starting a new container for every job instead of reusing to ensure isolation. - -These modifications have no reason to be merged into the upstream. -They don't make sense if the user just wants to run trusted actions locally. - -However, there may be overlaps in the future, such as a required bug fix or new feature needed by both projects. -In these cases, we will contribute the changes back to the upstream repository. - -## Act runner - -Gitea's runner is called act runner because it's based on act. - -Like other CI runners, we designed it as an external part of Gitea, which means it should run on a different server than Gitea. - -To ensure that the runner connects to the correct Gitea instance, we need to register it with a token. -Additionally, the runner will introduce itself to Gitea and declare what kind of jobs it can run by reporting its labels. - -Earlier, we mentioned that `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label. -But how does the runner know to run `ubuntu-latest`? The answer lies in mapping the label to an environment. -That's why when you add custom labels during registration, you will need to input some complex content like `my_custom_label:docker://centos:7`. -This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`. - -Docker isn't the only option, though. -The act also supports running jobs directly on the host. -This is achieved through labels like `linux_arm:host`. -This label indicates that the runner can take a job that needs to run on `linux_arm` and run it directly on the host. - -The label's design follows the format `label[:schema[:args]]`. -If the schema is omitted, it defaults to `host`. -So, - -- `my_custom_label:docker://node:18`: Run jobs labeled with `my_custom_label` using the `node:18` Docker image. -- `my_custom_label:host`: Run jobs labeled with `my_custom_label` directly on the host. -- `my_custom_label`: Same as `my_custom_label:host`. -- `my_custom_label:vm:ubuntu-latest`: (Example only, not implemented) Run jobs labeled with `my_custom_label` using a virtual machine with the `ubuntu-latest` ISO. - -## Communication protocol - -As act runner is an independent part of Gitea, we needed a protocol for runners to communicate with the Gitea instance. -However, we did not think it was a good idea to have Gitea listen on a new port. -Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP. -We chose to use gRPC over HTTP. - -We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up. -More information about gRPC can be found on [its website](https://grpc.io/). - -## Network architecture - -Let's examine the overall network architecture. -This will help you troubleshoot some problems and explain why it's a bad idea to register a runner with a loopback address of the Gitea instance. - - - -There are four network connections marked in the picture, and the direction of the arrows indicates the direction of establishing the connections. - -### Connection 1, act runner to Gitea instance - -The act runner must be able to connect to Gitea to receive tasks and send back the execution results. - -### Connection 2, job containers to Gitea instance - -The job containers have different network namespaces than the runner, even if they are on the same machine. -They need to connect to Gitea to fetch codes if there is `actions/checkout@v3` in the workflow, for example. -Fetching code is not always necessary to run some jobs, but it is required in most cases. - -If you use a loopback address to register a runner, the runner can connect to Gitea when it is on the same machine. -However, if a job container tries to fetch code from localhost, it will fail because Gitea is not in the same container. - -### Connection 3, act runner to internet - -When you use some actions like `actions/checkout@v3`, the act runner downloads the scripts, not the job containers. -By default, it downloads from [gitea.com](http://gitea.com/), so it requires access to the internet. -It also downloads some docker images from Docker Hub by default, which also requires internet access. - -However, internet access is not strictly necessary. -You can configure your Gitea instance to fetch actions or images from your intranet facilities. - -In fact, your Gitea instance can serve as both the actions marketplace and the image registry. -You can mirror actions repositories from GitHub to your Gitea instance, and use them as normal. -And [Gitea Container Registry](https://docs.gitea.io/en-us/usage/packages/container/) can be used as a Docker image registry. - -### Connection 4, job containers to internet - -When using actions such as `actions/setup-go@v4`, it may be necessary to download resources from the internet to set up the Go language environment in job containers. -Therefore, access to the internet is required for the successful completion of these actions. - -However, it is optional as well. -You can use your own custom actions to avoid relying on internet access, or you can use your packaged Docker image to run jobs with all dependencies installed. - -## Summary - -Using Gitea Actions only requires ensuring that the runner can connect to the Gitea instance. -Internet access is optional, but not having it will require some additional work. -In other words: The runner works best when it can query the internet itself, but you don't need to expose it to the internet (in either direction). - -If you encounter any network issues while using Gitea Actions, hopefully the image above can help you troubleshoot them. diff --git a/docs/content/doc/usage/actions/design.zh-cn.md b/docs/content/doc/usage/actions/design.zh-cn.md deleted file mode 100644 index e1bd1766e7..0000000000 --- a/docs/content/doc/usage/actions/design.zh-cn.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -date: "2023-05-24T15:00:00+08:00" -title: "Gitea Actions设计" -slug: "design" -weight: 40 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "设计" - weight: 40 - identifier: "actions-design" ---- - -# Gitea Actions设计 - -Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。 - -**目录** - -{{< toc >}} - -## Act - -[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。 -我们受到了它的启发，并思考它是否可能为Gitea运行Actions。 - -然而，尽管[nektos/act](https://github.com/nektos/act)被设计为一个命令行工具，但我们实际上需要的是一个专为Gitea修改的Go库。 -因此，我们在[gitea/act](https://gitea.com/gitea/act)基础上进行了分叉。 - -这是一个软分叉，将定期跟进上游。 -虽然添加了一些自定义提交，但我们会尽力避免对原始代码进行太多更改。 - -分叉的 act 只是Gitea特定用途的桥接或适配器。 -还添加了一些额外的提交，例如： - -- 将执行日志输出到日志记录器钩子，以便报告给Gitea -- 禁用 GraphQL URL，因为Gitea不支持它 -- 每个Job启动一个新的容器，而不是重复使用，以确保隔离性。 - -这些修改没有理由合并到上游。 -如果用户只想在本地运行可信的Actions，它们是没有意义的。 - -然而，将来可能会出现重叠，例如两个项目都需要的必要错误修复或新功能。 -在这些情况下，我们将向上游仓库贡献变更。 - -## act runner - -Gitea的Runner被称为act runner，因为它基于act。 - -与其他CIRunner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。 - -为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。 -此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。 - -之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。 -但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。 -这就是为什么在注册过程中添加自定义标签时，需要输入一些复杂内容，比如`my_custom_label:docker://centos:7`。 -这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。 - -然而，Docker不是唯一的选择。 -act 也支持直接在主机上运行Job。 -这是通过像`linux_arm:host`这样的标签实现的。 -这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。 - -标签的设计遵循格式`label[:schema[:args]]`。 -如果省略了schema，则默认为`host`。 - -因此， - -- `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。 -- `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。 -- `my_custom_label`：等同于`my_custom_label:host`。 -- `my_custom_label:vm:ubuntu-latest`：（仅为示例，未实现）使用带有`ubuntu-latest` ISO的虚拟机运行带有`my_custom_label`标签的Job。 - -## 通信协议 - -由于act runner是Gitea的独立部分，我们需要一种协议让Runner与Gitea实例进行通信。 -然而，我们不认为让Gitea监听一个新端口是个好主意。 -相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。 -因此，我们选择使用基于HTTP的gRPC。 - -我们使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 进行连接。 -有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。 - -## 网络架构 - -让我们来看一下整体的网络架构。 -这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。 - - - -图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。 - -### 连接 1，act runner到Gitea实例 - -act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。 - -### 连接 2，Job容器到Gitea实例 - -即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。 -举个例子，如果工作流中包含 `actions/checkout@v3`，Job容器需要连接到Gitea来获取代码。 -获取代码并不总是运行某些Job所必需的，但在大多数情况下是必需的。 - -如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。 -然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。 - -### 连接 3，act runner到互联网 - -当您使用诸如 `actions/checkout@v3` 的一些Actions时，act runner下载的是脚本，而不是Job容器。 -默认情况下，它从[gitea.com](http://gitea.com/)下载，因此需要访问互联网。 -它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。 - -然而，互联网访问并不是绝对必需的。 -您可以配置您的Gitea实例从您的内部网络设施中获取 Actions 或镜像。 - -实际上，您的Gitea实例可以同时充当 Actions 市场和镜像注册表。 -您可以将GitHub上的Actions仓库镜像到您的Gitea实例，并将其用作普通Actions。 -而 [Gitea 容器注册表](https://docs.gitea.io/en-us/usage/packages/container/) 可用作Docker镜像注册表。 - -### 连接 4，Job容器到互联网 - -当使用诸如`actions/setup-go@v4`的Actions时，可能需要从互联网下载资源，以设置Job容器中的Go语言环境。 -因此，成功完成这些Actions需要访问互联网。 - -然而，这也是可选的。 -您可以使用自定义的Actions来避免依赖互联网访问，或者可以使用已安装所有依赖项的打包的Docker镜像来运行Job。 - -## 总结 - -使用Gitea Actions只需要确保Runner能够连接到Gitea实例。 -互联网访问是可选的，但如果没有互联网访问，将需要额外的工作。 -换句话说：当Runner能够自行查询互联网时，它的工作效果最好，但您不需要将其暴露给互联网（无论是单向还是双向）。 - -如果您在使用Gitea Actions时遇到任何网络问题，希望上面的图片能够帮助您进行故障排除。 diff --git a/docs/content/doc/usage/actions/faq.en-us.md b/docs/content/doc/usage/actions/faq.en-us.md deleted file mode 100644 index 69a4cf3e89..0000000000 --- a/docs/content/doc/usage/actions/faq.en-us.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -date: "2023-04-27T15:00:00+08:00" -title: "Frequently Asked Questions of Gitea Actions" -slug: "faq" -weight: 100 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "FAQ" - weight: 100 - identifier: "actions-faq" ---- - -# Frequently Asked Questions of Gitea Actions - -This page contains some common questions and answers about Gitea Actions. - -**Table of Contents** - -{{< toc >}} - -## Why is Actions not enabled by default? - -We know it's annoying to enable Actions for the whole instance and each repository one by one, but not everyone likes or needs this feature. -We believe that more work needs to be done to improve Gitea Actions before it deserves any further special treatment. - -## Is it possible to enable Actions for new repositories by default for my own instance? - -Yes, when you enable Actions for the instance, you can choose to enable the `actions` unit for all new repositories by default. - -```ini -[repository] -DEFAULT_REPO_UNITS = ...,repo.actions -``` - -## Should we use `${{ github.xyz }}` or `${{ gitea.xyz }}` in workflow files? - -You can use `github.xyz` and Gitea will work fine. -As mentioned, Gitea Actions is designed to be compatible with GitHub Actions. -However, we recommend using `gitea.xyz` in case Gitea adds something that GitHub does not have to avoid different kinds of secrets in your workflow file (and because you are using this workflow on Gitea, not GitHub). -Still, this is completely optional since both options have the same effect at the moment. - -## Is it possible to register runners for a specific user (not organization)? - -Not yet. -It is technically possible to implement, but we need to discuss whether it is necessary. - -## Where will the runner download scripts when using actions such as `actions/checkout@v3`? - -You may be aware that there are tens of thousands of [marketplace actions](https://github.com/marketplace?type=actions) in GitHub. -However, when you write `uses: actions/checkout@v3`, it actually downloads the scripts from [gitea.com/actions/checkout](http://gitea.com/actions/checkout) by default (not GitHub). -This is a mirror of [github.com/actions/checkout](http://github.com/actions/checkout), but it's impossible to mirror all of them. -That's why you may encounter failures when trying to use some actions that haven't been mirrored. - -The good news is that you can specify the URL prefix to use actions from anywhere. -This is an extra syntax in Gitea Actions. -For example: - -- `uses: https://github.com/xxx/xxx@xxx` -- `uses: https://gitea.com/xxx/xxx@xxx` -- `uses: http://your_gitea_instance.com/xxx@xxx` - -Be careful, the `https://` or `http://` prefix is necessary! - -Alternatively, if you want your runners to download actions from GitHub or your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`. -See [Configuration Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#actions-actions). - -This is one of the differences from GitHub Actions, but it should allow users much more flexibility in how they run Actions. - -## How to limit the permission of the runners? - -Runners have no more permissions than simply connecting to your Gitea instance. -When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job. -If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](https://docs.gitea.io/en-us/usage/secrets/) to it. - -Refined permission control to Actions is a complicated job. -In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization. - -## How to avoid being hacked? - -There are two types of possible attacks: unknown runner stealing the code or secrets from your repository, or malicious scripts controlling your runner. - -Avoiding the former means not allowing people you don't know to register runners for your repository, organization, or instance. - -The latter is a bit more complicated. -If you're using a private Gitea instance for your company, you may not need to worry about security since you trust your colleagues and can hold them accountable. - -For public instances, things are a little different. -Here's how we do it on [gitea.com](http://gitea.com/): - -- We only register runners for the "gitea" organization, so our runners will not execute jobs from other repositories. -- Our runners always run jobs with isolated containers. While it is possible to do this directly on the host, we choose not to for more security. -- To run actions for fork pull requests, approval is required. See [#22803](https://github.com/go-gitea/gitea/pull/22803). -- If someone registers their own runner for their repository or organization on [gitea.com](http://gitea.com/), we have no objections and will just not use it in our org. However, they should take care to ensure that the runner is not used by other users they do not know. - -## Which operating systems are supported by act runner? - -It works well on Linux, macOS, and Windows. -While other operating systems are theoretically supported, they require further testing. - -One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures. - -For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default. -Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun). - -```yaml -defaults: - run: - shell: powershell -``` - -## Why choose GitHub Actions? Why not something compatible with GitLab CI/CD? - -[@lunny](https://gitea.com/lunny) has explained this in the [issue to implement actions](https://github.com/go-gitea/gitea/issues/13539). -Furthermore, Actions is not only a CI/CD system but also an automation tool. - -There have also been numerous [marketplace actions](https://github.com/marketplace?type=actions) implemented in the open-source world. -It is exciting to be able to reuse them. - -## What if it runs on multiple labels, such as `runs-on: [label_a, label_b]`? - -This is valid syntax. -It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on). -Unfortunately, act runner does not work this way. -As mentioned, we map labels to environments: - -- `ubuntu` → `ubuntu:22.04` -- `centos` → `centos:8` - -But we need to map label groups to environments instead, like so: - -- `[ubuntu]` → `ubuntu:22.04` -- `[with-gpu]` → `linux:with-gpu` -- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu` - -We also need to re-design how tasks are assigned to runners. -A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`. -Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`. -This is not a technical problem, it was just overlooked in the early design. -See [runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65). - -Currently, the act runner attempts to match everyone in the labels and uses the first match it finds. - -## What is the difference between agent labels and custom labels for a runner? - - - -Agent labels are reported to the Gitea instance by the runner during registration. -Custom labels, on the other hand, are added manually by a Gitea administrator or owners of the organization or repository (depending on the level of the runner). - -However, the design here needs improvement, as it currently has some rough edges. -You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`. -However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end. -This default may not match user expectations. -See [runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71). - -In the meantime, we suggest that you re-register your runner if you want to change its labels. - -## Will there be more implementations for Gitea Actions runner? - -Although we would like to provide more options, our limited manpower means that act runner will be the only officially supported runner. -However, both Gitea and act runner are completely open source, so anyone can create a new/better implementation. -We support your choice, no matter how you decide. -In case you fork act runner to create your own version: Please contribute the changes back if you can and if you think your changes will help others as well. - -## What workflow trigger events does Gitea support? - -All events listed in this table are supported events and are compatible with GitHub. -For events supported only by GitHub, see GitHub's [documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows). - -| trigger event | activity types | -|-----------------------------|--------------------------------------------------------------------------------------------------------------------------| -| create | not applicable | -| delete | not applicable | -| fork | not applicable | -| gollum | not applicable | -| push | not applicable | -| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` | -| issue_comment | `created`, `edited`, `deleted` | -| pull_request | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled` | -| pull_request_review | `submitted`, `edited` | -| pull_request_review_comment | `created`, `edited` | -| release | `published`, `edited` | -| registry_package | `published` | diff --git a/docs/content/doc/usage/actions/faq.zh-cn.md b/docs/content/doc/usage/actions/faq.zh-cn.md deleted file mode 100644 index ae6edd06f2..0000000000 --- a/docs/content/doc/usage/actions/faq.zh-cn.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -date: "2023-05-24T15:00:00+08:00" -title: "Gitea Actions常见问题解答" -slug: "faq" -weight: 100 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "常见问题" - weight: 100 - identifier: "actions-faq" ---- - -# Gitea Actions常见问题解答 - -本页面包含一些关于Gitea Actions的常见问题和答案。 - -**目录** - -{{< toc >}} - -## 为什么默认情况下不启用Actions？ - -我们知道为整个实例和每个仓库启用Actions可能很麻烦，但并不是每个人都喜欢或需要此功能。 -在我们认为Gitea Actions值得被特别对待之前，我们认为还需要做更多的工作来改进它。 - -## 是否可以在我的实例中默认启用新仓库的Actions？ - -是的，当您为实例启用Actions时，您可以选择默认启用actions单元以适用于所有新仓库。 - -```ini -[repository] -DEFAULT_REPO_UNITS = ...,repo.actions -``` - -## 在工作流文件中应该使用`${{ github.xyz }}`还是`${{ gitea.xyz }}`？ - -您可以使用`github.xyz`，Gitea将正常工作。 -如前所述，Gitea Actions的设计是与GitHub Actions兼容的。 -然而，我们建议在工作流文件中使用`gitea.xyz`，以防止在工作流文件中出现不同类型的密钥（因为您在Gitea上使用此工作流，而不是GitHub）。 -不过，这完全是可选的，因为目前这两个选项的效果是相同的。 - -## 是否可以为特定用户（而不是组织）注册Runner？ - -目前还不可以。 -从技术上讲是可以实现的，但我们需要讨论是否有必要。 - -## 使用`actions/checkout@v3`等Actions时，Job容器会从何处下载脚本？ - -您可能知道GitHub上有成千上万个[Actions市场](https://github.com/marketplace?type=actions)。 -然而，当您编写`uses: actions/checkout@v3`时，它实际上默认从[gitea.com/actions/checkout](http://gitea.com/actions/checkout)下载脚本（而不是从GitHub下载）。 -这是[github.com/actions/checkout](http://github.com/actions/checkout)的镜像，但无法将它们全部镜像。 -这就是为什么在尝试使用尚未镜像的某些Actions时可能会遇到失败的原因。 - -好消息是，您可以指定要从任何位置使用Actions的URL前缀。 -这是Gitea Actions中的额外语法。 -例如： - -- `uses: https://github.com/xxx/xxx@xxx` -- `uses: https://gitea.com/xxx/xxx@xxx` -- `uses: http://your_gitea_instance.com/xxx@xxx` - -注意，`https://`或`http://`前缀是必需的！ - -另外，如果您希望您的Runner默认从GitHub或您自己的Gitea实例下载Actions，可以通过设置 `[actions].DEFAULT_ACTIONS_URL`进行配置。 -参见[配置速查表](https://docs.gitea.io/en-us/config-cheat-sheet/#actions-actions)。 - -这是与GitHub Actions的一个区别，但它应该允许用户以更灵活的方式运行Actions。 - -## 如何限制Runner的权限？ - -Runner仅具有连接到您的Gitea实例的权限。 -当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。 -如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](https://docs.gitea.io/en-us/usage/secrets/)。 - -对于 Actions 的细粒度权限控制是一项复杂的工作。 -在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。 - -## 如何避免被黑客攻击？ - -有两种可能的攻击类型：未知的Runner窃取您的仓库中的代码或密钥，或恶意脚本控制您的Runner。 - -避免前者意味着不允许您不认识的人为您的仓库、组织或实例注册Runner。 - -后者要复杂一些。 -如果您为公司使用私有的Gitea实例，您可能不需要担心安全问题，因为您信任您的同事，并且可以追究他们的责任。 - -对于公共实例，情况略有不同。 -以下是我们在 [gitea.com](http://gitea.com/)上的做法： - -- 我们仅为 "gitea" 组织注册Runner，因此我们的Runner不会执行来自其他仓库的Job。 -- 我们的Runner始终在隔离容器中运行Job。虽然可以直接在主机上进行这样的操作，但出于安全考虑，我们选择不这样做。 -- 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。 -- 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。 - -## act runner支持哪些操作系统？ - -它在Linux、macOS和Windows上运行良好。 -虽然理论上支持其他操作系统，但需要进一步测试。 - -需要注意的一点是，如果选择直接在主机上运行Job而不是在Job容器中运行，操作系统之间的环境差异可能会导致意外的失败。 - -例如，在大多数情况下，Windows上没有可用的bash，而act尝试默认使用bash运行脚本。 -因此，您需要在工作流文件中将默认shell指定为`powershell`，参考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。 - -```yaml -defaults: - run: - shell: powershell -``` - -## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？ - -[@lunny](https://gitea.com/lunny)在实现Actions的[问题](https://github.com/go-gitea/gitea/issues/13539)中已经解释过这个问题。 -此外，Actions不仅是一个CI/CD 系统，还是一个自动化工具。 - -在开源世界中，已经有许多[市场上的Actions](https://github.com/marketplace?type=actions)实现了。 -能够重用它们是令人兴奋的。 - -## 如果它在多个标签上运行，例如 `runs-on: [label_a, label_b]`，会发生什么？ - -这是有效的语法。 -它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。 -不幸的是，act runner 并不支持这种方式。 -如上所述，我们将标签映射到环境： - -- `ubuntu` → `ubuntu:22.04` -- `centos` → `centos:8` - -但我们需要将标签组映射到环境，例如： - -- `[ubuntu]` → `ubuntu:22.04` -- `[with-gpu]` → `linux:with-gpu` -- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu` - -我们还需要重新设计任务分配给Runner的方式。 -具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。 -因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。 -这不是一个技术问题，只是在早期设计中被忽视了。 -参见[runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。 - -目前，act runner尝试匹配标签中的每一个，并使用找到的第一个匹配项。 - -## 代理标签和自定义标签对于Runner有什么区别？ - - - -代理标签是由Runner在注册过程中向Gitea实例报告的。 -而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。 - -然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。 -您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。 -然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。 -这个默认值可能与用户的期望不符。 -参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。 - -与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。 - -## Gitea Actions runner会有更多的实现吗？ - -虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。 -然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。 -我们支持您的选择，无论您如何决定。 -如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。 - -## Gitea 支持哪些工作流触发事件？ - -表格中列出的所有事件都是支持的，并且与 GitHub 兼容。 -对于仅 GitHub 支持的事件，请参阅 GitHub 的[文档](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)。 - -| 触发事件 | 活动类型 | -|-----------------------------|--------------------------------------------------------------------------------------------------------------------------| -| create | 不适用 | -| delete | 不适用 | -| fork | 不适用 | -| gollum | 不适用 | -| push | 不适用 | -| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` | -| issue_comment | `created`, `edited`, `deleted` | -| pull_request | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled` | -| pull_request_review | `submitted`, `edited` | -| pull_request_review_comment | `created`, `edited` | -| release | `published`, `edited` | -| registry_package | `published` | diff --git a/docs/content/doc/usage/actions/overview.en-us.md b/docs/content/doc/usage/actions/overview.en-us.md deleted file mode 100644 index e07eca994f..0000000000 --- a/docs/content/doc/usage/actions/overview.en-us.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -date: "2023-04-27T15:00:00+08:00" -title: "Gitea Actions" -slug: "overview" -weight: 1 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "Overview" - weight: 1 - identifier: "actions-overview" ---- - -# Gitea Actions - -Starting with Gitea **1.19**, Gitea Actions are available as a built-in CI/CD solution. - -**Table of Contents** - -{{< toc >}} - -## Name - -It is similar and compatible to [GitHub Actions](https://github.com/features/actions), and its name is inspired by it too. -To avoid confusion, we have clarified the spelling here: - -- "Gitea Actions" (with an "s", both words capitalized) is the name of the Gitea feature. -- "GitHub Actions" is the name of the GitHub feature. -- "Actions" could refer to either of the above, depending on the context. So it refers to "Gitea Actions" in this document. -- "action" or "actions" refer to some scripts/plugins to be used, like "actions/checkout@v3" or "actions/cache@v3". - -## Runners - -Just like other CI/CD solutions, Gitea doesn't run the jobs itself, but delegates the jobs to runners. -The runner of Gitea Actions is called [act runner](https://gitea.com/gitea/act_runner), it is a standalone program and also written in Go. -It is based on a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act). - -Because the runner is deployed independently, there could be potential security issues. -To avoid them, please follow two simple rules: - -- Don't use a runner you don't trust for your repository, organization or instance. -- Don't provide a runner to a repository, organization or instance you don't trust. - -For Gitea instances used internally, such as instances used by enterprises or individuals, neither of these two rules is a problem, they are naturally so. -However, for public Gitea instances, such as [gitea.com](https://gitea.com), these two rules should be kept in mind when adding or using runners. - -## Status - -Gitea Actions is still under development, so there may be some bugs and missing features. -And breaking changes may be made before it's stable (v1.20 or later). - -If the situation changes, we will update it here. -So please refer to the content here when you find outdated articles elsewhere. diff --git a/docs/content/doc/usage/actions/overview.zh-cn.md b/docs/content/doc/usage/actions/overview.zh-cn.md deleted file mode 100644 index 2081448151..0000000000 --- a/docs/content/doc/usage/actions/overview.zh-cn.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -date: "2023-05-24T15:00:00+08:00" -title: "Gitea Actions" -slug: "overview" -weight: 1 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "Overview" - weight: 1 - identifier: "actions-overview" ---- - -# Gitea Actions - -从Gitea **1.19**版本开始，Gitea Actions成为了内置的CI/CD解决方案。 - -**目录** - -{{< toc >}} - -## 名称 - -Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且兼容，它的名称也受到了它的启发。 -为了避免混淆，在这里我们明确了拼写方式： - -- "Gitea Actions"（两个单词都大写且带有"s"）是Gitea功能的名称。 -- "GitHub Actions"是GitHub功能的名称。 -- "Actions"根据上下文的不同可以指代以上任意一个。在本文档中指代的是"Gitea Actions"。 -- "action"或"actions"指代一些要使用的脚本/插件，比如"actions/checkout@v3"或"actions/cache@v3"。 - -## Runner - -和其他CI/CD解决方案一样，Gitea不会自己运行Job，而是将Job委托给Runner。 -Gitea Actions的Runner被称为[act runner](https://gitea.com/gitea/act_runner)，它是一个独立的程序，也是用Go语言编写的。 -它是基于[nektos/act](http://github.com/nektos/act)的一个[分支](https://gitea.com/gitea/act) 。 - -由于Runner是独立部署的，可能存在潜在的安全问题。 -为了避免这些问题，请遵循两个简单的规则： - -- 不要为你的仓库、组织或实例使用你不信任的Runner。 -- 不要为你不信任的仓库、组织或实例提供Runner。 - -对于内部使用的Gitea实例，比如企业或个人使用的实例，这两个规则不是问题，它们自然而然就是如此。 -然而，对于公共的Gitea实例，比如[gitea.com](https://gitea.com)，在添加或使用Runner时应当牢记这两个规则。 - -## 状态 - -Gitea Actions仍然在开发中，因此可能存在一些错误和缺失的功能。 -并且在稳定版本（v1.20或更高版本）之前可能会进行一些重大的更改。 - -如果情况发生变化，我们将在此处进行更新。 -因此，请在其他地方找到过时文章时参考此处的内容。 diff --git a/docs/content/doc/usage/actions/quickstart.en-us.md b/docs/content/doc/usage/actions/quickstart.en-us.md deleted file mode 100644 index 829f1a62c0..0000000000 --- a/docs/content/doc/usage/actions/quickstart.en-us.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -date: "2023-04-27T15:00:00+08:00" -title: "Quick Start" -slug: "quickstart" -weight: 10 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "Quick Start" - weight: 10 - identifier: "actions-quickstart" ---- - -# Quick Start - -This page will guide you through the process of using Gitea Actions. - -**Table of Contents** - -{{< toc >}} - -## Set up Gitea - -First of all, you need a Gitea instance. -You can follow the [documentation]({{< relref "doc/installation/from-package.en-us.md" >}}) to set up a new instance or upgrade your existing one. -It doesn't matter how you install or run Gitea, as long as its version is 1.19.0 or higher. - -Actions are disabled by default, so you need to add the following to the configuration file to enable it: - -```ini -[actions] -ENABLED=true -``` - -If you want to learn more or encounter any problems while configuring it, please refer to the [Configuration Cheat Sheet]({{< relref "doc/administration/config-cheat-sheet.en-us.md#actions-actions" >}}). - -### Set up runner - -Gitea Actions requires [act runner](https://gitea.com/gitea/act_runner) to run the jobs. -In order to avoid consuming too many resources and affecting the Gitea instance, it is recommended to start runners on separate machines from the Gitea instance. - -You can use the [pre-built binaries](http://dl.gitea.com/act_runner) or the [docker images](https://hub.docker.com/r/gitea/act_runner/tags) to set up the runner. - -Before proceeding any further, we suggest running it as a command line with pre-built binaries to ensure that it works with your environment, especially if you are running a runner on your local host. -And it could be easier to debug if something goes wrong. - -The runner can run the jobs in isolated Docker containers, so you need to make sure that the Docker has been installed and Docker daemon is running. -While it is not strictly necessary, because the runner can also run the jobs directly on the host, it depends on how you configure it. -However, it is recommended to use Docker to run the jobs, because it is more secure and easier to manage. - -Before running a runner, you should first register it to your Gitea instance using the following command: - -```bash -./act_runner register --no-interactive --instance <instance> --token <token> -``` - -There are two arguments required, `instance` and `token`. - -`instance` refers to the address of your Gitea instance, like `http://192.168.8.8:3000` or `https://gitea.com`. -The runner and job containers (which are started by the runner to execute jobs) will connect to this address. -This means that it could be different from the `ROOT_URL` of your Gitea instance, which is configured for web access. -It is always a bad idea to use a loopback address such as `127.0.0.1` or `localhost`. -If you are unsure which address to use, the LAN address is usually the right choice. - -`token` is used for authentication and identification, such as `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`. -It is one-time use only and cannot be used to register multiple runners. -You can obtain different levels of 'tokens' from the following places to create the corresponding level of' runners': - -- Instance level: The admin settings page, like `<your_gitea.com>/admin/actions/runners`. -- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`. -- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`. - - - -After registering, a new file named `.runner` will appear in the current directory. -This file stores the registration information. -Please do not edit it manually. -If this file is missing or corrupted, you can simply remove it and register again. - -Finally, it's time to start the runner: - -```bash -./act_runner daemon -``` - -And you can see the new runner in the management page: - - - -You can find more information by visiting [Act runner]({{< relref "doc/usage/actions/act-runner.en-us.md" >}}). - -### Use Actions - -Even if Actions is enabled for the Gitea instance, repositories still disable Actions by default. - -To enable it, go to the settings page of your repository like `your_gitea.com/<owner>/repo/settings` and enable `Enable Repository Actions`. - - - -The next steps may be rather complicated. -You will need to study [the workflow syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) for Actions and write the workflow files you want. - -However, we can just start from a simple demo: - -```yaml -name: Gitea Actions Demo -run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀 -on: [push] - -jobs: - Explore-Gitea-Actions: - runs-on: ubuntu-latest - steps: - - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event." - - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!" - - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}." - - name: Check out repository code - uses: actions/checkout@v3 - - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner." - - run: echo "🖥️ The workflow is now ready to test your code on the runner." - - name: List files in the repository - run: | - ls ${{ gitea.workspace }} - - run: echo "🍏 This job's status is ${{ job.status }}." -``` - -You can upload it as a file with the extension `.yaml` in the directory `.gitea/workflows/` of the repository, for example `.gitea/workflows/demo.yaml`. -You might notice that this is fairly similar from the [Quickstart for GitHub Actions](https://docs.github.com/en/actions/quickstart). -That is because Gitea Actions is designed to be compatible with GitHub Actions wherever possible. - -Be careful, the demo file contains some emojis. -Please make sure your database supports them, especially when using MySQL. -If the charset is not `utf8mb4`, errors will occur, such as `Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`. -See [Database Preparation]({{< relref "doc/installation/database-preparation.en-us.md#mysql" >}}) for more information. - -Alternatively, you can remove all emojis from the demo file and try again. - -The line `on: [push]` indicates that the workflow will be triggered when you push commits to this repository. -However, when you upload the YAML file, it also pushes a commit, so you should see a new task in the Actions tab. - - - -Great job! You have successfully started working with Actions. diff --git a/docs/content/doc/usage/actions/quickstart.zh-cn.md b/docs/content/doc/usage/actions/quickstart.zh-cn.md deleted file mode 100644 index 1893300b61..0000000000 --- a/docs/content/doc/usage/actions/quickstart.zh-cn.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -date: "2023-05-24T15:00:00+08:00" -title: "快速入门" -slug: "quickstart" -weight: 10 -draft: false -toc: false -menu: - sidebar: - parent: "actions" - name: "快速入门" - weight: 10 - identifier: "actions-quickstart" ---- - -# 快速入门 - -本页面将指导您使用Gitea Actions的过程。 - -**目录** - -{{< toc >}} - -## 设置Gitea - -首先，您需要一个Gitea实例。 -您可以按照[文档]({{< relref "doc/installation/from-package.zh-cn.md" >}}) 来设置一个新实例或升级现有实例。 -无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。 - -默认情况下，Actions是禁用的，因此您需要将以下内容添加到配置文件中以启用它： - -```ini -[actions] -ENABLED=true -``` - -如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#actions-actions" >}})。 - -### 设置Runner - -Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。 -为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。 - -您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。 - -在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。 -如果出现问题，这样调试起来会更容易。 - -该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。 -虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。 -然而，建议使用Docker运行Job，因为它更安全且更易于管理。 - -在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中： - -```bash -./act_runner register --no-interactive --instance <instance> --token <token> -``` - -需要两个必需的参数：`instance` 和 `token`。 - -`instance`是您的Gitea实例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。 -Runner和Job容器（由Runner启动以执行Job）将连接到此地址。 -这意味着它可能与用于Web访问的`ROOT_URL`不同。 -使用回环地址（例如 `127.0.0.1` 或 `localhost`）是一个不好的选择。 -如果不确定使用哪个地址，通常选择局域网地址即可。 - -`token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。 -它只能使用一次，并且不能用于注册多个Runner。 -您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner` - -- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。 -- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。 -- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。 - - - -注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。 -请不要手动编辑该文件。 -如果该文件丢失或损坏，只需删除它然后重新注册即可。 - -最后，是时候启动Runner了： - -```bash -./act_runner daemon -``` - -您可以在管理页面上看到新的Runner： - - - -您可以通过访问[act runner]({{< relref "doc/usage/actions/act-runner.zh-cn.md" >}}) 获取更多信息。 - -### 使用Actions - -即使对于启用了Gitea实例的Actions，存储库仍默认禁用Actions。 - -要启用它，请转到存储库的设置页面，例如`your_gitea.com/<owner>/repo/settings`，然后启用`Enable Repository Actions`。 - - - -接下来的步骤可能相当复杂。 -您需要学习Actions的[工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，并编写您想要的工作流文件。 - -不过，我们可以从一个简单的演示开始： - -```yaml -name: Gitea Actions Demo -run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀 -on: [push] - -jobs: - Explore-Gitea-Actions: - runs-on: ubuntu-latest - steps: - - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event." - - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!" - - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}." - - name: Check out repository code - uses: actions/checkout@v3 - - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner." - - run: echo "🖥️ The workflow is now ready to test your code on the runner." - - name: List files in the repository - run: | - ls ${{ gitea.workspace }} - - run: echo "🍏 This job's status is ${{ job.status }}." -``` - -您可以将上述示例上传为一个以`.yaml`扩展名的文件，放在存储库的`.gitea/workflows/`目录中，例如`.gitea/workflows/demo.yaml`。 -您可能会注意到，这与[GitHub Actions的快速入门](https://docs.github.com/en/actions/quickstart)非常相似。 -这是因为Gitea Actions在尽可能兼容GitHub Actions的基础上进行设计。 - -请注意，演示文件中包含一些表情符号。 -请确保您的数据库支持它们，特别是在使用MySQL时。 -如果字符集不是`utf8mb4，将出现错误，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。 -有关更多信息，请参阅[数据库准备工作]({{< relref "doc/installation/database-preparation.zh-cn.md#mysql" >}})。 - -或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。 - -`on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。 -然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。 - - - -做得好！您已成功开始使用Actions。 diff --git a/docs/content/doc/usage/agit-support.en-us.md b/docs/content/doc/usage/agit-support.en-us.md deleted file mode 100644 index 30e2879e89..0000000000 --- a/docs/content/doc/usage/agit-support.en-us.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -date: " 2022-09-01T20:50:42+0000" -title: "Agit Setup" -slug: "agit-setup" -weight: 12 -toc: false -draft: false -aliases: - - /en-us/agit-setup -menu: - sidebar: - parent: "usage" - name: "Agit Setup" - weight: 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" -``` diff --git a/docs/content/doc/usage/agit-support.zh-cn.md b/docs/content/doc/usage/agit-support.zh-cn.md deleted file mode 100644 index de6eba24b2..0000000000 --- a/docs/content/doc/usage/agit-support.zh-cn.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "Agit 设置" -slug: "agit-setup" -weight: 12 -toc: false -draft: false -aliases: - - /zh-cn/agit-setup -menu: - sidebar: - parent: "usage" - name: "Agit 设置" - weight: 12 - identifier: "agit-setup" ---- - -# Agit 设置 - -在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。 - -## 使用 Agit 创建 PR - -Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。 -通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。 -下面的示例说明了这一点： - -```shell -git push origin HEAD:refs/for/master -``` - -该命令的结构如下： - -- `HEAD`：目标分支 -- `refs/<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" -``` diff --git a/docs/content/doc/usage/authentication.en-us.md b/docs/content/doc/usage/authentication.en-us.md deleted file mode 100644 index d9648200ef..0000000000 --- a/docs/content/doc/usage/authentication.en-us.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Authentication" -slug: "authentication" -weight: 10 -toc: false -draft: false -aliases: - - /en-us/authentication -menu: - sidebar: - parent: "usage" - name: "Authentication" - weight: 10 - identifier: "authentication" ---- - -# Authentication - -{{< toc >}} - -## 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 `%[1]s` matching parameter will be substituted with login - name given on sign-in form. - - Example: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]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 `%[1]s` - matching parameter will be substituted with login name given on sign-in - form. - - Example: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))` - - Example: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]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. diff --git a/docs/content/doc/usage/authentication.zh-cn.md b/docs/content/doc/usage/authentication.zh-cn.md deleted file mode 100644 index bef78ba649..0000000000 --- a/docs/content/doc/usage/authentication.zh-cn.md +++ /dev/null @@ -1,293 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "认证" -slug: "authentication" -weight: 10 -toc: false -draft: false -aliases: - - /zh-cn/authentication -menu: - sidebar: - parent: "usage" - name: "认证" - weight: 10 - identifier: "authentication" ---- - -# 认证 - -## 轻量级目录访问协议（Lightweight Directory Access Protocol，LDAP） - -通过BindDN的LDAP和简单认证方式LDAP共享以下字段: - -- 认证名称 **(必选)** - - - 分配给新授权方法的名称。 - -- 主机名 **(必选)** - - - LDAP 服务的主机地址. - - 例如:`mydomain.com` - -- 端口号 **(必选)** - - - LDAP 服务的端口号. - - 例如: LDAP `389`/ LDAPs `636` - -- 安全协议 (可选) - - 连接LDAP服务器时是否使用TLS协议。 - -- 管理员过滤规则 (可选) - - 一个LDAP过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。 - - 示例:`(objectClass=adminAccount)` - - 适用于Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org` - -- 用户名属性（可选） - - - 用户LDAP记录中包含用户名称的属性。在第一次成功登录后，将使用指定的属性值作为新的Gitea账户用户名。若留空，则使用登录表单上提供的用户名。 - - 当提供的登录名与多个属性匹配时，这一选项非常有用，但是只有一个特定属性应该用于Gitea账户名称，请参阅"用户过滤器"。 - - 示例:uid - - 适用于Microsoft Active Directory（AD）的示例:`sAMAccountName` - -- 名字属性（可选） - - - 用户LDAP记录中包含用户名字的属性。将用于填充他们的账户信息。 - - 示例:givenName -- 姓氏属性（可选） - - 用户LDAP记录中包含用户姓氏的属性。将用于填充他们的账户信息。 - - 示例:`sn` - -- 电子邮件属性 **(必选)** - - 用户LDAP记录中包含用户电子邮件地址的属性。将用于填充他们的账户信息。 - - 示例:`mail` - -### LDAP(via BindDN) - -需要额外设置以下字段: - -- 绑定DN (可选) - - - 搜索用户时绑定到LDAP服务器的DN。这可以留空以执行匿名搜索。 - - 示例: `cn=Search,dc=mydomain,dc=com` - -- 绑定密码 (可选) - - - 上述指定的Bind DN（绑定区别名）的密码，如果有的话。注意：该密码在服务器上使用SECRET_KEY进行加密存储。仍然建议确保Bind DN具有尽可能少的权限。 - -- 用户搜索基准 **(必选)** - - - 这是用于搜索用户帐户的LDAP基础路径. - - 示例: `ou=Users,dc=mydomain,dc=com` - -- 用户过滤规则 **(必选)** - - LDAP 过滤器声明如何查找试图进行身份验证的用户记录 - `%[1]s`匹配参数将替换为登录表单中给出的登录名 - - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))` - - 示例 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)))` - - 如需多次替换，应使用 `%[1]s`，例如在将提供的登录名与多个属性（如用户标识符、电子邮件甚至电话号码）进行匹配时。 - - 示例: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))` -- 启用用户同步 - - 这个选项启用了一个周期性任务，用于将Gitea用户与LDAP服务器进行同步。默认的同步周期是每24小时， - 但您可以在app.ini文件中进行更改。 - 有关此部分的详细说明，请参阅[sample - app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini) - 的_cron.sync_external_users_ 部分的注释。前面提到的_User Search Base_和_User Filter_ - 设置将限制哪些用户可以使用Gitea以及哪些用户将被同步。 - 在初始运行任务时，将根据给定的设置创建所有与LDAP匹配的用户，因此在使用大型企业LDAP目录时需要小心。 - -### LDAP(simple auth) - -需要额外设置以下字段: - -- 用户DN **(必选)** - - - 用作用户 DN 的模板。匹配参数 `%s` 将替换为登录表单中的登录名。 - - 示例: `cn=%s,ou=Users,dc=mydomain,dc=com` - - 示例: `uid=%s,ou=Users,dc=mydomain,dc=com` - -- 用户搜索基准 (可选) - - - 用户搜索基准声明哪些用户帐户将被搜索. - - 示例: `ou=Users,dc=mydomain,dc=com` - -- 用户过滤规则 **(必选)** - - LDAP 过滤器声明何时允许用户登录 - `%[1]s`匹配参数将替换为登录表单中给出的登录名。 - - 示例: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))` - - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))` - -### 使用LDAP验证分组成员 - -使用以下字段: - -- 群组搜索基础DN(可选) - - 组使用的 LDAP DN。 - - 示例: `ou=group,dc=mydomain,dc=com` - -- 组名过滤器 (可选) - - - LDAP 过滤器，声明如何在上述 DN 中查找有效组。 - - 示例: `(|(cn=gitea_users)(cn=admins))` - -- 组中的用户属性 (可选) - - - 组中列出了哪个用户的 LDAP 属性。 - - 示例: `uid` - -- 用户组属性 (可选) - - 哪个组的 LDAP 属性包含一个高于用户属性名称的数组。 - - 示例: `memberUid` - -## 可插拔式认证模块(Pluggable Authentication Module,PAM) - -这个过程启用了PAM（Pluggable Authentication Modules）认证。用户仍然可以通过用户管理手动添加到系统中。 -PAM提供了一种机制，通过对用户进行PAM认证来自动将其添加到当前数据库中。为了与普通的Linux密码一起使用， -运行Gitea的用户还必须具有对`/etc/shadow`的读取权限，以便在使用公钥登录时检查账户的有效性。 - -**注意**:如果用户已将SSH公钥添加到Gitea中，使用这些密钥可能会绕过登录检查系统。因此， -如果您希望禁用使用PAM进行身份验证的用户，应该在Gitea中手动禁用该账户，使用内置的用户管理功能。 - -1. 配置和安装准备. - - 建议您创建一个管理用户. - - 建议取消自动注册. -1. 一旦数据库已初始化完成，使用新创建的管理员账户登录. -1. 导航至用户设置（右上角的图标），然后选择 -`Site Administration` -> `Authentication Sources`, 并选择 -`Add Authentication Source`. -1. 填写字段如下: - - 认证类型:`PAM`。 - - 名称:任何有效的值都可以，如果您愿意，可以使用"System Authentication"。 - - PAM服务名称:从/etc/pam.d/目录下选择适用于所需认证的正确文件[^1]。 - - PAM电子邮件域:用户认证时要附加的电子邮件后缀。例如，如果登录系统期望一个名为gituse的用户， - 并且将此字段设置为mail.com，那么Gitea在验证一个GIT实例的用户时将期望user emai字段为gituser@mail.com[^2]。 - -**Note**: PAM 支持通过[build-time flags](https://docs.gitea.io/en-us/install-from-source/#build)添加, -而官方提供的二进制文件通常不会默认启用此功能。PAM需要确保系统上有必要的libpam动态库，并且编译器可以访问必要的PAM开发头文件。 - -[^1]: 例如，在Debian "Bullseye"上使用标准Linux登录，可以使用`common-session-noninteractive`。这个值对于其他版本的Debian， -包括Ubuntu和Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。 - -[^2]: **PAM的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`gituser@mail.com`登录到Gitea的Web界面。 - -## 简单邮件传输协议(Simple Mail Transfer Protocol,SMTP) - -此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。请设置以下字段: - -- 身份验证名称 **(必选)** - - 分配给新授权方法的名称 - -- SMTP 验证类型 **(必选)** - - 用于连接 SMTP 主机的验证类型，plain 或 login - -- 主机名 **(必选)** - - - SMTP 服务的主机地址 - - 例如:`smtp.mydomain.com` - -- 端口号 **(必选)** - - - SMTP 服务的端口号 - - 例如: `587` - -- 允许的域名 - - - 如果使用公共 SMTP 主机或有多个域的 SMTP 主机，限制哪些域可以登录 - 限制哪些域可以登录。 - - 示例: `gitea.io,mydomain.com,mydomain2.com` - -- 强制使用 SMTPS - - 默认情况下将使用SMTPS连接到端口465.如果您希望将smtp用于其他端口，自行设置 - - 否则，如果服务器提供' STARTTLS '扩展名，则将使用此扩展名 -- 跳过 TLS 验证 - - 禁用 TLS 验证身份. -- 该认证源处于激活状态 - - 启用或禁用此身份验证源 - -## FreeIPA - -- 要使用 FreeIPA 凭据登录 Gitea，需要为 Gitea 创建一个绑定帐户。 - 创建一个绑定帐户: -- 在FreeIPA服务器上创建一个gitea.ldif文件，并将`dc=example,dc=com`替换为您的`dn`，然后提供一个适当安全的密码。 - - ```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 - ``` - -- 导入LDIF文件（如果需要，请将localhost更改为IPA服务器）。系统会提示您输入Directory Manager的密码。: - - ```sh - ldapmodify -h localhost -p 389 -x -D \ - "cn=Directory Manager" -W -f gitea.ldif - ``` - -- 为`gitea_users`添加IPA组: - - ```sh - ipa group-add --desc="Gitea Users" gitea_users - ``` - -- **提示**:对于IPA凭证错误，运行' kinit admin '并提供域管理帐户密码. -- 以管理员身份登录Gitea，点击Admin Panel下的`Authentication`。然后单击`Add New Source`并填写详细信息，更改所有适当的地方。 - -## SPNEGO with SSPI (Kerberos/NTLM, for Windows only) - -Gitea支持通过Windows内置的安全支持提供程序接口（Security Support Provider Interface，SSPI）实现SPNEGO单点登录认证（由RFC4559定义的方案），用于服务器的Web部分。SSPI仅在Windows环境中工作，即当服务器和客户端都在Windows操作系统上运行时。 - -在激活SSPI单点登录认证（SSO）之前，您需要准备您的环境: - -- 在Active Directory中创建一个单独的用户账户，gitea.exe 进程将在该账户下运行（例如，在domain.local域下创建一个名为user的账户: -- 为运行gitea.exe的主机创建一个服务主体名称（Service Principal Name，SPN），其类别为HTTP: - - - 以特权域用户（例如域管理员）的身份启动“命令提示符”或“PowerShell”。 - - 运行下面的命令，将host.domain.local替换为Web应用程序将运行的服务器的完全限定域名（FQDN），将domain\user替换为在前一步中创建的账户名称: - - ```sh - setspn -A HTTP/host.domain.local domain\user - ``` - -在遵循上述步骤之前，请确保您按照以下流程进行操作: - -1. 用之前创建的用户登录（如果已经登录，请先注销）。 -2. 确保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`设置为Web应用程序将运行的服务器的完全限定域名（FQDN），与之前创建服务主体名称时使用的一致（例如，`host.domain.local`）。 -3. 启动Web服务器（运行 `gitea.exe web`）。 -4. 在 `Site Administration -> Authentication Sources` 中添加一个 `SPNEGO with SSPI` 认证源，以启用SSPI认证。 -5. 在域中的客户端计算机上，使用任何域用户登录（与运行`gitea.exe`的服务器不同）。 -6. 如果您使用Chrome或Edge浏览器，请将Web应用程序的URL添加到“本地站点”（`Internet选项 -> 安全 -> 本地站点 -> 站点`）。 -7. 启动Chrome或Edge浏览器，导航到Gitea的FQDN URL（例如，`http://host.domain.local:3000`）。 -8. 在控制面板中点击“Sign In”按钮，然后选择SSPI，将会自动使用当前登录到计算机的用户进行登录。 -9. 如果无法正常工作，请确保: - - 您不是在运行`gitea.exe`的同一台服务器上运行Web浏览器。应该在与服务器不同的域加入计算机（客户端）上运行Web浏览器。如果客户端和服务器都在同一台计算机上运行，则NTLM将优先于Kerberos。 - - 主机上只有一个`HTTP/...`的SPN。 - - SPN中只包含主机名，不包含端口号。 - - 将Web应用程序的URL添加到"本地站点"。 - - 服务器和客户端的时钟差异不超过5分钟（取决于组策略）。 - - 在Internet Explorer中启用了"集成Windows身份验证"（在"高级设置"下）。 - -遵循这些步骤，您应该能够成功启用和使用SSPI单点登录认证（SSO）。 - -## 反向代理认证 - -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 来进行认证。 diff --git a/docs/content/doc/usage/authentication.zh-tw.md b/docs/content/doc/usage/authentication.zh-tw.md deleted file mode 100644 index 75959802b1..0000000000 --- a/docs/content/doc/usage/authentication.zh-tw.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "認證" -slug: "authentication" -weight: 10 -toc: false -draft: false -aliases: - - /zh-tw/authentication -menu: - sidebar: - parent: "usage" - name: "認證" - weight: 10 - identifier: "authentication" ---- - -# 認證 - -## TBD diff --git a/docs/content/doc/usage/clone-filter.en-us.md b/docs/content/doc/usage/clone-filter.en-us.md deleted file mode 100644 index 8331c138bf..0000000000 --- a/docs/content/doc/usage/clone-filter.en-us.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -date: "2021-02-02" -title: "Clone filters (partial clone)" -slug: "clone-filters" -weight: 25 -draft: false -toc: false -aliases: - - /en-us/clone-filters -menu: - sidebar: - parent: "usage" - name: "Clone filters" - weight: 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). diff --git a/docs/content/doc/usage/clone-filter.zh-cn.md b/docs/content/doc/usage/clone-filter.zh-cn.md deleted file mode 100644 index fc174fcb38..0000000000 --- a/docs/content/doc/usage/clone-filter.zh-cn.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "克隆过滤器 (部分克隆)" -slug: "clone-filters" -weight: 25 -draft: false -toc: false -aliases: - - /zh-cn/clone-filters -menu: - sidebar: - parent: "usage" - name: "克隆过滤器" - weight: 25 - identifier: "clone-filters" ---- - -# 克隆过滤器 (部分克隆) - -Git 引入了 `--filter` 选项用于 `git clone` 命令，该选项可以过滤掉大文件和对象（如 blob），从而创建一个仓库的部分克隆。克隆过滤器对于大型仓库和/或按流量计费的连接特别有用，因为完全克隆（不使用 `--filter`）可能会很昂贵（需要下载所有历史数据）。 - -这需要 Git 2.22 或更高版本，无论是在 Gitea 服务器上还是在客户端上都需要如此。为了使克隆过滤器正常工作，请确保客户端上的 Git 版本至少与服务器上的版本相同（或更高）。以管理员身份登录到 Gitea，然后转到管理后台 -> 应用配置，查看服务器的 Git 版本。 - -默认情况下，克隆过滤器是启用的，除非在 `[git]` 下将 `DISABLE_PARTIAL_CLONE` 设置为 `true`。 - -请参阅 [GitHub 博客文章：了解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以获取克隆过滤器的常见用法（无 Blob 和无树的克隆），以及 [GitLab 部分克隆文档](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以获取更高级的用法（例如按文件大小过滤和取消过滤以将部分克隆转换为完全克隆）。 diff --git a/docs/content/doc/usage/code-owners.en-us.md b/docs/content/doc/usage/code-owners.en-us.md deleted file mode 100644 index 94f81eeae1..0000000000 --- a/docs/content/doc/usage/code-owners.en-us.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -date: "2023-05-24T16:00:00+00:00" -title: "Code Owners" -slug: "code-owners" -weight: 30 -toc: false -draft: false -aliases: - - /en-us/code-owners -menu: - sidebar: - parent: "usage" - name: "Code Owners" - weight: 30 - identifier: "code-owners" ---- - -# Code Owners - -Gitea maintains code owner files. It looks for it in the following locations in this order: - -- `./CODEOWNERS` -- `./docs/CODEOWNERS` -- `./.gitea/CODEOWNERS` - -And stops at the first found file. - -File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...` - -Regexp specified in golang Regex format. -Regexp can start with `!` for negative rules - match all files except specified. - -Example file: - -``` -.*\\.go @user1 @user2 # This is comment - -# Comment too -# You can assigning code owning for users or teams -frontend/src/.*\\.js @org1/team1 @org1/team2 @user3 - -# You can use negative pattern -!frontend/src/.* @org1/team3 @user5 - -# You can use power of go regexp -docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4 -!/assets/.*\\.(bin|exe|msi) @user9 -``` - -### Escaping - -You can escape characters `#`, ` ` (space) and `\` with `\`, like: - -``` -dir/with\#hashtag @user1 -path\ with\ space @user2 -path/with\\backslash @user3 -``` - -Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like: - -``` -path/\\.with\\.dots -path/with\\+plus -``` diff --git a/docs/content/doc/usage/incoming-email.en-us.md b/docs/content/doc/usage/incoming-email.en-us.md deleted file mode 100644 index 205b3dd8ed..0000000000 --- a/docs/content/doc/usage/incoming-email.en-us.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -date: "2022-12-01T00:00:00+00:00" -title: "Incoming Email" -slug: "incoming-email" -weight: 13 -draft: false -toc: false -aliases: - - /en-us/incoming-email -menu: - sidebar: - parent: "usage" - name: "Incoming Email" - weight: 13 - identifier: "incoming-email" ---- - -# Incoming Email - -Gitea supports the execution of several actions through incoming mails. This page describes how to set this up. - -**Table of Contents** - -{{< toc >}} - -## 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`. diff --git a/docs/content/doc/usage/incoming-email.zh-cn.md b/docs/content/doc/usage/incoming-email.zh-cn.md deleted file mode 100644 index 335e6aa9e2..0000000000 --- a/docs/content/doc/usage/incoming-email.zh-cn.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "邮件接收" -slug: "incoming-email" -weight: 13 -draft: false -toc: false -aliases: - - /zh-cn/incoming-email -menu: - sidebar: - parent: "usage" - name: "邮件接收" - weight: 13 - identifier: "incoming-email" ---- - -# 邮件接收 - -Gitea 支持通过接收邮件执行多种操作。本页面描述了如何进行设置。 - -**目录** - -{{< toc >}} - -## 要求 - -处理接收的电子邮件需要启用 IMAP 功能的电子邮件帐户。 -推荐的策略是使用 [电子邮件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 邮箱。 -接收电子邮件地址中包含一个用户/操作特定的令牌，告诉 Gitea 应执行哪个操作。 -此令牌应该出现在 `To` 和 `Delivered-To` 头字段中。 - -Gitea 会尝试检测自动回复并跳过它们，电子邮件服务器也应该配置以减少接收到的干扰（垃圾邮件、通讯订阅等）。 - -## 配置 - -要激活处理接收的电子邮件消息功能，您需要在配置文件中配置 `email.incoming` 部分。 - -`REPLY_TO_ADDRESS` 包含电子邮件客户端将要回复的地址。 -该地址需要包含 `%{token}` 占位符，该占位符将被替换为描述用户/操作的令牌。 -此占位符在地址中只能出现一次，并且必须位于地址的用户部分（`@` 之前）。 - -使用电子邮件子地址的示例可能如下：`incoming+%{token}@example.com` - -如果使用 catch-all 邮箱，则占位符可以出现在地址的用户部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com` - -## 安全性 - -在选择用于接收传入电子邮件的域时要小心。 -建议在子域名上接收传入电子邮件，例如 `incoming.example.com`，以防止与运行在 `example.com` 上的其他服务可能存在的安全问题。 diff --git a/docs/content/doc/usage/issue-pull-request-templates.en-us.md b/docs/content/doc/usage/issue-pull-request-templates.en-us.md deleted file mode 100644 index b48763cf8e..0000000000 --- a/docs/content/doc/usage/issue-pull-request-templates.en-us.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -date: "2018-05-10T16:00:00+02:00" -title: "Issue and Pull Request templates" -slug: "issue-pull-request-templates" -weight: 15 -toc: false -draft: false -aliases: - - /en-us/issue-pull-request-templates -menu: - sidebar: - parent: "usage" - name: "Issue and Pull Request templates" - weight: 15 - identifier: "issue-pull-request-templates" ---- - -# Issue and Pull Request Templates - -**Table of Contents** - -{{< toc >}} - -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 issue config: - -- `.gitea/ISSUE_TEMPLATE/config.yaml` -- `.gitea/ISSUE_TEMPLATE/config.yml` -- `.gitea/issue_template/config.yaml` -- `.gitea/issue_template/config.yml` -- `.github/ISSUE_TEMPLATE/config.yaml` -- `.github/ISSUE_TEMPLATE/config.yml` -- `.github/issue_template/config.yaml` -- `.github/issue_template/config.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 | - | - -## Syntax for issue config - -This is a example for a issue config file - -```yaml -blank_issues_enabled: true -contact_links: - - name: Gitea - url: https://gitea.io - about: Visit the Gitea Website -``` - -### Possible Options - -| Key | Description | Type | Default | -|----------------------|-------------------------------------------------------------------------------------------------------|--------------------|----------------| -| blank_issues_enabled | If set to false, the User is forced to use a Template | Boolean | true | -| contact_links | Custom Links to show in the Choose Box | Contact Link Array | Empty Array | - -### Contact Link - -| Key | Description | Type | Required | -|----------------------|-------------------------------------------------------------------------------------------------------|---------|----------| -| name | the name of your link | String | true | -| url | The URL of your Link | String | true | -| about | A short description of your Link | String | true | diff --git a/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md b/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md deleted file mode 100644 index fa5b37126f..0000000000 --- a/docs/content/doc/usage/issue-pull-request-templates.zh-cn.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -date: "2022-09-07T16:00:00+08:00" -title: "工单与合并请求模板" -slug: "issue-pull-request-templates" -weight: 15 -toc: true -draft: false -aliases: - - /zh-cn/issue-pull-request-templates -menu: - sidebar: - parent: "usage" - name: "工单与合并请求模板" - weight: 15 - identifier: "issue-pull-request-templates" ---- - -# 从模板创建工单与合并请求 - -开发者可以利用问题模板创建工单与合并请求，其目的在于规范参与者的语言表达。 - -**目录** - -{{< toc >}} - -## 模板介绍 - -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 | - | diff --git a/docs/content/doc/usage/labels.en-us.md b/docs/content/doc/usage/labels.en-us.md deleted file mode 100644 index 8467f7e037..0000000000 --- a/docs/content/doc/usage/labels.en-us.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -date: "2023-03-04T19:00:00+00:00" -title: "Labels" -slug: "labels" -weight: 13 -toc: false -draft: false -aliases: - - /en-us/labels -menu: - sidebar: - parent: "usage" - name: "Labels" - weight: 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](../administration/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. diff --git a/docs/content/doc/usage/labels.zh-cn.md b/docs/content/doc/usage/labels.zh-cn.md deleted file mode 100644 index 07dd2bf854..0000000000 --- a/docs/content/doc/usage/labels.zh-cn.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "标签" -slug: "labels" -weight: 13 -toc: false -draft: false -aliases: - - /zh-cn/labels -menu: - sidebar: - parent: "usage" - name: "标签" - weight: 13 - identifier: "labels" ---- - -# 标签 - -您可以使用标签对工单和合并请求进行分类，并提高对它们的概览。 - -## 创建标签 - -对于仓库，可以在 `工单（Issues）` 中点击 `标签（Labels）` 来创建标签。 - -对于组织，您可以定义组织级别的标签，这些标签与所有组织仓库共享，包括已存在的仓库和新创建的仓库。可以在组织的 `设置（Settings）` 中创建组织级别的标签。 - -标签具有必填的名称和颜色，可选的描述，以及必须是独占的或非独占的（见下面的“作用域标签”）。 - -当您创建一个仓库时，可以通过使用 `工单标签（Issue Labels）` 选项来选择标签集。该选项列出了一些在您的实例上 [全局配置的可用标签集](../administration/customizing-gitea/#labels)。在创建仓库时，这些标签也将被创建。 - -## 作用域标签 - -作用域标签用于确保将至多一个具有相同作用域的标签分配给工单或合并请求。例如，如果标签 `kind/bug` 和 `kind/enhancement` 的独占选项被设置，那么工单只能被分类为 bug 或 enhancement 中的一个。 - -作用域标签的名称必须包含 `/`（不能在名称的任一端）。标签的作用域是基于最后一个 `/` 决定的，因此例如标签 `scope/subscope/item` 的作用域是 `scope/subscope`。 - -## 按标签筛选 - -工单和合并请求列表可以按标签进行筛选。选择多个标签将显示具有所有选定标签的工单和合并请求。 - -通过按住 alt 键并单击标签，可以将具有所选标签的工单和合并请求从列表中排除。 diff --git a/docs/content/doc/usage/linked-references.en-us.md b/docs/content/doc/usage/linked-references.en-us.md deleted file mode 100644 index 4e95193015..0000000000 --- a/docs/content/doc/usage/linked-references.en-us.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -date: "2019-11-21T17:00:00-03:00" -title: "Automatically Linked References" -slug: "automatically-linked-references" -weight: 15 -toc: false -draft: false -aliases: - - /en-us/automatically-linked-references -menu: - sidebar: - parent: "usage" - name: "Automatically Linked References" - weight: 15 - identifier: "automatically-linked-references" ---- - -# Automatically Linked References in Issues, Pull Requests and Commit Messages - -**Table of Contents** - -{{< toc >}} - -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 | - | A link to issue/pull 1234 in `User1/Repo1` | -| `!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` | -| `#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` | -| `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | -| `User1/Repo1#1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` | -| `User1/Repo1!1234` | no | - | A link to issue/pull 1234 in `User1/Repo1` | -| `User1/Repo1#1234` | yes | - | A link to _external issue_ 1234 for `User1/Repo1` | -| `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | -| `UserZ/RepoZ#1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` | -| `UserZ/RepoZ!1234` | - | no | A link to issue/pull 1234 in `UserZ/RepoZ` | -| `UserZ/RepoZ#1234` | - | yes | A link to _external issue_ 1234 for `UserZ/RepoZ` | -| `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 for `UserZ/RepoZ` | -| **Alphanumeric issue IDs:** | - | - | - | -| `AAA-1234` | yes | - | A link to _external issue_ `AAA-1234` for `User1/Repo1` | -| `!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | -| `User1/Repo1!1234` | yes | - | A link to _PR_ 1234 for `User1/Repo1` | -| _Not supported_ | - | yes | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` | -| `UserZ/RepoZ!1234` | - | yes | A link to _PR_ 1234 in `UserZ/RepoZ` | - -_The last section is for repositories with external issue trackers that use alphanumeric format._ - -_**-**: not applicable._ - -Note: automatic references between repositories with different types of issues (external vs. internal) are not fully supported -and may render invalid links. diff --git a/docs/content/doc/usage/linked-references.zh-cn.md b/docs/content/doc/usage/linked-references.zh-cn.md deleted file mode 100644 index e565847387..0000000000 --- a/docs/content/doc/usage/linked-references.zh-cn.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "自动链接引用" -slug: "automatically-linked-references" -weight: 15 -toc: false -draft: false -aliases: - - /zh-cn/automatically-linked-references -menu: - sidebar: - parent: "usage" - name: "自动链接引用s" - weight: 15 - identifier: "automatically-linked-references" ---- - -# 在工单、合并请求和提交消息中的自动链接引用 - -**目录** - -{{< toc >}} - -当发布工单、合并请求或评论时，文本描述会被解析以查找引用。这些引用将显示为工单视图中的链接，并且在某些情况下会触发特定的“操作”。 - -类似地，当列出提交消息时，它们也会被解析，并且当它们被推送到主分支时可以触发“操作”。 - -为了防止意外创建引用，对于引用的识别有一定的规则。例如，它们不应该包含在代码文本内部。它们还应该在周围的文本中合理清晰（例如，使用空格）。 - -## 用户、团队和组织提及 - -当找到形式为 `@username` 的文本，并且 `username` 与现有用户的名称匹配时，将创建一个“提及”引用。这将通过将文本更改为指向该用户个人资料的链接来显示，并根据被提及的用户是否具有访问内容所需的权限来可能创建通知。 - -示例： - -> [@John](#)，你能看一下这个吗？ - -对于团队和组织也是有效的： - -> [@Documenters](#)，我们需要为此进行规划。 -> [@CoolCompanyInc](#)，这个问题关系到我们所有人！ - -团队将在适当时收到邮件通知，但整个组织不会收到通知。 - -提交消息不会产生用户通知。 - -## 提交 - -可以使用提交的 SHA1 哈希或至少七个字符的一部分来引用提交。它们将显示为指向相应提交的链接。 - -示例： - -> 这个错误是在 [e59ff077](#) 中引入的 - -## 工单和合并请求 - -可以使用简单的符号 `#1234` 来创建对另一个工单或合并请求的引用，其中 _1234_ 是同一仓库中一个工单或合并请求的编号。这些引用将显示为指向被引用内容的链接。 - -创建此类型引用的效果是，在被引用的文档中创建一个“通知”，前提是引用的创建者对其具有读取权限。 - -示例： - -> 这似乎与 [#1234](#) 相关 - -还可以使用形式 `owner/repository#1234` 来引用其他仓库中的工单和合并请求： - -> 这似乎与 [mike/compiler#1234](#) 相关 - -或者也可以使用 `!1234` 符号。虽然在 Gitea 中合并请求是工单的一种形式，但 `#1234` 形式总是链接到工单；如果链接的条目恰好是一个合并请求，Gitea 会适当地进行重定向。而使用 `!1234` 符号，则会创建一个合并请求链接，根据需要会被重定向到工单。然而，如果使用外部跟踪器，这个区别可能很重要，因为工单和合并请求的链接是不能互换的。 - -## 可操作的引用在合并请求和提交消息中 - -有时，一个提交或合并请求可能会修复或重新出现在某个特定工单中。Gitea 支持在引用之前加上特定的“关键字”来关闭和重新打开被引用的工单。常见的关键字包括“closes”、“fixes”、“reopens”等。这个列表可以由站点管理员进行 [自定义]({{< ref "doc/administration/config-cheat-sheet.zh-cn.md" >}})。 - -示例： - -> 这个合并请求 _closes_ [#1234](#) - -如果可操作的引用被接受，这将在被引用的工单上创建一个通知，宣布当引用的合并请求被合并时该工单将被关闭。 - -为了接受可操作的引用，必须满足以下至少一项条件之一： - -- 评论者在创建引用时具有关闭或重新打开工单的权限。 -- 引用位于提交消息中。 -- 引用作为合并请求描述的一部分发布。 - -在最后一种情况下，只有当合并合并请求的人具有相应权限时，工单才会被关闭或重新打开。 - -此外，只有合并请求和提交消息可以创建一个操作，只有工单可以通过这种方式被关闭或重新打开。 - -默认的关键字如下： - -- **关闭工单**: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved -- **重新打开工单**: reopen, reopens, reopened - -## 合并请求和提交消息中的时间跟踪 - -当提交或合并合并请求导致自动关闭工单时，还可以通过提交消息添加解决此工单所花费的时间。 - -要指定解决工单所花费的时间，需要在工单编号后面以 `@<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. 内部）的仓库之间的自动引用，可能会导致无效链接。 diff --git a/docs/content/doc/usage/merge-message-templates.en-us.md b/docs/content/doc/usage/merge-message-templates.en-us.md deleted file mode 100644 index 03095a3bbe..0000000000 --- a/docs/content/doc/usage/merge-message-templates.en-us.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -date: "2022-08-31T17:35:40+08:00" -title: "Merge Message templates" -slug: "merge-message-templates" -weight: 15 -toc: false -draft: false -aliases: - - /en-us/merge-message-templates -menu: - sidebar: - parent: "usage" - name: "Merge Message templates" - weight: 15 - identifier: "merge-message-templates" ---- - -# Merge Message templates - -**Table of Contents** - -{{< toc >}} - -## 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` - -## Rebase - -When rebasing without a merge commit, `REBASE_TEMPLATE.md` modifies the message of the last commit. The following additional variables are available in this template: - -- CommitTitle: Commit's title -- CommitBody: Commits's body text diff --git a/docs/content/doc/usage/merge-message-templates.zh-cn.md b/docs/content/doc/usage/merge-message-templates.zh-cn.md deleted file mode 100644 index 0ec4eee483..0000000000 --- a/docs/content/doc/usage/merge-message-templates.zh-cn.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "合并消息模板" -slug: "merge-message-templates" -weight: 15 -toc: false -draft: false -aliases: - - /zh-cn/merge-message-templates -menu: - sidebar: - parent: "usage" - name: "合并消息模板" - weight: 15 - identifier: "merge-message-templates" ---- - -# 合并消息模板 - -**目录** - -{{< toc >}} - -## 文件名 - -PR 默认合并消息模板可能的文件名： - -- `.gitea/default_merge_message/MERGE_TEMPLATE.md` -- `.gitea/default_merge_message/REBASE_TEMPLATE.md` -- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md` -- `.gitea/default_merge_message/SQUASH_TEMPLATE.md` -- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md` -- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md` - -## 变量 - -您可以在这些模板中使用以下以 `${}` 包围的变量，这些变量遵循 [os.Expand](https://pkg.go.dev/os#Expand) 语法： - -- BaseRepoOwnerName：此合并请求的基础仓库所有者名称 -- BaseRepoName：此合并请求的基础仓库名称 -- BaseBranch：此合并请求的基础仓库目标分支名称 -- HeadRepoOwnerName：此合并请求的源仓库所有者名称 -- HeadRepoName：此合并请求的源仓库名称 -- HeadBranch：此合并请求的源仓库分支名称 -- PullRequestTitle：合并请求的标题 -- PullRequestDescription：合并请求的描述 -- PullRequestPosterName：合并请求的提交者名称 -- PullRequestIndex：合并请求的索引号 -- PullRequestReference：合并请求的引用字符与索引号。例如，#1、!2 -- ClosingIssues：返回一个包含将由此合并请求关闭的所有工单的字符串。例如 `close #1, close #2` - -## 变基（Rebase） - -在没有合并提交的情况下进行变基时，`REBASE_TEMPLATE.md` 修改最后一次提交的消息。此模板还提供以下附加变量： - -- CommitTitle：提交的标题 -- CommitBody：提交的正文文本 diff --git a/docs/content/doc/usage/packages/_index.en-us.md b/docs/content/doc/usage/packages/_index.en-us.md deleted file mode 100644 index e69de29bb2..0000000000 --- a/docs/content/doc/usage/packages/_index.en-us.md +++ /dev/null diff --git a/docs/content/doc/usage/packages/alpine.en-us.md b/docs/content/doc/usage/packages/alpine.en-us.md deleted file mode 100644 index f7d2c66586..0000000000 --- a/docs/content/doc/usage/packages/alpine.en-us.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -date: "2023-03-25T00:00:00+00:00" -title: "Alpine Package Registry" -slug: "alpine" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Alpine" - weight: 4 - identifier: "alpine" ---- - -# Alpine Package Registry - -Publish [Alpine](https://pkgs.alpinelinux.org/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Alpine registry, you need to use a HTTP client like `curl` to upload and a package manager like `apk` to consume packages. - -The following examples use `apk`. - -## Configuring the package registry - -To register the Alpine registry add the url to the list of known apk sources (`/etc/apk/repositories`): - -``` -https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository> -``` - -| Placeholder | Description | -| ------------ | ----------- | -| `owner` | The owner of the packages. | -| `branch` | The branch to use. | -| `repository` | The repository to use. | - -If the registry is private, provide credentials in the url. You can use a password or a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}): - -``` -https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository> -``` - -The Alpine registry files are signed with a RSA key which must be known to apk. Download the public key and store it in `/etc/apk/keys/`: - -```shell -curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key -``` - -Afterwards update the local package index: - -```shell -apk update -``` - -## Publish a package - -To publish an Alpine package (`*.apk`), perform a HTTP `PUT` operation with the package content in the request body. - -``` -PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository} -``` - -| Parameter | Description | -| ------------ | ----------- | -| `owner` | The owner of the package. | -| `branch` | The branch may match the release version of the OS, ex: `v3.17`. | -| `repository` | The repository can be used [to group packages](https://wiki.alpinelinux.org/wiki/Repositories) or just `main` or similar. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.apk \ - https://gitea.example.com/api/packages/testuser/alpine/v3.17/main -``` - -If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. -You cannot publish a file with the same name twice to a package. You must delete the existing package file first. - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `201 Created` | The package has been published. | -| `400 Bad Request` | The package name, version, branch, repository or architecture are invalid. | -| `409 Conflict` | A package file with the same combination of parameters exist already in the package. | - -## Delete a package - -To delete an Alpine package perform a HTTP `DELETE` operation. This will delete the package version too if there is no file left. - -``` -DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename} -``` - -| Parameter | Description | -| -------------- | ----------- | -| `owner` | The owner of the package. | -| `branch` | The branch to use. | -| `repository` | The repository to use. | -| `architecture` | The package architecture. | -| `filename` | The file to delete. - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk -``` - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `204 No Content` | Success | -| `404 Not Found` | The package or file was not found. | - -## Install a package - -To install a package from the Alpine registry, execute the following commands: - -```shell -# use latest version -apk add {package_name} -# use specific version -apk add {package_name}={package_version} -``` diff --git a/docs/content/doc/usage/packages/alpine.zh-cn.md b/docs/content/doc/usage/packages/alpine.zh-cn.md deleted file mode 100644 index fd9470525d..0000000000 --- a/docs/content/doc/usage/packages/alpine.zh-cn.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -date: "2023-03-25T00:00:00+00:00" -title: "Alpine 软件包注册表" -slug: "alpine" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Alpine" - weight: 4 - identifier: "alpine" ---- - -# Alpine 软件包注册表 - -在您的用户或组织中发布 [Alpine](https://pkgs.alpinelinux.org/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Alpine 注册表，您需要使用像 curl 这样的 HTTP 客户端来上传包，并使用像 apk 这样的包管理器来消费包。 - -以下示例使用 `apk`。 - -## 配置软件包注册表 - -要注册 Alpine 注册表，请将 URL 添加到已知的 apk 源列表中 (`/etc/apk/repositories`): - -``` -https://gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository> -``` - -| 占位符 | 描述 | -| ------------ | -------------- | -| `owner` | 软件包所有者 | -| `branch` | 要使用的分支名 | -| `repository` | 要使用的仓库名 | - -如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}): - -``` -https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/alpine/<branch>/<repository> -``` - -Alpine 注册表文件使用 RSA 密钥进行签名，apk 必须知道该密钥。下载公钥并将其存储在 `/etc/apk/keys/` 目录中： - -```shell -curl -JO https://gitea.example.com/api/packages/{owner}/alpine/key -``` - -之后，更新本地软件包索引： - -```shell -apk update -``` - -## 发布软件包 - -要发布一个 Alpine 包（`*.apk`），请执行带有包内容的 HTTP `PUT` 操作，将其放在请求体中。 - -``` -PUT https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository} -``` - -| 参数 | 描述 | -| ------------ | --------------------------------------------------------------------------------------------------- | -| `owner` | 包的所有者。 | -| `branch` | 分支可以与操作系统的发行版本匹配，例如：v3.17。 | -| `repository` | 仓库可以用于[分组包](https://wiki.alpinelinux.org/wiki/Repositories) 或者只是 `main` 或类似的名称。 | - -使用 HTTP 基本身份验证的示例请求： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.apk \ - https://gitea.example.com/api/packages/testuser/alpine/v3.17/main -``` - -如果您使用的是双重身份验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#authentication" >}})代替密码。 -您不能将具有相同名称的文件两次发布到一个包中。您必须首先删除现有的包文件。 - -服务器将以以下的 HTTP 状态码响应： - -| HTTP 状态码 | 含义 | -| ----------------- | ------------------------------------------ | -| `201 Created` | 软件包已发布。 | -| `400 Bad Request` | 软件包的名称、版本、分支、仓库或架构无效。 | -| `409 Conflict` | 具有相同参数组合的包文件已存在于软件包中。 | - -## 删除软件包 - -要删除 Alpine 包，执行 HTTP 的 DELETE 操作。如果没有文件，这将同时删除包版本。 - -``` -DELETE https://gitea.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename} -``` - -| 参数 | 描述 | -| -------------- | -------------- | -| `owner` | 软件包的所有者 | -| `branch` | 要使用的分支名 | -| `repository` | 要使用的仓库名 | -| `architecture` | 软件包的架构 | -| `filename` | 要删除的文件名 | - -使用 HTTP 基本身份验证的示例请求： - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk -``` - -服务器将以以下的 HTTP 状态码响应： - -| HTTP 状态码 | 含义 | -| ---------------- | ------------------ | -| `204 No Content` | 成功 | -| `404 Not Found` | 未找到软件包或文件 | - -## 安装软件包 - -要从 Alpine 注册表安装软件包，请执行以下命令： - -```shell -# use latest version -apk add {package_name} -# use specific version -apk add {package_name}={package_version} -``` diff --git a/docs/content/doc/usage/packages/cargo.en-us.md b/docs/content/doc/usage/packages/cargo.en-us.md deleted file mode 100644 index d341eb9f83..0000000000 --- a/docs/content/doc/usage/packages/cargo.en-us.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -date: "2022-11-20T00:00:00+00:00" -title: "Cargo Package Registry" -slug: "cargo" -weight: 5 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Cargo" - weight: 5 - identifier: "cargo" ---- - -# Cargo Package Registry - -Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Cargo package registry, you need [Rust and Cargo](https://www.rust-lang.org/tools/install). - -Cargo stores information about the available packages in a package index stored in a git repository. -This repository is needed to work with the registry. -The following section describes how to create it. - -## Index Repository - -Cargo stores information about the available packages in a package index stored in a git repository. -In Gitea this repository has the special name `_cargo-index`. -After a package was uploaded, its metadata is automatically written to the index. -The content of this repository should not be manually modified. - -The user or organization package settings page allows to create the index repository along with the configuration file. -If needed this action will rewrite the configuration file. -This can be useful if for example the Gitea instance domain was changed. - -If the case arises where the packages stored in Gitea and the information in the index repository are out of sync, the settings page allows to rebuild the index repository. -This action iterates all packages in the registry and writes their information to the index. -If there are lot of packages this process may take some time. - -## Configuring the package registry - -To register the package registry the Cargo configuration must be updated. -Add the following text to the configuration file located in the current users home directory (for example `~/.cargo/config.toml`): - -``` -[registry] -default = "gitea" - -[registries.gitea] -index = "https://gitea.example.com/{owner}/_cargo-index.git" - -[net] -git-fetch-with-cli = true -``` - -| Parameter | Description | -| --------- | ----------- | -| `owner` | The owner of the package. | - -If the registry is private or you want to publish new packages, you have to configure your credentials. -Add the credentials section to the credentials file located in the current users home directory (for example `~/.cargo/credentials.toml`): - -``` -[registries.gitea] -token = "Bearer {token}" -``` - -| Parameter | Description | -| --------- | ----------- | -| `token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) | - -## Publish a package - -Publish a package by running the following command in your project: - -```shell -cargo publish -``` - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a package from the package registry, execute the following command: - -```shell -cargo add {package_name} -``` - -| Parameter | Description | -| -------------- | ----------- | -| `package_name` | The package name. | - -## Supported commands - -``` -cargo publish -cargo add -cargo install -cargo yank -cargo unyank -cargo search -``` diff --git a/docs/content/doc/usage/packages/cargo.zh-cn.md b/docs/content/doc/usage/packages/cargo.zh-cn.md deleted file mode 100644 index 2d451716d1..0000000000 --- a/docs/content/doc/usage/packages/cargo.zh-cn.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -date: "2022-11-20T00:00:00+00:00" -title: "Cargo 软件包注册表" -slug: "cargo" -weight: 5 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Cargo" - weight: 5 - identifier: "cargo" ---- - -# Cargo 软件包注册表 - -为您的用户或组织发布 [Cargo](https://doc.rust-lang.org/stable/cargo/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -若要使用 Cargo 软件包注册表, 您需要安装 [Rust 和 Cargo](https://www.rust-lang.org/tools/install). - -Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。 -这个仓库是与注册表交互所必需的。 -下面的部分将介绍如何创建它。 - -## 索引仓库 - -Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件包索引中。 -在 Gitea 中，这个仓库有一个特殊的名称叫做 `_cargo-index`。 -在上传软件包之后，它的元数据会自动写入索引中。 -不应手动修改这个注册表的内容。 - -用户或组织软件包设置页面允许创建这个索引仓库以及配置文件。 -如果需要，此操作将重写配置文件。 -例如，如果 Gitea 实例的域名已更改，这将非常有用。 - -如果存储在 Gitea 中的软件包与索引注册表中的信息不同步，设置页面允许重建这个索引注册表。 -这个操作将遍历注册表中的所有软件包，并将它们的信息写入索引中。 -如果有很多软件包，这个过程可能需要一些时间。 - -## 配置软件包注册表 - -要注册这个软件包注册表，必须更新 Cargo 的配置。 -将以下文本添加到位于当前用户主目录中的配置文件中（例如 `~/.cargo/config.toml`）： - -``` -[registry] -default = "gitea" - -[registries.gitea] -index = "https://gitea.example.com/{owner}/_cargo-index.git" - -[net] -git-fetch-with-cli = true -``` - -| 参数 | 描述 | -| ------- | ---------------- | -| `owner` | 软件包的所有者。 | - -如果这个注册表是私有的或者您想要发布新的软件包，您必须配置您的凭据。 -将凭据部分添加到位于当前用户主目录中的凭据文件中（例如 `~/.cargo/credentials.toml`）： - -``` -[registries.gitea] -token = "Bearer {token}" -``` - -| 参数 | 描述 | -| ------- | ------------------------------------------------------------------------------------- | -| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) | - -## 发布软件包 - -在项目中运行以下命令来发布软件包： - -```shell -cargo publish -``` - -如果已经存在同名和版本的软件包，您将无法发布新的软件包。您必须先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表安装软件包，请执行以下命令： - -```shell -cargo add {package_name} -``` - -| 参数 | 描述 | -| -------------- | ------------ | -| `package_name` | 软件包名称。 | - -## 支持的命令 - -``` -cargo publish -cargo add -cargo install -cargo yank -cargo unyank -cargo search -``` diff --git a/docs/content/doc/usage/packages/chef.en-us.md b/docs/content/doc/usage/packages/chef.en-us.md deleted file mode 100644 index ee77957551..0000000000 --- a/docs/content/doc/usage/packages/chef.en-us.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -date: "2023-01-20T00:00:00+00:00" -title: "Chef Package Registry" -slug: "chef" -weight: 5 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Chef" - weight: 5 - identifier: "chef" ---- - -# Chef Package Registry - -Publish [Chef](https://chef.io/) cookbooks for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Chef package registry, you have to use [`knife`](https://docs.chef.io/workstation/knife/). - -## Authentication - -The Chef package registry does not use an username:password authentication but signed requests with a private:public key pair. -Visit the package owner settings page to create the necessary key pair. -Only the public key is stored inside Gitea. if you loose access to the private key you must re-generate the key pair. -[Configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the downloaded private key with your Gitea username as `client_name`. - -## Configure the package registry - -To [configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the Gitea package registry add the url to the `~/.chef/config.rb` file. - -``` -knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef' -``` - -| Parameter | Description | -| --------- | ----------- | -| `owner` | The owner of the package. | - -## Publish a package - -To publish a Chef package execute the following command: - -```shell -knife supermarket share {package_name} -``` - -| Parameter | Description | -| -------------- | ----------- | -| `package_name` | The package name. | - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a package from the package registry, execute the following command: - -```shell -knife supermarket install {package_name} -``` - -Optional you can specify the package version: - -```shell -knife supermarket install {package_name} {package_version} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `package_name` | The package name. | -| `package_version` | The package version. | - -## Delete a package - -If you want to remove a package from the registry, execute the following command: - -```shell -knife supermarket unshare {package_name} -``` - -Optional you can specify the package version: - -```shell -knife supermarket unshare {package_name}/versions/{package_version} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `package_name` | The package name. | -| `package_version` | The package version. | diff --git a/docs/content/doc/usage/packages/chef.zh-cn.md b/docs/content/doc/usage/packages/chef.zh-cn.md deleted file mode 100644 index 939c94b429..0000000000 --- a/docs/content/doc/usage/packages/chef.zh-cn.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -date: "2023-01-20T00:00:00+00:00" -title: "Chef 软件包注册表" -slug: "chef" -weight: 5 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Chef" - weight: 5 - identifier: "chef" ---- - -# Chef Package Registry - -为您的用户或组织发布 [Chef](https://chef.io/) cookbooks。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Chef 软件包注册表，您需要使用 [`knife`](https://docs.chef.io/workstation/knife/). - -## 认证 - -Chef 软件包注册表不使用用户名和密码进行身份验证，而是使用私钥和公钥对请求进行签名。 -请访问软件包所有者设置页面以创建必要的密钥对。 -只有公钥存储在Gitea中。如果您丢失了私钥的访问权限，您必须重新生成密钥对。 -[配置 `knife`](https://docs.chef.io/workstation/knife_setup/)，使用下载的私钥，并将 Gitea 用户名设置为 `client_name`。 - -## 配置软件包注册表 - -要将 [`knife` 配置](https://docs.chef.io/workstation/knife_setup/)为使用 Gitea 软件包注册表，请将 URL 添加到 `~/.chef/config.rb` 文件中。 - -``` -knife[:supermarket_site] = 'https://gitea.example.com/api/packages/{owner}/chef' -``` - -| 参数 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -## 发布软件包 - -若要发布 Chef 软件包，请执行以下命令： - -```shell -knife supermarket share {package_name} -``` - -| 参数 | 描述 | -| -------------- | ---------- | -| `package_name` | 软件包名称 | - -如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表中安装软件包，请执行以下命令： - -```shell -knife supermarket install {package_name} -``` - -您可以指定软件包的版本，这是可选的： - -```shell -knife supermarket install {package_name} {package_version} -``` - -| 参数 | 描述 | -| ----------------- | ---------- | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | - -## 删除软件包 - -如果您想要从注册表中删除软件包，请执行以下命令： - -```shell -knife supermarket unshare {package_name} -``` - -可选地，您可以指定软件包的版本： - -```shell -knife supermarket unshare {package_name}/versions/{package_version} -``` - -| 参数 | 描述 | -| ----------------- | ---------- | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | diff --git a/docs/content/doc/usage/packages/composer.en-us.md b/docs/content/doc/usage/packages/composer.en-us.md deleted file mode 100644 index 092518c9f0..0000000000 --- a/docs/content/doc/usage/packages/composer.en-us.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Composer Package Registry" -slug: "composer" -weight: 10 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Composer" - weight: 10 - identifier: "composer" ---- - -# Composer Package Registry - -Publish [Composer](https://getcomposer.org/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Composer package registry, you can use [Composer](https://getcomposer.org/download/) to consume and a HTTP upload client like `curl` to publish packages. - -## Publish a package - -To publish a Composer package perform a HTTP PUT operation with the package content in the request body. -The package content must be the zipped PHP project with the `composer.json` file. -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -``` -PUT https://gitea.example.com/api/packages/{owner}/composer -``` - -| Parameter | Description | -| ---------- | ----------- | -| `owner` | The owner of the package. | - -If the `composer.json` file does not contain a `version` property, you must provide it as a query parameter: - -``` -PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z} -``` - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/project.zip \ - https://gitea.example.com/api/packages/testuser/composer -``` - -Or specify the package version as query parameter: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/project.zip \ - https://gitea.example.com/api/packages/testuser/composer?version=1.0.3 -``` - -If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `201 Created` | The package has been published. | -| `400 Bad Request` | The package name and/or version are invalid or a package with the same name and version already exist. | - -## Configuring the package registry - -To register the package registry you need to add it to the Composer `config.json` file (which can usually be found under `<user-home-dir>/.composer/config.json`): - -```json -{ - "repositories": [{ - "type": "composer", - "url": "https://gitea.example.com/api/packages/{owner}/composer" - } - ] -} -``` - -To access the package registry using credentials, you must specify them in the `auth.json` file as follows: - -```json -{ - "http-basic": { - "gitea.example.com": { - "username": "{username}", - "password": "{password}" - } - } -} -``` - -| Parameter | Description | -| ---------- | ----------- | -| `owner` | The owner of the package. | -| `username` | Your Gitea username. | -| `password` | Your Gitea password or a personal access token. | - -## Install a package - -To install a package from the package registry, execute the following command: - -```shell -composer require {package_name} -``` - -Optional you can specify the package version: - -```shell -composer require {package_name}:{package_version} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `package_name` | The package name. | -| `package_version` | The package version. | diff --git a/docs/content/doc/usage/packages/composer.zh-cn.md b/docs/content/doc/usage/packages/composer.zh-cn.md deleted file mode 100644 index de19f71305..0000000000 --- a/docs/content/doc/usage/packages/composer.zh-cn.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Composer 软件包注册表" -slug: "composer" -weight: 10 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Composer" - weight: 10 - identifier: "composer" ---- - -# Composer 软件包注册表 - -为您的用户或组织发布 [Composer](https://getcomposer.org/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Composer 软件包注册表，您可以使用 [Composer](https://getcomposer.org/download/) 消费，并使用类似 `curl` 的 HTTP 上传客户端发布软件包。 - -## 发布软件包 - -要发布 Composer 软件包，请执行 HTTP `PUT` 操作，将软件包内容放入请求体中。 -软件包内容必须是包含 `composer.json` 文件的压缩 PHP 项目。 -如果已经存在同名和版本的软件包，则无法发布新的软件包。您必须先删除现有的软件包。 - -``` -PUT https://gitea.example.com/api/packages/{owner}/composer -``` - -| 参数 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -如果 `composer.json` 文件不包含 `version` 属性，您必须将其作为查询参数提供： - -``` -PUT https://gitea.example.com/api/packages/{owner}/composer?version={x.y.z} -``` - -使用 HTTP 基本身份验证的示例请求： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/project.zip \ - https://gitea.example.com/api/packages/testuser/composer -``` - -或者将软件包版本指定为查询参数： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/project.zip \ - https://gitea.example.com/api/packages/testuser/composer?version=1.0.3 -``` - -如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 - -服务器将以以下 HTTP 状态码响应。 - -| HTTP 状态码 | 含义 | -| ----------------- | ----------------------------------------------------------- | -| `201 Created` | 软件包已发布 | -| `400 Bad Request` | 软件包名称和/或版本无效，或具有相同名称和版本的软件包已存在 | - -## 配置软件包注册表 - -要注册软件包注册表，您需要将其添加到 Composer 的 `config.json` 文件中（通常可以在 `<user-home-dir>/.composer/config.json` 中找到）： - -```json -{ - "repositories": [{ - "type": "composer", - "url": "https://gitea.example.com/api/packages/{owner}/composer" - } - ] -} -``` - -要使用凭据访问软件包注册表，您必须在 `auth.json` 文件中指定它们，如下所示： - -```json -{ - "http-basic": { - "gitea.example.com": { - "username": "{username}", - "password": "{password}" - } - } -} -``` - -| 参数 | 描述 | -| ---------- | --------------------------- | -| `owner` | 软件包的所有者 | -| `username` | 您的 Gitea 用户名 | -| `password` | 您的Gitea密码或个人访问令牌 | - -## 安装软件包 - -要从软件包注册表中安装软件包，请执行以下命令： - -```shell -composer require {package_name} -``` - -您可以指定软件包的版本，这是可选的： - -```shell -composer require {package_name}:{package_version} -``` - -| 参数 | 描述 | -| ----------------- | ---------- | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | diff --git a/docs/content/doc/usage/packages/conan.en-us.md b/docs/content/doc/usage/packages/conan.en-us.md deleted file mode 100644 index 5ca3ca7a26..0000000000 --- a/docs/content/doc/usage/packages/conan.en-us.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Conan Package Registry" -slug: "conan" -weight: 20 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Conan" - weight: 20 - identifier: "conan" ---- - -# Conan Package Registry - -Publish [Conan](https://conan.io/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Conan package registry, you need to use the [conan](https://conan.io/downloads.html) command line tool to consume and publish packages. - -## Configuring the package registry - -To register the package registry you need to configure a new Conan remote: - -```shell -conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan -conan user --remote {remote} --password {password} {username} -``` - -| Parameter | Description | -| -----------| ----------- | -| `remote` | The remote name. | -| `username` | Your Gitea username. | -| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | -| `owner` | The owner of the package. | - -For example: - -```shell -conan remote add gitea https://gitea.example.com/api/packages/testuser/conan -conan user --remote gitea --password password123 testuser -``` - -## Publish a package - -Publish a Conan package by running the following command: - -```shell -conan upload --remote={remote} {recipe} -``` - -| Parameter | Description | -| ----------| ----------- | -| `remote` | The remote name. | -| `recipe` | The recipe to upload. | - -For example: - -```shell -conan upload --remote=gitea ConanPackage/1.2@gitea/final -``` - -The Gitea Conan package registry has full [revision](https://docs.conan.io/en/latest/versioning/revisions.html) support. - -## Install a package - -To install a Conan package from the package registry, execute the following command: - -```shell -conan install --remote={remote} {recipe} -``` - -| Parameter | Description | -| ----------| ----------- | -| `remote` | The remote name. | -| `recipe` | The recipe to download. | - -For example: - -```shell -conan install --remote=gitea ConanPackage/1.2@gitea/final -``` - -## Supported commands - -``` -conan install -conan get -conan info -conan search -conan upload -conan user -conan download -conan remove -``` diff --git a/docs/content/doc/usage/packages/conan.zh-cn.md b/docs/content/doc/usage/packages/conan.zh-cn.md deleted file mode 100644 index 3d3aa8a298..0000000000 --- a/docs/content/doc/usage/packages/conan.zh-cn.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Conan 软件包注册表" -slug: "conan" -weight: 20 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Conan" - weight: 20 - identifier: "conan" ---- - -# Conan 软件包注册表 - -为您的用户或组织发布 [Conan](https://conan.io/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 [conan](https://conan.io/downloads.html) 软件包注册表，您需要使用 conan 命令行工具来消费和发布软件包。 - -## 配置软件包注册表 - -要注册软件包注册表，您需要配置一个新的 Conan remote： - -```shell -conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan -conan user --remote {remote} --password {password} {username} -``` - -| 参数 | 描述 | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `remote` | 远程名称。 | -| `username` | 您的 Gitea 用户名。 | -| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 | -| `owner` | 软件包的所有者。 | - -例如: - -```shell -conan remote add gitea https://gitea.example.com/api/packages/testuser/conan -conan user --remote gitea --password password123 testuser -``` - -## 发布软件包 - -通过运行以下命令发布 Conan 软件包： - -```shell -conan upload --remote={remote} {recipe} -``` - -| 参数 | 描述 | -| -------- | --------------- | -| `remote` | 远程名称 | -| `recipe` | 要上传的 recipe | - -For example: - -```shell -conan upload --remote=gitea ConanPackage/1.2@gitea/final -``` - -Gitea Conan 软件包注册表支持完整的[版本修订](https://docs.conan.io/en/latest/versioning/revisions.html)。 - -## 安装软件包 - -要从软件包注册表中安装Conan软件包，请执行以下命令： - -```shell -conan install --remote={remote} {recipe} -``` - -| 参数 | 描述 | -| -------- | --------------- | -| `remote` | 远程名称 | -| `recipe` | 要下载的 recipe | - -例如： - -```shell -conan install --remote=gitea ConanPackage/1.2@gitea/final -``` - -## 支持的命令 - -``` -conan install -conan get -conan info -conan search -conan upload -conan user -conan download -conan remove -``` diff --git a/docs/content/doc/usage/packages/conda.en-us.md b/docs/content/doc/usage/packages/conda.en-us.md deleted file mode 100644 index 6178b6237d..0000000000 --- a/docs/content/doc/usage/packages/conda.en-us.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -date: "2022-12-28T00:00:00+00:00" -title: "Conda Package Registry" -slug: "conda" -weight: 25 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Conda" - weight: 25 - identifier: "conda" ---- - -# Conda Package Registry - -Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Conda package registry, you need to use [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html). - -## Configuring the package registry - -To register the package registry and provide credentials, edit your `.condarc` file: - -```yaml -channel_alias: https://gitea.example.com/api/packages/{owner}/conda -channels: - - https://gitea.example.com/api/packages/{owner}/conda -default_channels: - - https://gitea.example.com/api/packages/{owner}/conda -``` - -| Placeholder | Description | -| ------------ | ----------- | -| `owner` | The owner of the package. | - -See the [official documentation](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html) for explanations of the individual settings. - -If you need to provide credentials, you may embed them as part of the channel url (`https://user:password@gitea.example.com/...`). - -## Publish a package - -To publish a package, perform a HTTP PUT operation with the package content in the request body. - -``` -PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename} -``` - -| Placeholder | Description | -| ------------ | ----------- | -| `owner` | The owner of the package. | -| `channel` | The [channel](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html) of the package. (optional) | -| `filename` | The name of the file. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/package-1.0.conda \ - https://gitea.example.com/api/packages/testuser/conda/package-1.0.conda -``` - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a package from the package registry, execute one of the following commands: - -```shell -conda install {package_name} -conda install {package_name}={package_version} -conda install -c {channel} {package_name} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `package_name` | The package name. | -| `package_version` | The package version. | -| `channel` | The channel of the package. (optional) | diff --git a/docs/content/doc/usage/packages/conda.zh-cn.md b/docs/content/doc/usage/packages/conda.zh-cn.md deleted file mode 100644 index 721c2761ca..0000000000 --- a/docs/content/doc/usage/packages/conda.zh-cn.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -date: "2022-12-28T00:00:00+00:00" -title: "Conda 软件包注册表" -slug: "conda" -weight: 25 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Conda" - weight: 25 - identifier: "conda" ---- - -# Conda 软件包注册表 - -为您的用户或组织发布 [Conda](https://docs.conda.io/en/latest/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Conda 软件包注册表，您需要使用 [conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) 命令行工具。 - -## 配置软件包注册表 - -要注册软件包注册表并提供凭据，请编辑您的 `.condarc` 文件： - -```yaml -channel_alias: https://gitea.example.com/api/packages/{owner}/conda -channels: - - https://gitea.example.com/api/packages/{owner}/conda -default_channels: - - https://gitea.example.com/api/packages/{owner}/conda -``` - -| 占位符 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -有关各个设置的解释，请参阅[官方文档](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html)。 - -如果需要提供凭据，可以将它们作为通道 URL 的一部分嵌入（`https://user:password@gitea.example.com/...`）。 - -## 发布软件包 - -要发布一个软件包，请执行一个HTTP `PUT`操作，请求正文中包含软件包内容。 - -``` -PUT https://gitea.example.com/api/packages/{owner}/conda/{channel}/{filename} -``` - -| 占位符 | 描述 | -| ---------- | --------------------------------------------------------------------------------------------------- | -| `owner` | 软件包的所有者 | -| `channel` | 软件包的[通道](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html)（可选） | -| `filename` | 文件名 | - -使用HTTP基本身份验证的示例请求： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/package-1.0.conda \ - https://gitea.example.com/api/packages/testuser/conda/package-1.0.conda -``` - -如果已经存在同名和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表中安装软件包，请执行以下命令之一： - -```shell -conda install {package_name} -conda install {package_name}={package_version} -conda install -c {channel} {package_name} -``` - -| 参数 | 描述 | -| ----------------- | -------------------- | -| `package_name` | 软件包的名称 | -| `package_version` | 软件包的版本 | -| `channel` | 软件包的通道（可选） | diff --git a/docs/content/doc/usage/packages/container.en-us.md b/docs/content/doc/usage/packages/container.en-us.md deleted file mode 100644 index 457e6fb1a4..0000000000 --- a/docs/content/doc/usage/packages/container.en-us.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Container Registry" -slug: "container" -weight: 30 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Container Registry" - weight: 30 - identifier: "container" ---- - -# Container Registry - -Publish [Open Container Initiative](https://opencontainers.org/) compliant images for your user or organization. -The container registry follows the OCI specs and supports all compatible images like [Docker](https://www.docker.com/) and [Helm Charts](https://helm.sh/). - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Container registry, you can use the tools for your specific image type. -The following examples use the `docker` client. - -## Login to the container registry - -To push an image or if the image is in a private registry, you have to authenticate: - -```shell -docker login gitea.example.com -``` - -If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. - -## Image naming convention - -Images must follow this naming convention: - -`{registry}/{owner}/{image}` - -For example, these are all valid image names for the owner `testuser`: - -`gitea.example.com/testuser/myimage` - -`gitea.example.com/testuser/my-image` - -`gitea.example.com/testuser/my/image` - -**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. - -## Push an image - -Push an image by executing the following command: - -```shell -docker push gitea.example.com/{owner}/{image}:{tag} -``` - -| Parameter | Description | -| ----------| ----------- | -| `owner` | The owner of the image. | -| `image` | The name of the image. | -| `tag` | The tag of the image. | - -For example: - -```shell -docker push gitea.example.com/testuser/myimage:latest -``` - -## Pull an image - -Pull an image by executing the following command: - -```shell -docker pull gitea.example.com/{owner}/{image}:{tag} -``` - -| Parameter | Description | -| ----------| ----------- | -| `owner` | The owner of the image. | -| `image` | The name of the image. | -| `tag` | The tag of the image. | - -For example: - -```shell -docker pull gitea.example.com/testuser/myimage:latest -``` diff --git a/docs/content/doc/usage/packages/container.zh-cn.md b/docs/content/doc/usage/packages/container.zh-cn.md deleted file mode 100644 index d441a81078..0000000000 --- a/docs/content/doc/usage/packages/container.zh-cn.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "容器注册表" -slug: "container" -weight: 30 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "容器" - weight: 30 - identifier: "container" ---- - -# 容器注册表 - -为您的用户或组织发布符合 [Open Container Initiative(OCI)](https://opencontainers.org/) 规范的镜像。 -该容器注册表遵循 OCI 规范，并支持所有兼容的镜像类型，如 [Docker](https://www.docker.com/) 和 [Helm Charts](https://helm.sh/)。 - -**目录** - -{{< toc >}} - -## 目录 - -要使用容器注册表，您可以使用适用于特定镜像类型的工具。 -以下示例使用 `docker` 客户端。 - -## 登录容器注册表 - -要推送镜像或者如果镜像位于私有注册表中，您需要进行身份验证： - -```shell -docker login gitea.example.com -``` - -如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。 - -## 镜像命名约定 - -镜像必须遵循以下命名约定： - -`{registry}/{owner}/{image}` - -例如，以下是所有者为 `testuser` 的有效镜像名称示例： - -`gitea.example.com/testuser/myimage` - -`gitea.example.com/testuser/my-image` - -`gitea.example.com/testuser/my/image` - -**注意:** 该注册表仅支持大小写不敏感的标签名称。因此，`image:tag` 和 `image:Tag` 将被视为相同的镜像和标签。 - -## 推送镜像 - -通过执行以下命令来推送镜像： - -```shell -docker push gitea.example.com/{owner}/{image}:{tag} -``` - -| 参数 | 描述 | -| ------- | ------------ | -| `owner` | 镜像的所有者 | -| `image` | 镜像的名称 | -| `tag` | 镜像的标签 | - -例如： - -```shell -docker push gitea.example.com/testuser/myimage:latest -``` - -## 拉取镜像 - -通过执行以下命令来拉取镜像： - -```shell -docker pull gitea.example.com/{owner}/{image}:{tag} -``` - -| Parameter | Description | -| --------- | ------------ | -| `owner` | 镜像的所有者 | -| `image` | 镜像的名称 | -| `tag` | 镜像的标签 | - -例如： - -```shell -docker pull gitea.example.com/testuser/myimage:latest -``` diff --git a/docs/content/doc/usage/packages/cran.en-us.md b/docs/content/doc/usage/packages/cran.en-us.md deleted file mode 100644 index fafe49429b..0000000000 --- a/docs/content/doc/usage/packages/cran.en-us.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -date: "2023-01-01T00:00:00+00:00" -title: "CRAN Package Registry" -slug: "cran" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "CRAN" - weight: 35 - identifier: "cran" ---- - -# CRAN Package Registry - -Publish [R](https://www.r-project.org/) packages to a [CRAN](https://cran.r-project.org/)-like registry for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the CRAN package registry, you need to install [R](https://cran.r-project.org/). - -## Configuring the package registry - -To register the package registry you need to add it to `Rprofile.site`, either on the system-level, user-level (`~/.Rprofile`) or project-level: - -``` -options("repos" = c(getOption("repos"), c(gitea="https://gitea.example.com/api/packages/{owner}/cran"))) -``` - -| Parameter | Description | -| --------- | ----------- | -| `owner` | The owner of the package. | - -If you need to provide credentials, you may embed them as part of the url (`https://user:password@gitea.example.com/...`). - -## Publish a package - -To publish a R package, perform a HTTP `PUT` operation with the package content in the request body. - -Source packages: - -``` -PUT https://gitea.example.com/api/packages/{owner}/cran/src -``` - -| Parameter | Description | -| --------- | ----------- | -| `owner` | The owner of the package. | - -Binary packages: - -``` -PUT https://gitea.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion} -``` - -| Parameter | Description | -| ---------- | ----------- | -| `owner` | The owner of the package. | -| `platform` | The name of the platform. | -| `rversion` | The R version of the binary. | - -For example: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/package.zip \ - https://gitea.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2 -``` - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a R package from the package registry, execute the following command: - -```shell -install.packages("{package_name}") -``` - -| Parameter | Description | -| -------------- | ----------- | -| `package_name` | The package name. | - -For example: - -```shell -install.packages("testpackage") -``` diff --git a/docs/content/doc/usage/packages/cran.zh-cn.md b/docs/content/doc/usage/packages/cran.zh-cn.md deleted file mode 100644 index fec9a56feb..0000000000 --- a/docs/content/doc/usage/packages/cran.zh-cn.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -date: "2023-01-01T00:00:00+00:00" -title: "CRAN 软件包注册表" -slug: "cran" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "CRAN" - weight: 35 - identifier: "cran" ---- - -# CRAN 软件包注册表 - -将 [R](https://www.r-project.org/) 软件包发布到您的用户或组织的类似 [CRAN](https://cran.r-project.org/) 的注册表。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用CRAN软件包注册表，您需要安装 [R](https://cran.r-project.org/)。 - -## 配置软件包注册表 - -要注册软件包注册表，您需要将其添加到 `Rprofile.site` 文件中，可以是系统级别、用户级别 `~/.Rprofile` 或项目级别： - -``` -options("repos" = c(getOption("repos"), c(gitea="https://gitea.example.com/api/packages/{owner}/cran"))) -``` - -| 参数 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -如果需要提供凭据，可以将它们嵌入到URL(`https://user:password@gitea.example.com/...`)中。 - -## 发布软件包 - -要发布 R 软件包，请执行带有软件包内容的 HTTP `PUT` 操作。 - -源代码软件包： - -``` -PUT https://gitea.example.com/api/packages/{owner}/cran/src -``` - -| 参数 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -二进制软件包： - -``` -PUT https://gitea.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion} -``` - -| 参数 | 描述 | -| ---------- | -------------- | -| `owner` | 软件包的所有者 | -| `platform` | 平台的名称 | -| `rversion` | 二进制的R版本 | - -例如： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/package.zip \ - https://gitea.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2 -``` - -如果同名和版本的软件包已存在，则无法发布软件包。您必须首先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表中安装R软件包，请执行以下命令： - -```shell -install.packages("{package_name}") -``` - -| 参数 | 描述 | -| -------------- | ----------------- | -| `package_name` | The package name. | - -例如： - -```shell -install.packages("testpackage") -``` diff --git a/docs/content/doc/usage/packages/debian.en-us.md b/docs/content/doc/usage/packages/debian.en-us.md deleted file mode 100644 index 239fd8c174..0000000000 --- a/docs/content/doc/usage/packages/debian.en-us.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -date: "2023-01-07T00:00:00+00:00" -title: "Debian Package Registry" -slug: "debian" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Debian" - weight: 35 - identifier: "debian" ---- - -# Debian Package Registry - -Publish [Debian](https://www.debian.org/distrib/packages) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Debian registry, you need to use a HTTP client like `curl` to upload and a package manager like `apt` to consume packages. - -The following examples use `apt`. - -## Configuring the package registry - -To register the Debian registry add the url to the list of known apt sources: - -```shell -echo "deb https://gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list -``` - -| Placeholder | Description | -| -------------- | ----------- | -| `owner` | The owner of the package. | -| `distribution` | The distribution to use. | -| `component` | The component to use. | - -If the registry is private, provide credentials in the url. You can use a password or a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}): - -```shell -echo "deb https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list -``` - -The Debian registry files are signed with a PGP key which must be known to apt: - -```shell -sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/trusted.gpg.d/gitea-{owner}.asc -``` - -Afterwards update the local package index: - -```shell -apt update -``` - -## Publish a package - -To publish a Debian package (`*.deb`), perform a HTTP `PUT` operation with the package content in the request body. - -``` -PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload -``` - -| Parameter | Description | -| -------------- | ----------- | -| `owner` | The owner of the package. | -| `distribution` | The distribution may match the release name of the OS, ex: `bionic`. | -| `component` | The component can be used to group packages or just `main` or similar. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.deb \ - https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/upload -``` - -If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. -You cannot publish a file with the same name twice to a package. You must delete the existing package version first. - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `201 Created` | The package has been published. | -| `400 Bad Request` | The package name, version, distribution, component or architecture are invalid. | -| `409 Conflict` | A package file with the same combination of parameters exists already. | - -## Delete a package - -To delete a Debian package perform a HTTP `DELETE` operation. This will delete the package version too if there is no file left. - -``` -DELETE https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version. | -| `distribution` | The package distribution. | -| `component` | The package component. | -| `architecture` | The package architecture. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64 -``` - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `204 No Content` | Success | -| `404 Not Found` | The package or file was not found. | - -## Install a package - -To install a package from the Debian registry, execute the following commands: - -```shell -# use latest version -apt install {package_name} -# use specific version -apt install {package_name}={package_version} -``` diff --git a/docs/content/doc/usage/packages/debian.zh-cn.md b/docs/content/doc/usage/packages/debian.zh-cn.md deleted file mode 100644 index 57b8a9e4ae..0000000000 --- a/docs/content/doc/usage/packages/debian.zh-cn.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -date: "2023-01-07T00:00:00+00:00" -title: "Debian 软件包注册表" -slug: "debian" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Debian" - weight: 35 - identifier: "debian" ---- - -# Debian 软件包注册表 - -为您的用户或组织发布 [Debian](https://www.debian.org/distrib/packages) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Debian 注册表，您需要使用类似于 `curl` 的 HTTP 客户端进行上传，并使用类似于 `apt` 的软件包管理器消费软件包。 - -以下示例使用 `apt`。 - -## 配置软件包注册表 - -要注册 Debian 注册表，请将 URL 添加到已知 `apt` 源列表中： - -```shell -echo "deb https://gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list -``` - -| 占位符 | 描述 | -| -------------- | -------------- | -| `owner` | 软件包的所有者 | -| `distribution` | 要使用的发行版 | -| `component` | 要使用的组件 | - -如果注册表是私有的，请在 URL 中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})： - -```shell -echo "deb https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/gitea.list -``` - -Debian 注册表文件使用 PGP 密钥进行签名，`apt` 必须知道该密钥： - -```shell -sudo curl https://gitea.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/trusted.gpg.d/gitea-{owner}.asc -``` - -然后更新本地软件包索引： - -```shell -apt update -``` - -## 发布软件包 - -要发布一个 Debian 软件包（`*.deb`），执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。 - -``` -PUT https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload -``` - -| 参数 | 描述 | -| -------------- | ----------------------------------------------------- | -| `owner` | 软件包的所有者 | -| `distribution` | 发行版，可能与操作系统的发行版名称匹配，例如 `bionic` | -| `component` | 组件，可用于分组软件包，或仅为 `main` 或类似的组件。 | - -使用 HTTP 基本身份验证的示例请求： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.deb \ - https://gitea.example.com/api/packages/testuser/debian/pool/bionic/main/upload -``` - -如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 -您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。 - -服务器将使用以下 HTTP 状态代码进行响应。 - -| HTTP 状态码 | 意义 | -| ----------------- | ---------------------------------------- | -| `201 Created` | 软件包已发布 | -| `400 Bad Request` | 软件包名称、版本、发行版、组件或架构无效 | -| `409 Conflict` | 具有相同参数组合的软件包文件已经存在 | - -## 删除软件包 - -要删除 Debian 软件包，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。 - -``` -DELETE https://gitea.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture} -``` - -| 参数 | 描述 | -| ----------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | -| `distribution` | 软件包发行版 | -| `component` | 软件包组件 | -| `architecture` | 软件包架构 | - -使用 HTTP 基本身份验证的示例请求： - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64 -``` - -服务器将使用以下 HTTP 状态代码进行响应。 - -| HTTP 状态码 | 含义 | -| ---------------- | ------------------ | -| `204 No Content` | 成功 | -| `404 Not Found` | 找不到软件包或文件 | - -## 安装软件包 - -要从 Debian 注册表安装软件包，请执行以下命令: - -```shell -# use latest version -apt install {package_name} -# use specific version -apt install {package_name}={package_version} -``` diff --git a/docs/content/doc/usage/packages/generic.en-us.md b/docs/content/doc/usage/packages/generic.en-us.md deleted file mode 100644 index 9ff8930722..0000000000 --- a/docs/content/doc/usage/packages/generic.en-us.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Generic Package Registry" -slug: "generic" -weight: 40 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Generic" - weight: 40 - identifier: "generic" ---- - -# Generic Package Registry - -Publish generic files, like release binaries or other output, for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Authenticate to the package registry - -To authenticate to the Package Registry, you need to provide [custom HTTP headers or use HTTP Basic authentication]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). - -## Publish a package - -To publish a generic package perform a HTTP PUT operation with the package content in the request body. -You cannot publish a file with the same name twice to a package. You must delete the existing package version first. - -``` -PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). | -| `package_version` | The package version, a non-empty string without trailing or leading whitespaces. | -| `file_name` | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.bin \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin -``` - -If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `201 Created` | The package has been published. | -| `400 Bad Request` | The package name and/or version and/or file name are invalid. | -| `409 Conflict` | A file with the same name exist already in the package. | - -## Download a package - -To download a generic package perform a HTTP GET operation. - -``` -GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version. | -| `file_name` | The filename. | - -The file content is served in the response body. The response content type is `application/octet-stream`. - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_token_or_password \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin -``` - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `200 OK` | Success | -| `404 Not Found` | The package or file was not found. | - -## Delete a package - -To delete a generic package perform a HTTP DELETE operation. This will delete all files of this version. - -``` -DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0 -``` - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `204 No Content` | Success | -| `404 Not Found` | The package was not found. | - -## Delete a package file - -To delete a file of a generic package perform a HTTP DELETE operation. This will delete the package version too if there is no file left. - -``` -DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version. | -| `filename` | The filename. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin -``` - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `204 No Content` | Success | -| `404 Not Found` | The package or file was not found. | diff --git a/docs/content/doc/usage/packages/generic.zh-cn.md b/docs/content/doc/usage/packages/generic.zh-cn.md deleted file mode 100644 index ce5cdcb7ae..0000000000 --- a/docs/content/doc/usage/packages/generic.zh-cn.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "通用软件包注册表" -slug: "generic" -weight: 40 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "通用" - weight: 40 - identifier: "generic" ---- - -# 通用软件包注册表 - -发布通用文件，如发布二进制文件或其他输出，供您的用户或组织使用。 - -**目录** - -{{< toc >}} - -## 身份验证软件包注册表 - -要身份验证软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 - -## 发布软件包 - -要发布通用软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。 -您无法向软件包中多次发布具有相同名称的文件。您必须首先删除现有的软件包版本。 - -``` -PUT https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} -``` - -| 参数 | 描述 | -| ----------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `owner` | 软件包的所有者。 | -| `package_name` | 软件包名称。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) | -| `package_version` | 软件包版本，一个非空字符串，不包含前导或尾随空格 | -| `file_name` | 文件名。它只能包含小写字母 (`a-z`)、大写字母 (`A-Z`)、数字 (`0-9`)、点号 (`.`)、连字符 (`-`)、加号 (`+`) 或下划线 (`_`) | - -使用 HTTP 基本身份验证的示例请求： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.bin \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin -``` - -如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。 - -服务器将使用以下 HTTP 状态代码进行响应。 - -| HTTP 状态码 | 意义 | -| ----------------- | ---------------------------------- | -| `201 Created` | 软件包已发布 | -| `400 Bad Request` | 软件包名称和/或版本和/或文件名无效 | -| `409 Conflict` | 具有相同名称的文件已存在于软件包中 | - -## 下载软件包 - -要下载通用软件包，请执行 HTTP `GET` 操作。 - -``` -GET https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name} -``` - -| 参数 | 描述 | -| ----------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | -| `file_name` | 文件名 | - -文件内容将在响应主体中返回。响应的内容类型为 `application/octet-stream`。 - -服务器将使用以下 HTTP 状态代码进行响应。 - -```shell -curl --user your_username:your_token_or_password \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin -``` - -服务器会以以下 HTTP 状态码进行响应： - -| HTTP 状态码 | 含义 | -| --------------- | -------------------- | -| `200 OK` | 成功 | -| `404 Not Found` | 找不到软件包或者文件 | - -## 删除软件包 - -要删除通用软件包，请执行 HTTP DELETE 操作。这将同时删除该版本的所有文件。 - -``` -DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version} -``` - -| 参数 | 描述 | -| ----------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | - -服务器将使用以下 HTTP 状态代码进行响应。 - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0 -``` - -The server responds with the following HTTP Status codes. - -| HTTP 状态码 | 意义 | -| ---------------- | ------------ | -| `204 No Content` | 成功 | -| `404 Not Found` | 找不到软件包 | - -## 删除软件包文件 - -要删除通用软件包的文件，请执行 HTTP `DELETE` 操作。如果没有文件留下，这将同时删除软件包版本。 - -``` -DELETE https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename} -``` - -| 参数 | 描述 | -| ----------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | -| `filename` | 文件名 | - -使用 HTTP 基本身份验证的示例请求： - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin -``` - -服务器将使用以下 HTTP 状态代码进行响应： - -| HTTP 状态码 | 含义 | -| ---------------- | ------------------ | -| `204 No Content` | 成功 | -| `404 Not Found` | 找不到软件包或文件 | diff --git a/docs/content/doc/usage/packages/go.en-us.md b/docs/content/doc/usage/packages/go.en-us.md deleted file mode 100644 index 04452c3516..0000000000 --- a/docs/content/doc/usage/packages/go.en-us.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -date: "2023-05-10T00:00:00+00:00" -title: "Go Package Registry" -slug: "go" -weight: 45 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Go" - weight: 45 - identifier: "go" ---- - -# Go Package Registry - -Publish Go packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Publish a package - -To publish a Go package perform a HTTP `PUT` operation with the package content in the request body. -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. -The package must follow the [documented structure](https://go.dev/ref/mod#zip-files). - -``` -PUT https://gitea.example.com/api/packages/{owner}/go/upload -``` - -| Parameter | Description | -| --------- | ----------- | -| `owner` | The owner of the package. | - -To authenticate to the package registry, you need to provide [custom HTTP headers or use HTTP Basic authentication]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}): - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.zip \ - https://gitea.example.com/api/packages/testuser/go/upload -``` - -If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `201 Created` | The package has been published. | -| `400 Bad Request` | The package is invalid. | -| `409 Conflict` | A package with the same name exist already. | - -## Install a package - -To install a Go package instruct Go to use the package registry as proxy: - -```shell -# use latest version -GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name} -# or -GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest -# use specific version -GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version. | - -If the owner of the packages is private you need to [provide credentials](https://go.dev/ref/mod#private-module-proxy-auth). - -More information about the `GOPROXY` environment variable and how to protect against data leaks can be found in [the documentation](https://go.dev/ref/mod#private-modules). diff --git a/docs/content/doc/usage/packages/go.zh-cn.md b/docs/content/doc/usage/packages/go.zh-cn.md deleted file mode 100644 index 069a6991fb..0000000000 --- a/docs/content/doc/usage/packages/go.zh-cn.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -date: "2023-05-10T00:00:00+00:00" -title: "Go 软件包注册表" -slug: "go" -weight: 45 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Go" - weight: 45 - identifier: "go" ---- - -# Go 软件包注册表 - -为您的用户或组织发布 Go 软件包。 - -**目录** - -{{< toc >}} - -## 发布软件包 - -要发布 Go 软件包，请执行 HTTP `PUT` 操作，并将软件包内容放入请求主体中。 -如果已经存在相同名称和版本的软件包，您无法发布软件包。您必须首先删除现有的软件包。 -该软件包必须遵循[文档中的结构](https://go.dev/ref/mod#zip-files)。 - -``` -PUT https://gitea.example.com/api/packages/{owner}/go/upload -``` - -| 参数 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -要身份验证到软件包注册表，您需要提供[自定义 HTTP 头或使用 HTTP 基本身份验证]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.zip \ - https://gitea.example.com/api/packages/testuser/go/upload -``` - -如果您使用的是 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。 - -服务器将使用以下 HTTP 状态代码进行响应。 - -| HTTP 状态码 | 含义 | -| ----------------- | -------------------------- | -| `201 Created` | 软件包已发布 | -| `400 Bad Request` | 软件包无效 | -| `409 Conflict` | 具有相同名称的软件包已存在 | - -## 安装软件包 - -要安装Go软件包，请指示Go使用软件包注册表作为代理： - -```shell -# 使用最新版本 -GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name} -# 或者 -GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@latest -# 使用特定版本 -GOPROXY=https://gitea.example.com/api/packages/{owner}/go go install {package_name}@{package_version} -``` - -| 参数 | 描述 | -| ----------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | - -如果软件包的所有者是私有的，则需要[提供凭据](https://go.dev/ref/mod#private-module-proxy-auth)。 - -有关 `GOPROXY` 环境变量的更多信息以及如何防止数据泄漏的信息，请[参阅文档](https://go.dev/ref/mod#private-modules)。 diff --git a/docs/content/doc/usage/packages/helm.en-us.md b/docs/content/doc/usage/packages/helm.en-us.md deleted file mode 100644 index 1db1e8758b..0000000000 --- a/docs/content/doc/usage/packages/helm.en-us.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -date: "2022-04-14T00:00:00+00:00" -title: "Helm Chart Registry" -slug: "helm" -weight: 50 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Helm" - weight: 50 - identifier: "helm" ---- - -# Helm Chart Registry - -Publish [Helm](https://helm.sh/) charts for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Helm Chart registry use a simple HTTP client like `curl` or the [`helm cm-push`](https://github.com/chartmuseum/helm-push/) plugin. - -## Publish a package - -Publish a package by running the following command: - -```shell -curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts -``` - -or with the `helm cm-push` plugin: - -```shell -helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm -helm cm-push ./{chart_file}.tgz {repo} -``` - -| Parameter | Description | -| ------------ | ----------- | -| `username` | Your Gitea username. | -| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | -| `repo` | The name for the repository. | -| `chart_file` | The Helm Chart archive. | -| `owner` | The owner of the package. | - -## Install a package - -To install a Helm char from the registry, execute the following command: - -```shell -helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm -helm repo update -helm install {name} {repo}/{chart} -``` - -| Parameter | Description | -| ---------- | ----------- | -| `username` | Your Gitea username. | -| `password` | Your Gitea password or a personal access token. | -| `repo` | The name for the repository. | -| `owner` | The owner of the package. | -| `name` | The local name. | -| `chart` | The name Helm Chart. | diff --git a/docs/content/doc/usage/packages/helm.zh-cn.md b/docs/content/doc/usage/packages/helm.zh-cn.md deleted file mode 100644 index 337170bc26..0000000000 --- a/docs/content/doc/usage/packages/helm.zh-cn.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -date: "2022-04-14T00:00:00+00:00" -title: "Helm Chart 注册表" -slug: "helm" -weight: 50 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Helm" - weight: 50 - identifier: "helm" ---- - -# Helm Chart 注册表 - -为您的用户或组织发布 [Helm](https://helm.sh/) charts。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Helm Chart 注册表，可以使用诸如 `curl` 或 [`helm cm-push`](https://github.com/chartmuseum/helm-push/) 插件之类的简单HTTP客户端。 - -## 发布软件包 - -通过运行以下命令来发布软件包： - -```shell -curl --user {username}:{password} -X POST --upload-file ./{chart_file}.tgz https://gitea.example.com/api/packages/{owner}/helm/api/charts -``` - -或者使用 `helm cm-push` 插件： - -```shell -helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm -helm cm-push ./{chart_file}.tgz {repo} -``` - -| 参数 | 描述 | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `username` | 您的Gitea用户名 | -| `password` | 您的Gitea密码。如果您使用的是2FA或OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码进行身份验证。 | -| `repo` | 仓库名称 | -| `chart_file` | Helm Chart 归档文件 | -| `owner` | 软件包的所有者 | - -## 安装软件包 - -要从注册表中安装Helm Chart，请执行以下命令： - -```shell -helm repo add --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm -helm repo update -helm install {name} {repo}/{chart} -``` - -| 参数 | 描述 | -| ---------- | --------------------------- | -| `username` | 您的Gitea用户名 | -| `password` | 您的Gitea密码或个人访问令牌 | -| `repo` | 存储库的名称 | -| `owner` | 软件包的所有者 | -| `name` | 本地名称 | -| `chart` | Helm Chart的名称 | diff --git a/docs/content/doc/usage/packages/maven.en-us.md b/docs/content/doc/usage/packages/maven.en-us.md deleted file mode 100644 index 85b37fe464..0000000000 --- a/docs/content/doc/usage/packages/maven.en-us.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Maven Package Registry" -slug: "maven" -weight: 60 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Maven" - weight: 60 - identifier: "maven" ---- - -# Maven Package Registry - -Publish [Maven](https://maven.apache.org) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Maven package registry, you can use [Maven](https://maven.apache.org/install.html) or [Gradle](https://gradle.org/install/). -The following examples use `Maven` and `Gradle Groovy`. - -## Configuring the package registry - -To register the package registry you first need to add your access token to the [`settings.xml`](https://maven.apache.org/settings.html) file: - -```xml -<settings> - <servers> - <server> - <id>gitea</id> - <configuration> - <httpHeaders> - <property> - <name>Authorization</name> - <value>token {access_token}</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> -</settings> -``` - -Afterwards add the following sections to your project `pom.xml` file: - -```xml -<repositories> - <repository> - <id>gitea</id> - <url>https://gitea.example.com/api/packages/{owner}/maven</url> - </repository> -</repositories> -<distributionManagement> - <repository> - <id>gitea</id> - <url>https://gitea.example.com/api/packages/{owner}/maven</url> - </repository> - <snapshotRepository> - <id>gitea</id> - <url>https://gitea.example.com/api/packages/{owner}/maven</url> - </snapshotRepository> -</distributionManagement> -``` - -| Parameter | Description | -| -------------- | ----------- | -| `access_token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). | -| `owner` | The owner of the package. | - -### Gradle variant - -When you plan to add some packages from Gitea instance in your project, you should add it in repositories section: - -```groovy -repositories { - // other repositories - maven { url "https://gitea.example.com/api/packages/{owner}/maven" } -} -``` - -In Groovy gradle you may include next script in your publishing part: - -```groovy -publishing { - // other settings of publication - repositories { - maven { - name = "Gitea" - url = uri("https://gitea.example.com/api/packages/{owner}/maven") - - credentials(HttpHeaderCredentials) { - name = "Authorization" - value = "token {access_token}" - } - - authentication { - header(HttpHeaderAuthentication) - } - } - } -} -``` - -## Publish a package - -To publish a package simply run: - -```shell -mvn deploy -``` - -Or call `gradle` with task `publishAllPublicationsToGiteaRepository` in case you are using gradle: - -```groovy -./gradlew publishAllPublicationsToGiteaRepository -``` - -If you want to publish a prebuild package to the registry, you can use [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html): - -```shell -mvn deploy:deploy-file -Durl=https://gitea.example.com/api/packages/{owner}/maven -DrepositoryId=gitea -Dfile=/path/to/package.jar -``` - -| Parameter | Description | -| -------------- | ----------- | -| `owner` | The owner of the package. | - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a Maven package from the package registry, add a new dependency to your project `pom.xml` file: - -```xml -<dependency> - <groupId>com.test.package</groupId> - <artifactId>test_project</artifactId> - <version>1.0.0</version> -</dependency> -``` - -And analog in gradle groovy: - -```groovy -implementation "com.test.package:test_project:1.0.0" -``` - -Afterwards run: - -```shell -mvn install -``` - -## Supported commands - -``` -mvn install -mvn deploy -mvn dependency:get: -``` diff --git a/docs/content/doc/usage/packages/maven.zh-cn.md b/docs/content/doc/usage/packages/maven.zh-cn.md deleted file mode 100644 index 833bb81507..0000000000 --- a/docs/content/doc/usage/packages/maven.zh-cn.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Maven 软件包注册表" -slug: "maven" -weight: 60 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Maven" - weight: 60 - identifier: "maven" ---- - -# Maven 软件包注册表 - -为您的用户或组织发布 [Maven](https://maven.apache.org) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Maven 软件包注册表，您可以使用 [Maven](https://maven.apache.org/install.html) 或 [Gradle](https://gradle.org/install/)。 -以下示例使用 `Maven` 和 `Gradle Groovy`。 - -## 配置软件包注册表 - -要注册软件包注册表，首先需要将访问令牌添加到 [`settings.xml`](https://maven.apache.org/settings.html) 文件中： - -```xml -<settings> - <servers> - <server> - <id>gitea</id> - <configuration> - <httpHeaders> - <property> - <name>Authorization</name> - <value>token {access_token}</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> -</settings> -``` - -然后在项目的 `pom.xml` 文件中添加以下部分： - -```xml -<repositories> - <repository> - <id>gitea</id> - <url>https://gitea.example.com/api/packages/{owner}/maven</url> - </repository> -</repositories> -<distributionManagement> - <repository> - <id>gitea</id> - <url>https://gitea.example.com/api/packages/{owner}/maven</url> - </repository> - <snapshotRepository> - <id>gitea</id> - <url>https://gitea.example.com/api/packages/{owner}/maven</url> - </snapshotRepository> -</distributionManagement> -``` - -| 参数 | 描述 | -| -------------- | ------------------------------------------------------------------------------------- | -| `access_token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) | -| `owner` | 软件包的所有者 | - -### Gradle variant - -如果您计划在项目中添加来自 Gitea 实例的一些软件包，请将其添加到 repositories 部分中： - -```groovy -repositories { - // other repositories - maven { url "https://gitea.example.com/api/packages/{owner}/maven" } -} -``` - -在 Groovy gradle 中，您可以在发布部分中包含以下脚本： - -```groovy -publishing { - // 其他发布设置 - repositories { - maven { - name = "Gitea" - url = uri("https://gitea.example.com/api/packages/{owner}/maven") - - credentials(HttpHeaderCredentials) { - name = "Authorization" - value = "token {access_token}" - } - - authentication { - header(HttpHeaderAuthentication) - } - } - } -} -``` - -## 发布软件包 - -要发布软件包，只需运行以下命令： - -```shell -mvn deploy -``` - -或者，如果您使用的是 Gradle，请使用 `gradle` 命令和 `publishAllPublicationsToGiteaRepository` 任务： - -```groovy -./gradlew publishAllPublicationsToGiteaRepository -``` - -如果您想要将预构建的软件包发布到注册表中，可以使用 [`mvn deploy:deploy-file`](https://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html) 命令： - -```shell -mvn deploy:deploy-file -Durl=https://gitea.example.com/api/packages/{owner}/maven -DrepositoryId=gitea -Dfile=/path/to/package.jar -``` - -| 参数 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -如果存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表中安装 Maven 软件包，请在项目的 `pom.xml` 文件中添加新的依赖项： - -```xml -<dependency> - <groupId>com.test.package</groupId> - <artifactId>test_project</artifactId> - <version>1.0.0</version> -</dependency> -``` - -在 `Gradle Groovy` 中类似的操作如下： - -```groovy -implementation "com.test.package:test_project:1.0.0" -``` - -然后运行： - -```shell -mvn install -``` - -## 支持的命令 - -``` -mvn install -mvn deploy -mvn dependency:get: -``` diff --git a/docs/content/doc/usage/packages/npm.en-us.md b/docs/content/doc/usage/packages/npm.en-us.md deleted file mode 100644 index 58edcd02a4..0000000000 --- a/docs/content/doc/usage/packages/npm.en-us.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "npm Package Registry" -slug: "npm" -weight: 70 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "npm" - weight: 70 - identifier: "npm" ---- - -# npm Package Registry - -Publish [npm](https://www.npmjs.com/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the npm package registry, you need [Node.js](https://nodejs.org/en/download/) coupled with a package manager such as [Yarn](https://classic.yarnpkg.com/en/docs/install) or [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) itself. - -The registry supports [scoped](https://docs.npmjs.com/misc/scope/) and unscoped packages. - -The following examples use the `npm` tool with the scope `@test`. - -## Configuring the package registry - -To register the package registry you need to configure a new package source. - -```shell -npm config set {scope}:registry https://gitea.example.com/api/packages/{owner}/npm/ -npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{token}" -``` - -| Parameter | Description | -| ------------ | ----------- | -| `scope` | The scope of the packages. | -| `owner` | The owner of the package. | -| `token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). | - -For example: - -```shell -npm config set @test:registry https://gitea.example.com/api/packages/testuser/npm/ -npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" -``` - -or without scope: - -```shell -npm config set registry https://gitea.example.com/api/packages/testuser/npm/ -npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" -``` - -## Publish a package - -Publish a package by running the following command in your project: - -```shell -npm publish -``` - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Unpublish a package - -Delete a package by running the following command: - -```shell -npm unpublish {package_name}[@{package_version}] -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `package_name` | The package name. | -| `package_version` | The package version. | - -For example: - -```shell -npm unpublish @test/test_package -npm unpublish @test/test_package@1.0.0 -``` - -## Install a package - -To install a package from the package registry, execute the following command: - -```shell -npm install {package_name} -``` - -| Parameter | Description | -| -------------- | ----------- | -| `package_name` | The package name. | - -For example: - -```shell -npm install @test/test_package -``` - -## Tag a package - -The registry supports [version tags](https://docs.npmjs.com/adding-dist-tags-to-packages/) which can be managed by `npm dist-tag`: - -```shell -npm dist-tag add {package_name}@{version} {tag} -``` - -| Parameter | Description | -| -------------- | ----------- | -| `package_name` | The package name. | -| `version` | The version of the package. | -| `tag` | The tag name. | - -For example: - -```shell -npm dist-tag add test_package@1.0.2 release -``` - -The tag name must not be a valid version. All tag names which are parsable as a version are rejected. - -## Search packages - -The registry supports [searching](https://docs.npmjs.com/cli/v7/commands/npm-search/) but does not support special search qualifiers like `author:gitea`. - -## Supported commands - -``` -npm install -npm ci -npm publish -npm unpublish -npm dist-tag -npm view -npm search -``` diff --git a/docs/content/doc/usage/packages/npm.zh-cn.md b/docs/content/doc/usage/packages/npm.zh-cn.md deleted file mode 100644 index 4863b2582b..0000000000 --- a/docs/content/doc/usage/packages/npm.zh-cn.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "npm 软件包注册表" -slug: "npm" -weight: 70 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "npm" - weight: 70 - identifier: "npm" ---- - -# npm Package Registry - -为您的用户或组织发布 [npm](https://www.npmjs.com/) 包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 npm 包注册表，您需要安装 [Node.js](https://nodejs.org/en/download/) 以及与之配套的软件包管理器，例如 [Yarn](https://classic.yarnpkg.com/en/docs/install) 或 [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/) 本身。 - -该注册表支持[作用域](https://docs.npmjs.com/misc/scope/)和非作用域软件包。 - -以下示例使用具有作用域 `@test` 的 `npm` 工具。 - -## 配置软件包注册表 - -要注册软件包注册表，您需要配置一个新的软件包源。 - -```shell -npm config set {scope}:registry https://gitea.example.com/api/packages/{owner}/npm/ -npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{token}" -``` - -| 参数 | 描述 | -| ------- | --------------------------------------------------------------------------------------- | -| `scope` | 软件包的作用域 | -| `owner` | 软件包的所有者 | -| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 | - -例如： - -```shell -npm config set @test:registry https://gitea.example.com/api/packages/testuser/npm/ -npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" -``` - -或者，不使用作用域： - -```shell -npm config set registry https://gitea.example.com/api/packages/testuser/npm/ -npm config set -- '//gitea.example.com/api/packages/testuser/npm/:_authToken' "personal_access_token" -``` - -## 发布软件包 - -在项目中运行以下命令发布软件包： - -```shell -npm publish -``` - -如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。 - -## 删除软件包 - -通过运行以下命令删除软件包： - -```shell -npm unpublish {package_name}[@{package_version}] -``` - -| 参数 | 描述 | -| ----------------- | ---------- | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | - -例如 - -```shell -npm unpublish @test/test_package -npm unpublish @test/test_package@1.0.0 -``` - -## 安装软件包 - -要从软件包注册表中安装软件包，请执行以下命令： - -```shell -npm install {package_name} -``` - -| 参数 | 描述 | -| -------------- | ---------- | -| `package_name` | 软件包名称 | - -例如： - -```shell -npm install @test/test_package -``` - -## 给软件包打标签 - -该注册表支持[版本标签](https://docs.npmjs.com/adding-dist-tags-to-packages/)，可以通过 `npm dist-tag` 管理： - -```shell -npm dist-tag add {package_name}@{version} {tag} -``` - -| 参数 | 描述 | -| -------------- | ---------- | -| `package_name` | 软件包名称 | -| `version` | 软件包版本 | -| `tag` | 软件包标签 | - -例如： - -```shell -npm dist-tag add test_package@1.0.2 release -``` - -标签名称不能是有效的版本。所有可解析为版本的标签名称都将被拒绝。 - -## 搜索软件包 - -该注册表支持[搜索](https://docs.npmjs.com/cli/v7/commands/npm-search/)，但不支持像 `author:gitea` 这样的特殊搜索限定符。 - -## 支持的命令 - -``` -npm install -npm ci -npm publish -npm unpublish -npm dist-tag -npm view -npm search -``` diff --git a/docs/content/doc/usage/packages/nuget.en-us.md b/docs/content/doc/usage/packages/nuget.en-us.md deleted file mode 100644 index ccda2cc49c..0000000000 --- a/docs/content/doc/usage/packages/nuget.en-us.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "NuGet Package Registry" -slug: "nuget" -weight: 80 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "NuGet" - weight: 80 - identifier: "nuget" ---- - -# NuGet Package Registry - -Publish [NuGet](https://www.nuget.org/) packages for your user or organization. The package registry supports the V2 and V3 API protocol and you can work with [NuGet Symbol Packages](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) too. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the NuGet package registry, you can use command-line interface tools as well as NuGet features in various IDEs like Visual Studio. -More information about NuGet clients can be found in [the official documentation](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools). -The following examples use the `dotnet nuget` tool. - -## Configuring the package registry - -To register the package registry you need to configure a new NuGet feed source: - -```shell -dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json -``` - -| Parameter | Description | -| ------------- | ----------- | -| `source_name` | The desired source name. | -| `username` | Your Gitea username. | -| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | -| `owner` | The owner of the package. | - -For example: - -```shell -dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json -``` - -You can add the source without credentials and use the [`--api-key`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-push) parameter when publishing packages. In this case you need to provide a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). - -## Publish a package - -Publish a package by running the following command: - -```shell -dotnet nuget push --source {source_name} {package_file} -``` - -| Parameter | Description | -| -------------- | ----------- | -| `source_name` | The desired source name. | -| `package_file` | Path to the package `.nupkg` file. | - -For example: - -```shell -dotnet nuget push --source gitea test_package.1.0.0.nupkg -``` - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -### Symbol Packages - -The NuGet package registry has build support for a symbol server. The PDB files embedded in a symbol package (`.snupkg`) can get requested by clients. -To do so, register the NuGet package registry as symbol source: - -``` -https://gitea.example.com/api/packages/{owner}/nuget/symbols -``` - -| Parameter | Description | -| --------- | ----------- | -| `owner` | The owner of the package registry. | - -For example: - -``` -https://gitea.example.com/api/packages/testuser/nuget/symbols -``` - -## Install a package - -To install a NuGet package from the package registry, execute the following command: - -```shell -dotnet add package --source {source_name} --version {package_version} {package_name} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `source_name` | The desired source name. | -| `package_name` | The package name. | -| `package_version` | The package version. | - -For example: - -```shell -dotnet add package --source gitea --version 1.0.0 test_package -``` - -## Supported commands - -``` -dotnet add -dotnet nuget push -dotnet nuget delete -``` diff --git a/docs/content/doc/usage/packages/nuget.zh-cn.md b/docs/content/doc/usage/packages/nuget.zh-cn.md deleted file mode 100644 index 14205545b5..0000000000 --- a/docs/content/doc/usage/packages/nuget.zh-cn.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "NuGet 软件包注册表" -slug: "nuget" -weight: 80 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "NuGet" - weight: 80 - identifier: "nuget" ---- - -# NuGet 软件包注册表 - -发布适用于您的用户或组织的 [NuGet](https://www.nuget.org/) 软件包。软件包注册表支持 V2 和 V3 API 协议，并且您还可以使用 [NuGet 符号软件包](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg)。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 NuGet 软件包注册表，您可以使用命令行界面工具，以及各种集成开发环境（IDE）中的 NuGet 功能，如 Visual Studio。有关 NuGet 客户端的更多信息，请参[阅官方文档](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools)。 -以下示例使用 `dotnet nuget` 工具。 - -## 配置软件包注册表 - -要注册软件包注册表，您需要配置一个新的NuGet源： - -```shell -dotnet nuget add source --name {source_name} --username {username} --password {password} https://gitea.example.com/api/packages/{owner}/nuget/index.json -``` - -| 参数 | 描述 | -| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `source_name` | 所需源名称 | -| `username` | 您的Gitea用户名 | -| `password` | 您的Gitea密码。如果您使用2FA或OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 | -| `owner` | 软件包的所有者 | - -例如： - -```shell -dotnet nuget add source --name gitea --username testuser --password password123 https://gitea.example.com/api/packages/testuser/nuget/index.json -``` - -您可以在不提供凭据的情况下添加源，并在发布软件包时使用--api-key参数。在这种情况下，您需要提供[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 - -## 发布软件包 - -通过运行以下命令发布软件包： - -```shell -dotnet nuget push --source {source_name} {package_file} -``` - -| 参数 | 描述 | -| -------------- | ---------------------------- | -| `source_name` | 所需源名称 | -| `package_file` | 软件包 `.nupkg` 文件的路径。 | - -例如： - -```shell -dotnet nuget push --source gitea test_package.1.0.0.nupkg -``` - -如果已经存在相同名称和版本的软件包，您无法发布该软件包。您必须先删除现有的软件包。 - -### 符号软件包 - -NuGet 软件包注册表支持构建用于符号服务器的符号软件包。客户端可以请求嵌入在符号软件包（`.snupkg`）中的 PDB 文件。 -为此，请将 NuGet 软件包注册表注册为符号源： - -``` -https://gitea.example.com/api/packages/{owner}/nuget/symbols -``` - -| 参数 | 描述 | -| ------- | -------------------- | -| `owner` | 软件包注册表的所有者 | - -例如： - -``` -https://gitea.example.com/api/packages/testuser/nuget/symbols -``` - -## 安装软件包 - -要从软件包注册表安装 NuGet 软件包，请执行以下命令： - -```shell -dotnet add package --source {source_name} --version {package_version} {package_name} -``` - -| 参数 | 描述 | -| ----------------- | ------------ | -| `source_name` | 所需源名称 | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本。 | - -例如： - -```shell -dotnet add package --source gitea --version 1.0.0 test_package -``` - -## 支持的命令 - -``` -dotnet add -dotnet nuget push -dotnet nuget delete -``` diff --git a/docs/content/doc/usage/packages/overview.en-us.md b/docs/content/doc/usage/packages/overview.en-us.md deleted file mode 100644 index bf33ea627d..0000000000 --- a/docs/content/doc/usage/packages/overview.en-us.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "Package Registry" -slug: "overview" -weight: 1 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Overview" - weight: 1 - identifier: "packages-overview" ---- - -# Package Registry - -Starting with Gitea **1.17**, the Package Registry can be used as a public or private registry for common package managers. - -**Table of Contents** - -{{< toc >}} - -## Supported package managers - -The following package managers are currently supported: - -| Name | Language | Package client | -| ---- | -------- | -------------- | -| [Alpine]({{< relref "doc/usage/packages/alpine.en-us.md" >}}) | - | `apk` | -| [Cargo]({{< relref "doc/usage/packages/cargo.en-us.md" >}}) | Rust | `cargo` | -| [Chef]({{< relref "doc/usage/packages/chef.en-us.md" >}}) | - | `knife` | -| [Composer]({{< relref "doc/usage/packages/composer.en-us.md" >}}) | PHP | `composer` | -| [Conan]({{< relref "doc/usage/packages/conan.en-us.md" >}}) | C++ | `conan` | -| [Conda]({{< relref "doc/usage/packages/conda.en-us.md" >}}) | - | `conda` | -| [Container]({{< relref "doc/usage/packages/container.en-us.md" >}}) | - | any OCI compliant client | -| [CRAN]({{< relref "doc/usage/packages/cran.en-us.md" >}}) | R | - | -| [Debian]({{< relref "doc/usage/packages/debian.en-us.md" >}}) | - | `apt` | -| [Generic]({{< relref "doc/usage/packages/generic.en-us.md" >}}) | - | any HTTP client | -| [Go]({{< relref "doc/usage/packages/go.en-us.md" >}}) | Go | `go` | -| [Helm]({{< relref "doc/usage/packages/helm.en-us.md" >}}) | - | any HTTP client, `cm-push` | -| [Maven]({{< relref "doc/usage/packages/maven.en-us.md" >}}) | Java | `mvn`, `gradle` | -| [npm]({{< relref "doc/usage/packages/npm.en-us.md" >}}) | JavaScript | `npm`, `yarn`, `pnpm` | -| [NuGet]({{< relref "doc/usage/packages/nuget.en-us.md" >}}) | .NET | `nuget` | -| [Pub]({{< relref "doc/usage/packages/pub.en-us.md" >}}) | Dart | `dart`, `flutter` | -| [PyPI]({{< relref "doc/usage/packages/pypi.en-us.md" >}}) | Python | `pip`, `twine` | -| [RPM]({{< relref "doc/usage/packages/rpm.en-us.md" >}}) | - | `yum`, `dnf`, `zypper` | -| [RubyGems]({{< relref "doc/usage/packages/rubygems.en-us.md" >}}) | Ruby | `gem`, `Bundler` | -| [Swift]({{< relref "doc/usage/packages/rubygems.en-us.md" >}}) | Swift | `swift` | -| [Vagrant]({{< relref "doc/usage/packages/vagrant.en-us.md" >}}) | - | `vagrant` | - -**The following paragraphs only apply if Packages are not globally disabled!** - -## Repository-Packages - -A package always belongs to an owner (a user or organisation), not a repository. -To link an (already uploaded) package to a repository, open the settings page -on that package and choose a repository to link this package to. -The entire package will be linked, not just a single version. - -Linking a package results in showing that package in the repository's package list, -and shows a link to the repository on the package site (as well as a link to the repository issues). - -## Access Restrictions - -| Package owner type | User | Organization | -|--------------------|------|--------------| -| **read** access | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only | -| **write** access | owner only | org members with admin or write access to the org | - -N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission. - -## Create or upload a package - -Depending on the type of package, use the respective package-manager for that. Check out the sub-page of a specific package manager for instructions. - -## View packages - -You can view the packages of a repository on the repository page. - -1. Go to the repository. -1. Go to **Packages** in the navigation bar. - -To view more details about a package, select the name of the package. - -## Download a package - -To download a package from your repository: - -1. Go to **Packages** in the navigation bar. -1. Select the name of the package to view the details. -1. In the **Assets** section, select the name of the package file you want to download. - -## Delete a package - -You cannot edit a package after you have published it in the Package Registry. Instead, you -must delete and recreate it. - -To delete a package from your repository: - -1. Go to **Packages** in the navigation bar. -1. Select the name of the package to view the details. -1. Click **Delete package** to permanently delete the package. - -## Disable the Package Registry - -The Package Registry is automatically enabled. To disable it for a single repository: - -1. Go to **Settings** in the navigation bar. -1. Disable **Enable Repository Packages Registry**. - -Previously published packages are not deleted by disabling the Package Registry. diff --git a/docs/content/doc/usage/packages/overview.zh-cn.md b/docs/content/doc/usage/packages/overview.zh-cn.md deleted file mode 100644 index 9d24a733fd..0000000000 --- a/docs/content/doc/usage/packages/overview.zh-cn.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "软件包注册表" -slug: "overview" -weight: 1 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Overview" - weight: 1 - identifier: "packages-overview" ---- - -# 软件包注册表 - -从Gitea **1.17**版本开始，软件包注册表可以用作常见软件包管理器的公共或私有注册表。 - -**目录** - -{{< toc >}} - -## 支持的软件包管理器 - -目前支持以下软件包管理器： - -| Name | Language | Package client | -| ------------------------------------------------------------------- | ---------- | ------------------------- | -| [Alpine]({{< relref "doc/usage/packages/alpine.zh-cn.md" >}}) | - | `apk` | -| [Cargo]({{< relref "doc/usage/packages/cargo.zh-cn.md" >}}) | Rust | `cargo` | -| [Chef]({{< relref "doc/usage/packages/chef.zh-cn.md" >}}) | - | `knife` | -| [Composer]({{< relref "doc/usage/packages/composer.zh-cn.md" >}}) | PHP | `composer` | -| [Conan]({{< relref "doc/usage/packages/conan.zh-cn.md" >}}) | C++ | `conan` | -| [Conda]({{< relref "doc/usage/packages/conda.zh-cn.md" >}}) | - | `conda` | -| [Container]({{< relref "doc/usage/packages/container.zh-cn.md" >}}) | - | 任何符合OCI规范的客户端 | -| [CRAN]({{< relref "doc/usage/packages/cran.zh-cn.md" >}}) | R | - | -| [Debian]({{< relref "doc/usage/packages/debian.zh-cn.md" >}}) | - | `apt` | -| [Generic]({{< relref "doc/usage/packages/generic.zh-cn.md" >}}) | - | 任何HTTP客户端 | -| [Go]({{< relref "doc/usage/packages/go.zh-cn.md" >}}) | Go | `go` | -| [Helm]({{< relref "doc/usage/packages/helm.zh-cn.md" >}}) | - | 任何HTTP客户端, `cm-push` | -| [Maven]({{< relref "doc/usage/packages/maven.zh-cn.md" >}}) | Java | `mvn`, `gradle` | -| [npm]({{< relref "doc/usage/packages/npm.zh-cn.md" >}}) | JavaScript | `npm`, `yarn`, `pnpm` | -| [NuGet]({{< relref "doc/usage/packages/nuget.zh-cn.md" >}}) | .NET | `nuget` | -| [Pub]({{< relref "doc/usage/packages/pub.zh-cn.md" >}}) | Dart | `dart`, `flutter` | -| [PyPI]({{< relref "doc/usage/packages/pypi.zh-cn.md" >}}) | Python | `pip`, `twine` | -| [RPM]({{< relref "doc/usage/packages/rpm.zh-cn.md" >}}) | - | `yum`, `dnf`, `zypper` | -| [RubyGems]({{< relref "doc/usage/packages/rubygems.zh-cn.md" >}}) | Ruby | `gem`, `Bundler` | -| [Swift]({{< relref "doc/usage/packages/rubygems.zh-cn.md" >}}) | Swift | `swift` | -| [Vagrant]({{< relref "doc/usage/packages/vagrant.zh-cn.md" >}}) | - | `vagrant` | - -**以下段落仅适用于未全局禁用软件包的情况！** - -## 仓库 x 软件包 - -软件包始终属于所有者（用户或组织），而不是仓库。 -要将（已上传的）软件包链接到仓库，请打开该软件包的设置页面，并选择要将此软件包链接到的仓库。 -将链接到整个软件包，而不仅是单个版本。 - -链接软件包将导致在仓库的软件包列表中显示该软件包，并在软件包页面上显示到仓库的链接（以及到仓库工单的链接）。 - -## 访问限制 - -| 软件包所有者类型 | 用户 | 组织 | -| ---------------- | ---------------------------------------- | ------------------------------------------ | -| **读取** 访问 | 公开，如果用户也是公开的；否则仅限此用户 | 公开，如果组织是公开的，否则仅限组织成员 | -| **写入** 访问 | 仅软件包所有者 | 具有组织中的管理员或写入访问权限的组织成员 | - -注意：这些访问限制可能会[变化](https://github.com/go-gitea/gitea/issues/19270)，将通过专门的组织团队权限添加更细粒度的控制。 - -## 创建或上传软件包 - -根据软件包类型，使用相应的软件包管理器。请查看特定软件包管理器的子页面以获取说明。 - -## 查看软件包 - -您可以在仓库页面上查看仓库的软件包。 - -1. 转到仓库主页。 -2. 在导航栏中选择**软件包** - -要查看有关软件包的更多详细信息，请选择软件包的名称。 - -## 下载软件包 - -要从仓库下载软件包： - -1. 在导航栏中选择**软件包** -2. 选择软件包的名称以查看详细信息。 -3. 在 **Assets** 部分，选择要下载的软件包文件的名称。 - -## 删除软件包 - -在将软件包发布到软件包注册表后，您无法编辑软件包。相反，您必须删除并重新创建它。 - -要从仓库中删除软件包： - -1. 在导航栏中选择**软件包** -2. 选择软件包的名称以查看详细信息。 -3. 单击**删除软件包**以永久删除软件包。 - -## 禁用软件包注册表 - -包注册表已自动启用。要在单个存储库中禁用它： - -1. 在导航栏中选择**设置**。 -2. 禁用**启用仓库软件包注册表**. - -禁用软件包注册表不会删除先前发布的软件包。 diff --git a/docs/content/doc/usage/packages/pub.en-us.md b/docs/content/doc/usage/packages/pub.en-us.md deleted file mode 100644 index 823984d54d..0000000000 --- a/docs/content/doc/usage/packages/pub.en-us.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -date: "2022-07-31T00:00:00+00:00" -title: "Pub Package Registry" -slug: "pub" -weight: 90 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Pub" - weight: 90 - identifier: "pub" ---- - -# Pub Package Registry - -Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Pub package registry, you need to use the tools [dart](https://dart.dev/tools/dart-tool) and/or [flutter](https://docs.flutter.dev/reference/flutter-cli). - -The following examples use dart. - -## Configuring the package registry - -To register the package registry and provide credentials, execute: - -```shell -dart pub token add https://gitea.example.com/api/packages/{owner}/pub -``` - -| Placeholder | Description | -| ------------ | ----------- | -| `owner` | The owner of the package. | - -You need to provide your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). - -## Publish a package - -To publish a package, edit the `pubspec.yaml` and add the following line: - -```yaml -publish_to: https://gitea.example.com/api/packages/{owner}/pub -``` - -| Placeholder | Description | -| ------------ | ----------- | -| `owner` | The owner of the package. | - -Now you can publish the package by running the following command: - -```shell -dart pub publish -``` - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a Pub package from the package registry, execute the following command: - -```shell -dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/ -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | - -For example: - -```shell -# use latest version -dart pub add mypackage --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ -# specify version -dart pub add mypackage:1.0.8 --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ -``` diff --git a/docs/content/doc/usage/packages/pub.zh-cn.md b/docs/content/doc/usage/packages/pub.zh-cn.md deleted file mode 100644 index 9941a57089..0000000000 --- a/docs/content/doc/usage/packages/pub.zh-cn.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -date: "2022-07-31T00:00:00+00:00" -title: "Pub 软件包注册表" -slug: "pub" -weight: 90 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Pub" - weight: 90 - identifier: "pub" ---- - -# Pub 软件包注册表 - -为您的用户或组织发布 [Pub](https://dart.dev/guides/packages) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用Pub软件包注册表，您需要使用 [dart](https://dart.dev/tools/dart-tool) 和/或 [flutter](https://docs.flutter.dev/reference/flutter-cli). 工具。 - -以下示例使用 `dart`。 - -## 配置软件包注册表 - -要注册软件包注册表并提供凭据，请执行以下操作： - -```shell -dart pub token add https://gitea.example.com/api/packages/{owner}/pub -``` - -| 占位符 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -您需要提供您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})。 - -## 发布软件包 - -要发布软件包，请编辑 `pubspec.yaml` 文件，并添加以下行： - -```yaml -publish_to: https://gitea.example.com/api/packages/{owner}/pub -``` - -| 占位符 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -现在，您可以通过运行以下命令来发布软件包： - -```shell -dart pub publish -``` - -如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表安装Pub软件包，请执行以下命令： - -```shell -dart pub add {package_name} --hosted-url=https://gitea.example.com/api/packages/{owner}/pub/ -``` - -| 参数 | 描述 | -| -------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | - -例如： - -```shell -# use latest version -dart pub add mypackage --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ -# specify version -dart pub add mypackage:1.0.8 --hosted-url=https://gitea.example.com/api/packages/testuser/pub/ -``` diff --git a/docs/content/doc/usage/packages/pypi.en-us.md b/docs/content/doc/usage/packages/pypi.en-us.md deleted file mode 100644 index 822e3ab97c..0000000000 --- a/docs/content/doc/usage/packages/pypi.en-us.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "PyPI Package Registry" -slug: "pypi" -weight: 100 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "PyPI" - weight: 100 - identifier: "pypi" ---- - -# PyPI Package Registry - -Publish [PyPI](https://pypi.org/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the PyPI package registry, you need to use the tools [pip](https://pypi.org/project/pip/) to consume and [twine](https://pypi.org/project/twine/) to publish packages. - -## Configuring the package registry - -To register the package registry you need to edit your local `~/.pypirc` file. Add - -```ini -[distutils] -index-servers = gitea - -[gitea] -repository = https://gitea.example.com/api/packages/{owner}/pypi -username = {username} -password = {password} -``` - -| Placeholder | Description | -| ------------ | ----------- | -| `owner` | The owner of the package. | -| `username` | Your Gitea username. | -| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | - -## Publish a package - -Publish a package by running the following command: - -```shell -python3 -m twine upload --repository gitea /path/to/files/* -``` - -The package files have the extensions `.tar.gz` and `.whl`. - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a PyPI package from the package registry, execute the following command: - -```shell -pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `username` | Your Gitea username. | -| `password` | Your Gitea password or a personal access token. | -| `owner` | The owner of the package. | -| `package_name` | The package name. | - -For example: - -```shell -pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package -``` - -You can use `--extra-index-url` instead of `--index-url` but that makes you vulnerable to dependency confusion attacks because `pip` checks the official PyPi repository for the package before it checks the specified custom repository. Read the `pip` docs for more information. - -## Supported commands - -``` -pip install -twine upload -``` diff --git a/docs/content/doc/usage/packages/pypi.zh-cn.md b/docs/content/doc/usage/packages/pypi.zh-cn.md deleted file mode 100644 index 555fc4db43..0000000000 --- a/docs/content/doc/usage/packages/pypi.zh-cn.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "PyPI 软件包注册表" -slug: "pypi" -weight: 100 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "PyPI" - weight: 100 - identifier: "pypi" ---- - -# PyPI 软件包注册表 - -为您的用户或组织发布 [PyPI](https://pypi.org/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 PyPI 软件包注册表，您需要使用 [pip](https://pypi.org/project/pip/) 工具来消费和使用 [twine](https://pypi.org/project/twine/) 工具来发布软件包。 - -## 配置软件包注册表 - -要注册软件包注册表，您需要编辑本地的 `~/.pypirc` 文件。添加以下内容： - -```ini -[distutils] -index-servers = gitea - -[gitea] -repository = https://gitea.example.com/api/packages/{owner}/pypi -username = {username} -password = {password} -``` - -| 占位符 | 描述 | -| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `owner` | 软件包的所有者 | -| `username` | 您的 Gitea 用户名 | -| `password` | 您的 Gitea 密码。如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码 | - -## 发布软件包 - -通过运行以下命令来发布软件包： - -```shell -python3 -m twine upload --repository gitea /path/to/files/* -``` - -软件包文件的扩展名为 `.tar.gz` 和 `.whl`。 - -如果已存在具有相同名称和版本的软件包，则无法发布软件包。您必须先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表安装 PyPI 软件包，请执行以下命令： - -```shell -pip install --index-url https://{username}:{password}@gitea.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name} -``` - -| 参数 | 描述 | -| -------------- | ----------------------------- | -| `username` | 您的 Gitea 用户名 | -| `password` | 您的 Gitea 密码或个人访问令牌 | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | - -例如： - -```shell -pip install --index-url https://testuser:password123@gitea.example.com/api/packages/testuser/pypi/simple --no-deps test_package -``` - -您可以使用 `--extra-index-url` 替代 `--index-url`，但这样会使您容易受到依赖混淆攻击，因为 `pip` 会先检查官方 PyPi 仓库中的软件包，然后再检查指定的自定义仓库。请阅读 `pip` 文档以获取更多信息。 - -## 支持的命令 - -``` -pip install -twine upload -``` diff --git a/docs/content/doc/usage/packages/rpm.en-us.md b/docs/content/doc/usage/packages/rpm.en-us.md deleted file mode 100644 index 7a258f5c03..0000000000 --- a/docs/content/doc/usage/packages/rpm.en-us.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -date: "2023-03-08T00:00:00+00:00" -title: "RPM Package Registry" -slug: "rpm" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "RPM" - weight: 105 - identifier: "rpm" ---- - -# RPM Package Registry - -Publish [RPM](https://rpm.org/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the RPM registry, you need to use a package manager like `yum`, `dnf` or `zypper` to consume packages. - -The following examples use `dnf`. - -## Configuring the package registry - -To register the RPM registry add the url to the list of known apt sources: - -```shell -dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm.repo -``` - -| Placeholder | Description | -| ----------- | ----------- | -| `owner` | The owner of the package. | - -If the registry is private, provide credentials in the url. You can use a password or a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}): - -```shell -dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm.repo -``` - -You have to add the credentials to the urls in the `rpm.repo` file in `/etc/yum.repos.d` too. - -## Publish a package - -To publish a RPM package (`*.rpm`), perform a HTTP PUT operation with the package content in the request body. - -``` -PUT https://gitea.example.com/api/packages/{owner}/rpm/upload -``` - -| Parameter | Description | -| --------- | ----------- | -| `owner` | The owner of the package. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.rpm \ - https://gitea.example.com/api/packages/testuser/rpm/upload -``` - -If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. -You cannot publish a file with the same name twice to a package. You must delete the existing package version first. - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `201 Created` | The package has been published. | -| `400 Bad Request` | The package is invalid. | -| `409 Conflict` | A package file with the same combination of parameters exist already in the package. | - -## Delete a package - -To delete an RPM package perform a HTTP DELETE operation. This will delete the package version too if there is no file left. - -``` -DELETE https://gitea.example.com/api/packages/{owner}/rpm/{package_name}/{package_version}/{architecture} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version. | -| `architecture` | The package architecture. | - -Example request using HTTP Basic authentication: - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/rpm/test-package/1.0.0/x86_64 -``` - -The server responds with the following HTTP Status codes. - -| HTTP Status Code | Meaning | -| ----------------- | ------- | -| `204 No Content` | Success | -| `404 Not Found` | The package or file was not found. | - -## Install a package - -To install a package from the RPM registry, execute the following commands: - -```shell -# use latest version -dnf install {package_name} -# use specific version -dnf install {package_name}-{package_version}.{architecture} -``` diff --git a/docs/content/doc/usage/packages/rpm.zh-cn.md b/docs/content/doc/usage/packages/rpm.zh-cn.md deleted file mode 100644 index f76273e5a8..0000000000 --- a/docs/content/doc/usage/packages/rpm.zh-cn.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -date: "2023-03-08T00:00:00+00:00" -title: "RPM 软件包注册表" -slug: "packages/rpm" -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "RPM" - weight: 105 - identifier: "rpm" ---- - -# RPM 软件包注册表 - -为您的用户或组织发布 [RPM](https://rpm.org/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用RPM注册表，您需要使用像 `yum`, `dnf` 或 `zypper` 这样的软件包管理器来消费软件包。 - -以下示例使用 `dnf`。 - -## 配置软件包注册表 - -要注册RPM注册表，请将 URL 添加到已知 `apt` 源列表中： - -```shell -dnf config-manager --add-repo https://gitea.example.com/api/packages/{owner}/rpm.repo -``` - -| 占位符 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -如果注册表是私有的，请在URL中提供凭据。您可以使用密码或[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})： - -```shell -dnf config-manager --add-repo https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/rpm.repo -``` - -您还必须将凭据添加到 `/etc/yum.repos.d` 中的 `rpm.repo` 文件中的URL中。 - -## 发布软件包 - -要发布RPM软件包（`*.rpm`），请执行带有软件包内容的 HTTP `PUT` 操作。 - -``` -PUT https://gitea.example.com/api/packages/{owner}/rpm/upload -``` - -| 参数 | 描述 | -| ------- | -------------- | -| `owner` | 软件包的所有者 | - -使用HTTP基本身份验证的示例请求： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/file.rpm \ - https://gitea.example.com/api/packages/testuser/rpm/upload -``` - -如果您使用 2FA 或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})替代密码。您无法将具有相同名称的文件两次发布到软件包中。您必须先删除现有的软件包版本。 - -服务器将以以下HTTP状态码响应。 - -| HTTP 状态码 | 含义 | -| ----------------- | ------------------------------------------------ | -| `201 Created` | 软件包已发布 | -| `400 Bad Request` | 软件包无效 | -| `409 Conflict` | 具有相同参数组合的软件包文件已经存在于该软件包中 | - -## 删除软件包 - -要删除 RPM 软件包，请执行 HTTP `DELETE` 操作。如果没有文件剩余，这也将删除软件包版本。 - -``` -DELETE https://gitea.example.com/api/packages/{owner}/rpm/{package_name}/{package_version}/{architecture} -``` - -| 参数 | 描述 | -| ----------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | -| `package_version` | 软件包版本 | -| `architecture` | 软件包架构 | - -使用HTTP基本身份验证的示例请求： - -```shell -curl --user your_username:your_token_or_password -X DELETE \ - https://gitea.example.com/api/packages/testuser/rpm/test-package/1.0.0/x86_64 -``` - -服务器将以以下HTTP状态码响应： - -| HTTP 状态码 | 含义 | -| ---------------- | ------------------ | -| `204 No Content` | 成功 | -| `404 Not Found` | 未找到软件包或文件 | - -## 安装软件包 - -要从RPM注册表安装软件包，请执行以下命令： - -```shell -# use latest version -dnf install {package_name} -# use specific version -dnf install {package_name}-{package_version}.{architecture} -``` diff --git a/docs/content/doc/usage/packages/rubygems.en-us.md b/docs/content/doc/usage/packages/rubygems.en-us.md deleted file mode 100644 index 5cfebfc84a..0000000000 --- a/docs/content/doc/usage/packages/rubygems.en-us.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "RubyGems Package Registry" -slug: "rubygems" -weight: 110 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "RubyGems" - weight: 110 - identifier: "rubygems" ---- - -# RubyGems Package Registry - -Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the RubyGems package registry, you need to use the [gem](https://guides.rubygems.org/command-reference/) command line tool to consume and publish packages. - -## Configuring the package registry - -To register the package registry edit the `~/.gem/credentials` file and add: - -```ini ---- -https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token} -``` - -| Parameter | Description | -| ------------- | ----------- | -| `owner` | The owner of the package. | -| `token` | Your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}). | - -For example: - -``` ---- -https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4 -``` - -## Publish a package - -Publish a package by running the following command: - -```shell -gem push --host {host} {package_file} -``` - -| Parameter | Description | -| -------------- | ----------- | -| `host` | URL to the package registry. | -| `package_file` | Path to the package `.gem` file. | - -For example: - -```shell -gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem -``` - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a package from the package registry you can use [Bundler](https://bundler.io) or `gem`. - -### Bundler - -Add a new `source` block to your `Gemfile`: - -``` -source "https://gitea.example.com/api/packages/{owner}/rubygems" do - gem "{package_name}" -end -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | - -For example: - -``` -source "https://gitea.example.com/api/packages/testuser/rubygems" do - gem "test_package" -end -``` - -Afterwards run the following command: - -```shell -bundle install -``` - -### gem - -Execute the following command: - -```shell -gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name} -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | - -For example: - -```shell -gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package -``` - -## Supported commands - -``` -gem install -bundle install -gem push -``` diff --git a/docs/content/doc/usage/packages/rubygems.zh-cn.md b/docs/content/doc/usage/packages/rubygems.zh-cn.md deleted file mode 100644 index f3416c239e..0000000000 --- a/docs/content/doc/usage/packages/rubygems.zh-cn.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -date: "2021-07-20T00:00:00+00:00" -title: "RubyGems 软件包注册表" -slug: "rubygems" -weight: 110 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "RubyGems" - weight: 110 - identifier: "rubygems" ---- - -# RubyGems 软件包注册表 - -为您的用户或组织发布 [RubyGems](https://guides.rubygems.org/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用RubyGems软件包注册表，您需要使用 [gem](https://guides.rubygems.org/command-reference/) 命令行工具来消费和发布软件包。 - -## 配置软件包注册表 - -要注册软件包注册表，请编辑 `~/.gem/credentials` 文件并添加： - -```ini ---- -https://gitea.example.com/api/packages/{owner}/rubygems: Bearer {token} -``` - -| 参数 | 描述 | -| ------- | ------------------------------------------------------------------------------------- | -| `owner` | 软件包的所有者 | -| `token` | 您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}}) | - -例如： - -``` ---- -https://gitea.example.com/api/packages/testuser/rubygems: Bearer 3bd626f84b01cd26b873931eace1e430a5773cc4 -``` - -## 发布软件包 - -通过运行以下命令来发布软件包： - -```shell -gem push --host {host} {package_file} -``` - -| 参数 | 描述 | -| -------------- | ------------------------ | -| `host` | 软件包注册表的URL | -| `package_file` | 软件包 `.gem` 文件的路径 | - -例如： - -```shell -gem push --host https://gitea.example.com/api/packages/testuser/rubygems test_package-1.0.0.gem -``` - -如果已经存在相同名称和版本的软件包，您将无法发布软件包。您必须先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表安装软件包，您可以使用 [Bundler](https://bundler.io) 或 `gem`。 - -### Bundler - -在您的 `Gemfile` 中添加一个新的 `source` 块： - -``` -source "https://gitea.example.com/api/packages/{owner}/rubygems" do - gem "{package_name}" -end -``` - -| 参数 | 描述 | -| -------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | - -例如： - -``` -source "https://gitea.example.com/api/packages/testuser/rubygems" do - gem "test_package" -end -``` - -之后运行以下命令： - -```shell -bundle install -``` - -### gem - -执行以下命令： - -```shell -gem install --host https://gitea.example.com/api/packages/{owner}/rubygems {package_name} -``` - -| 参数 | 描述 | -| -------------- | -------------- | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包名称 | - -例如： - -```shell -gem install --host https://gitea.example.com/api/packages/testuser/rubygems test_package -``` - -## 支持的命令 - -``` -gem install -bundle install -gem push -``` diff --git a/docs/content/doc/usage/packages/storage.en-us.md b/docs/content/doc/usage/packages/storage.en-us.md deleted file mode 100644 index bf500f3bc1..0000000000 --- a/docs/content/doc/usage/packages/storage.en-us.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -date: "2022-11-01T00:00:00+00:00" -title: "Storage" -slug: "storage" -weight: 5 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Storage" - weight: 2 - identifier: "storage" ---- - -# Storage - -This document describes the storage of the package registry and how it can be managed. - -**Table of Contents** - -{{< toc >}} - -## Deduplication - -The package registry has a build-in deduplication of uploaded blobs. -If two identical files are uploaded only one blob is saved on the filesystem. -This ensures no space is wasted for duplicated files. - -If two packages are uploaded with identical files, both packages will display the same size but on the filesystem they require only half of the size. -Whenever a package gets deleted, only the references to the underlying blobs are removed. -The blobs get not removed at this moment, so they still require space on the filesystem. -When a new package gets uploaded the existing blobs may get referenced again. - -These unreferenced blobs get deleted by a [clean up job]({{< relref "doc/administration/config-cheat-sheet.en-us.md#cron---cleanup-expired-packages-croncleanup_packages" >}}). -The config setting `OLDER_THAN` configures how long unreferenced blobs are kept before they get deleted. - -## Cleanup Rules - -Package registries can become large over time without cleanup. -It's recommended to delete unnecessary packages and set up cleanup rules to automatically manage the package registry usage. -Every package owner (user or organization) manages the cleanup rules which are applied to their packages. - -|Setting|Description| -|-|-| -|Enabled|Turn the cleanup rule on or off.| -|Type|Every rule manages a specific package type.| -|Apply pattern to full package name|If enabled, the patterns below are applied to the full package name (`package/version`). Otherwise only the version (`version`) is used.| -|Keep the most recent|How many versions to *always* keep for each package.| -|Keep versions matching|The regex pattern that determines which versions to keep. An empty pattern keeps no version while `.+` keeps all versions. The container registry will always keep the `latest` version even if not configured.| -|Remove versions older than|Remove only versions older than the selected days.| -|Remove versions matching|The regex pattern that determines which versions to remove. An empty pattern or `.+` leads to the removal of every package if no other setting tells otherwise.| - -Every cleanup rule can show a preview of the affected packages. -This can be used to check if the cleanup rules is proper configured. - -### Regex examples - -Regex patterns are automatically surrounded with `\A` and `\z` anchors. -Do not include any `\A`, `\z`, `^` or `$` token in the regex patterns as they are not necessary. -The patterns are case-insensitive which matches the behaviour of the package registry in Gitea. - -|Pattern|Description| -|-|-| -|`.*`|Match every possible version.| -|`v.+`|Match versions that start with `v`.| -|`release`|Match only the version `release`.| -|`release.*`|Match versions that are either named or start with `release`.| -|`.+-temp-.+`|Match versions that contain `-temp-`.| -|`v.+\|release`|Match versions that either start with `v` or are named `release`.| -|`package/v.+\|other/release`|Match versions of the package `package` that start with `v` or the version `release` of the package `other`. This needs the setting *Apply pattern to full package name* enabled.| - -### How the cleanup rules work - -The cleanup rules are part of the [clean up job]({{< relref "doc/administration/config-cheat-sheet.en-us.md#cron---cleanup-expired-packages-croncleanup_packages" >}}) and run periodically. - -The cleanup rule: - -1. Collects all packages of the package type for the owners registry. -2. For every package it collects all versions. -3. Excludes from the list the # versions based on the *Keep the most recent* value. -4. Excludes from the list any versions matching the *Keep versions matching* value. -5. Excludes from the list the versions more recent than the *Remove versions older than* value. -6. Excludes from the list any versions not matching the *Remove versions matching* value. -7. Deletes the remaining versions. diff --git a/docs/content/doc/usage/packages/storage.zh-cn.md b/docs/content/doc/usage/packages/storage.zh-cn.md deleted file mode 100644 index 7845f40cf8..0000000000 --- a/docs/content/doc/usage/packages/storage.zh-cn.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -date: "2022-11-01T00:00:00+00:00" -title: "存储" -slug: "storage" -weight: 5 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Storage" - weight: 2 - identifier: "storage" ---- - -# 存储 - -本文档描述了软件包注册表的存储方式以及如何管理存储。 - -**目录** - -{{< toc >}} - -## 去重 - -软件包注册表具有内置的去重功能，可以对上传的 Blob 进行去重处理。 -如果上传了两个相同的文件，只会在文件系统上保存一个 Blob。 -这样可以确保不会浪费空间用于重复的文件。 - -如果上传了两个具有相同文件的软件包，这两个软件包将显示相同的大小，但在文件系统上，它们只需要一半的大小。 -每当删除一个软件包时，只会删除对底层 Blob 的引用。 -此时，Blob 不会被删除，因此它们仍然占用文件系统上的空间。 -当上传新的软件包时，现有的 Blob 可能会再次被引用。 - -这些无引用的 Blob 会在一个清理任务中被删除。 -配置设置 `OLDER_THAN` 可以配置无引用的 Blob 在被删除之前保留的时间。 - -## 清理规则 - -软件包注册表可能会随着时间的推移而变得很大，如果不进行清理的话。 -建议删除不必要的软件包并设置清理规则以自动管理软件包注册表的使用情况。 -每个软件包所有者（用户或组织）都可以管理应用于其软件包的清理规则。 - -| 设置 | 描述 | -| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| 启用 | 打开或关闭清理规则。 | -| 类型 | 每个规则管理特定的软件包类型。 | -| 将模式应用于完整的软件包名称 | 如果启用，则应用以下模式到完整的软件包名称（`package/version`），否则只使用版本号（`version`）。 | -| 保留最近的版本数 | 对于每个软件包要始终保留的版本数量。 | -| 保留与以下模式匹配的版本 | 确定要保留哪些版本的正则表达式模式。空模式表示不保留任何版本，而 `.+` 表示保留所有版本。即使未配置，容器注册表也始终保留 `latest` 版本。 | -| 删除早于多少天的版本 | 仅删除早于所选天数的版本。 | -| 删除与以下模式匹配的版本 | 确定要删除哪些版本的正则表达式模式。空模式或 `.+` 表示如果没有其他设置指定，则删除所有软件包。 | - -每个清理规则都可以显示受影响的软件包的预览。 -这可以用来检查清理规则是否正确配置。 - -### 正则表达式示例 - -正则表达式模式会自动使用 `\A` 和 `\z` 锚点进行包围。 -不要在正则表达式模式中包含任何 `\A`、`\z`、`^` 或 `$` 标记，因为它们不是必要的。 -模式是不区分大小写的，与 Gitea 中的软件包注册表的行为相匹配。 - -| Pattern | Description | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------- | -| `.*` | 匹配任何可能的版本。 | -| `v.+` | 匹配以 `v` 开头的版本。 | -| `release` | 仅匹配版本号为 `release`。 | -| `release.*` | 匹配以 `release` 命名或以 `release` 开头的版本。 | -| `.+-temp-.+` | 匹配包含 `-temp-` 的版本。 | -| `v.+\|release` | 匹配以 `v` 开头的版本或版本号为 `release`。 | -| `package/v.+\|other/release` | 匹配以 `v` 开头的 package 的版本或 `other` 的版本号为 `release`。需要启用*将模式应用于完整的软件包名称*设置。 | - -### 清理规则的工作原理 - -清理规则是清理任务的一部分，定期运行。 - -清理规则： - -1. 收集所有属于所有者注册表的特定软件包类型的软件包。 -2. 对于每个软件包，收集所有版本。 -3. 根据 *保留最近的版本数* 的值，从列表中排除版本。 -4. 根据 *保留与以下模式匹配的版本* 的值，从列表中排除任何版本。 -5. 根据 *删除早于多少天的版本* 的值，从列表中排除比这个值更近的版本。 -6. 根据 *删除与以下模式匹配的版本* 的值，从列表中排除任何不匹配的版本。 -7. 删除剩余的版本。 diff --git a/docs/content/doc/usage/packages/swift.en-us.md b/docs/content/doc/usage/packages/swift.en-us.md deleted file mode 100644 index 6d4d0f24b4..0000000000 --- a/docs/content/doc/usage/packages/swift.en-us.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -date: "2023-01-10T00:00:00+00:00" -title: "Swift Package Registry" -slug: "swift" -weight: 95 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Swift" - weight: 95 - identifier: "swift" ---- - -# Swift Package Registry - -Publish [Swift](https://www.swift.org/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Swift package registry, you need to use [swift](https://www.swift.org/getting-started/) to consume and a HTTP client (like `curl`) to publish packages. - -## Configuring the package registry - -To register the package registry and provide credentials, execute: - -```shell -swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password} -``` - -| Placeholder | Description | -| ------------ | ----------- | -| `owner` | The owner of the package. | -| `username` | Your Gitea username. | -| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | - -The login is optional and only needed if the package registry is private. - -## Publish a package - -First you have to pack the contents of your package: - -```shell -swift package archive-source -``` - -To publish the package perform a HTTP PUT request with the package content in the request body. - -```shell --user your_username:your_password_or_token \ -curl -X PUT --user {username}:{password} \ - -H "Accept: application/vnd.swift.registry.v1+json" \ - -F source-archive=@/path/to/package.zip \ - -F metadata={metadata} \ - https://gitea.example.com/api/packages/{owner}/swift/{scope}/{name}/{version} -``` - -| Placeholder | Description | -| ----------- | ----------- | -| `username` | Your Gitea username. | -| `password` | Your Gitea password. If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password. | -| `owner` | The owner of the package. | -| `scope` | The package scope. | -| `name` | The package name. | -| `version` | The package version. | -| `metadata` | (Optional) The metadata of the package. JSON encoded subset of https://schema.org/SoftwareSourceCode | - -You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first. - -## Install a package - -To install a Swift package from the package registry, add it in the `Package.swift` file dependencies list: - -``` -dependencies: [ - .package(id: "{scope}.{name}", from:"{version}") -] -``` - -| Parameter | Description | -| ----------- | ----------- | -| `scope` | The package scope. | -| `name` | The package name. | -| `version` | The package version. | - -Afterwards execute the following command to install it: - -```shell -swift package resolve -``` diff --git a/docs/content/doc/usage/packages/swift.zh-cn.md b/docs/content/doc/usage/packages/swift.zh-cn.md deleted file mode 100644 index 9c627416ad..0000000000 --- a/docs/content/doc/usage/packages/swift.zh-cn.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -date: "2023-01-10T00:00:00+00:00" -title: "Swift 软件包注册表" -slug: "swift" -weight: 95 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Swift" - weight: 95 - identifier: "swift" ---- - -# Swift 软件包注册表 - -为您的用户或组织发布 [Swift](https://www.swift.org/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Swift 软件包注册表，您需要使用 [swift](https://www.swift.org/getting-started/) 消费软件包，并使用 HTTP 客户端（如 `curl`）发布软件包。 - -## 配置软件包注册表 - -要注册软件包注册表并提供凭据，请执行以下命令： - -```shell -swift package-registry set https://gitea.example.com/api/packages/{owner}/swift -login {username} -password {password} -``` - -| 占位符 | 描述 | -| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `owner` | 软件包的所有者。 | -| `username` | 您的 Gitea 用户名。 | -| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 | - -登录是可选的，只有在软件包注册表是私有的情况下才需要。 - -## 发布软件包 - -首先，您需要打包软件包的内容： - -```shell -swift package archive-source -``` - -要发布软件包，请执行一个带有软件包内容的 HTTP `PUT` 请求，将内容放在请求正文中。 - -```shell --user your_username:your_password_or_token \ -curl -X PUT --user {username}:{password} \ - -H "Accept: application/vnd.swift.registry.v1+json" \ - -F source-archive=@/path/to/package.zip \ - -F metadata={metadata} \ - https://gitea.example.com/api/packages/{owner}/swift/{scope}/{name}/{version} -``` - -| 占位符 | 描述 | -| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `username` | 您的 Gitea 用户名。 | -| `password` | 您的 Gitea 密码。如果您使用两步验证或 OAuth，请使用[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})代替密码。 | -| `owner` | 软件包的所有者。 | -| `scope` | 软件包的作用域。 | -| `name` | 软件包的名称。 | -| `version` | 软件包的版本。 | -| `metadata` | （可选）软件包的元数据。以 JSON 编码的子集，格式参考 https://schema.org/SoftwareSourceCode | - -如果已经存在相同名称和版本的软件包，则无法发布软件包。您必须首先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表安装 Swift 软件包，请将其添加到 `Package.swift` 文件的依赖项列表中： - -``` -dependencies: [ - .package(id: "{scope}.{name}", from:"{version}") -] -``` - -| 参数 | 描述 | -| --------- | -------------- | -| `scope` | 软件包的作用域 | -| `name` | 软件包的名称 | -| `version` | 软件包的版本 | - -之后，执行以下命令来安装它： - -```shell -swift package resolve -``` diff --git a/docs/content/doc/usage/packages/vagrant.en-us.md b/docs/content/doc/usage/packages/vagrant.en-us.md deleted file mode 100644 index 583bbc199b..0000000000 --- a/docs/content/doc/usage/packages/vagrant.en-us.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -date: "2022-08-23T00:00:00+00:00" -title: "Vagrant Package Registry" -slug: "vagrant" -weight: 120 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Vagrant" - weight: 120 - identifier: "vagrant" ---- - -# Vagrant Package Registry - -Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization. - -**Table of Contents** - -{{< toc >}} - -## Requirements - -To work with the Vagrant package registry, you need [Vagrant](https://www.vagrantup.com/downloads) and a tool to make HTTP requests like `curl`. - -## Publish a package - -Publish a Vagrant box by performing a HTTP PUT request to the registry: - -``` -PUT https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box -``` - -| Parameter | Description | -| ----------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | -| `package_version` | The package version, semver compatible. | -| `provider` | One of the [supported provider names](https://www.vagrantup.com/docs/providers). | - -Example for uploading a Hyper-V box: - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/your/vagrant.box \ - https://gitea.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box -``` - -You cannot publish a box if a box of the same name, version and provider already exists. You must delete the existing package first. - -## Install a package - -To install a box from the package registry, execute the following command: - -```shell -vagrant box add "https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}" -``` - -| Parameter | Description | -| -------------- | ----------- | -| `owner` | The owner of the package. | -| `package_name` | The package name. | - -For example: - -```shell -vagrant box add "https://gitea.example.com/api/packages/testuser/vagrant/test_system" -``` - -This will install the latest version of the package. To add a specific version, use the `--box-version` parameter. -If the registry is private you can pass your [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) in the `VAGRANT_CLOUD_TOKEN` environment variable. - -## Supported commands - -``` -vagrant box add -``` diff --git a/docs/content/doc/usage/packages/vagrant.zh-cn.md b/docs/content/doc/usage/packages/vagrant.zh-cn.md deleted file mode 100644 index ddcec9e4c9..0000000000 --- a/docs/content/doc/usage/packages/vagrant.zh-cn.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -date: "2022-08-23T00:00:00+00:00" -title: "Vagrant 软件包注册表" -slug: "vagrant" -weight: 120 -draft: false -toc: false -menu: - sidebar: - parent: "packages" - name: "Vagrant" - weight: 120 - identifier: "vagrant" ---- - -# Vagrant 软件包注册表 - -为您的用户或组织发布 [Vagrant](https://www.vagrantup.com/) 软件包。 - -**目录** - -{{< toc >}} - -## 要求 - -要使用 Vagrant 软件包注册表，您需要安装 [Vagrant](https://www.vagrantup.com/downloads) 并使用类似于 `curl` 的工具进行 HTTP 请求。 - -## 发布软件包 - -通过执行 HTTP PUT 请求将 Vagrant box 发布到注册表： - -``` -PUT https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box -``` - -| 参数 | 描述 | -| ----------------- | ------------------------------------------------------------------ | -| `owner` | 软件包的所有者 | -| `package_name` | 软件包的名称 | -| `package_version` | 软件包的版本，兼容 semver 格式 | -| `provider` | [支持的提供程序名称](https://www.vagrantup.com/docs/providers)之一 | - -上传 Hyper-V box 的示例： - -```shell -curl --user your_username:your_password_or_token \ - --upload-file path/to/your/vagrant.box \ - https://gitea.example.com/api/packages/testuser/vagrant/test_system/1.0.0/hyperv.box -``` - -如果已经存在相同名称、版本和提供程序的软件包，则无法发布软件包。您必须首先删除现有的软件包。 - -## 安装软件包 - -要从软件包注册表安装软件包，请执行以下命令： - -```shell -vagrant box add "https://gitea.example.com/api/packages/{owner}/vagrant/{package_name}" -``` - -| 参数 | 描述 | -| -------------- | --------------- | -| `owner` | 软件包的所有者. | -| `package_name` | 软件包的名称 | - -例如： - -```shell -vagrant box add "https://gitea.example.com/api/packages/testuser/vagrant/test_system" -``` - -这将安装软件包的最新版本。要添加特定版本，请使用` --box-version` 参数。 -如果注册表是私有的，您可以将您的[个人访问令牌]({{< relref "doc/development/api-usage.zh-cn.md#通过-api-认证" >}})传递给 `VAGRANT_CLOUD_TOKEN` 环境变量。 - -## 支持的命令 - -``` -vagrant box add -``` diff --git a/docs/content/doc/usage/permissions.en-us.md b/docs/content/doc/usage/permissions.en-us.md deleted file mode 100644 index 655c67de86..0000000000 --- a/docs/content/doc/usage/permissions.en-us.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -date: "2021-12-13:10:10+08:00" -title: "Permissions" -slug: "permissions" -weight: 14 -toc: false -draft: false -aliases: - - /en-us/permissions -menu: - sidebar: - parent: "usage" - name: "Permissions" - weight: 14 - identifier: "permissions" ---- - -# Permissions - -**Table of Contents** - -{{< toc >}} - -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. diff --git a/docs/content/doc/usage/permissions.zh-cn.md b/docs/content/doc/usage/permissions.zh-cn.md deleted file mode 100644 index 3163633589..0000000000 --- a/docs/content/doc/usage/permissions.zh-cn.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "权限" -slug: "permissions" -weight: 14 -toc: false -draft: false -aliases: - - /zh-cn/permissions -menu: - sidebar: - parent: "usage" - name: "权限" - weight: 14 - identifier: "permissions" ---- - -# 权限 - -**目录** - -{{< toc >}} - -Gitea 支持对仓库进行权限管理，这样您就可以为不同的人员提供不同的访问权限。首先，我们需要了解 `单元（Unit）`。 - -## 单元（Unit） - -在 Gitea 中，我们将仓库的子模块称为 `单元（Unit）`。现在我们有以下几个单元。 - -| 名称 | 描述 | 权限 | -| ----------------- | --------------------------------------------------- | ------------ | -| 代码 | 访问源代码、文件、提交和分支。 | 读取 写入 | -| 工单 | 组织缺陷报告、任务和里程碑。 | 读取 写入 | -| 合并请求 | 启用合并请求和代码审核。 | 读取 写入 | -| 发布 | 跟踪项目版本和下载。 | 读取 写入 | -| 维基 | 与协作者编写和共享文档。 | 读取 写入 | -| 外部维基 | 链接到外部维基。 | 读取 | -| 外部工单跟踪器 | 链接到外部工单跟踪器。 | 读取 | -| 项目 | 模板仓库的 URL。 | 读取 写入 | -| 设置 | 管理仓库。 | 管理员 | - -通过不同的权限，用户可以在这些单元上执行不同的操作。 - -| 名称 | 读取 | 写入 | 管理员 | -| ----------------- | -------------------------------------------------- | ------------------------------ | ------------------------- | -| 代码 | 查看代码树、文件、提交、分支等。 | 推送代码。 | - | -| 工单 | 查看工单并创建新工单。 | 添加标签、分配、关闭工单。 | - | -| 合并请求 | 查看合并请求并创建新合并请求。 | 添加标签、分配、关闭合并请求。 | - | -| 发布 | 查看发布和下载文件。 | 创建/编辑发布。 | - | -| 维基 | 查看维基页面。克隆维基仓库。 | 创建/编辑维基页面，推送更改。 | - | -| 外部维基 | 链接到外部维基。 | - | - | -| 外部工单跟踪器 | 链接到外部工单跟踪器。 | - | - | -| 项目 | 查看面板。 | 在面板之间移动工单。 | - | -| 设置 | - | - | 管理仓库 | - -个人仓库和组织仓库之间的权限存在一些差异。 - -## 个人仓库 - -对于个人仓库，创建者是仓库的唯一所有者，对于该仓库的任何更改或删除没有限制。仓库所有者可以添加协作者来帮助维护仓库。协作者可以拥有 `读取（Read）`、`写入（Write）` 和 `管理员（Admin）` 权限。 - -## 组织仓库 - -与个人仓库不同，组织仓库的所有者是组织的所有者团队。 - -### 团队 - -组织中的一个团队具有单元权限设置。它可以拥有成员和仓库的范围。团队可以访问组织中的所有仓库或者由所有者团队授权访问的特定仓库。团队也可以被允许创建新的仓库。 - -所有者团队（Owners）将在创建组织时自动创建，并且创建者将成为所有者团队的第一个成员。 -组织的每个成员必须至少属于一个团队。所有者团队不能被删除，只有所有者团队的成员可以创建新的团队。可以创建一个管理员团队来管理某些仓库，该团队的成员可以对这些仓库进行任何操作。可以由所有者团队创建一个生成团队来执行其权限允许的操作。 diff --git a/docs/content/doc/usage/profile-readme.en-us.md b/docs/content/doc/usage/profile-readme.en-us.md deleted file mode 100644 index a290eadbb1..0000000000 --- a/docs/content/doc/usage/profile-readme.en-us.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -date: "2023-03-02T21:00:00+05:00" -title: "Profile READMEs" -slug: "profile-readme" -weight: 12 -toc: false -draft: false -menu: - sidebar: - parent: "usage" - name: "Profile READMEs" - weight: 12 - identifier: "profile-readme" ---- - -# Profile READMEs - -To display a markdown file in your Gitea profile page, simply make a repository named ".profile" and edit the README.md file inside. Gitea will automatically pull this file in and display it above your repositories. - -Note. You are welcome to make this repository private. Doing so will hide your source files from public viewing and allow you to privitize certain files. However, the README.md file will be the only file present on your profile. If you wish to have an entirely private .profile repository, remove or rename the README.md file. diff --git a/docs/content/doc/usage/profile-readme.zh-cn.md b/docs/content/doc/usage/profile-readme.zh-cn.md deleted file mode 100644 index a253fcaf24..0000000000 --- a/docs/content/doc/usage/profile-readme.zh-cn.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "个人资料 README" -slug: "profile-readme" -weight: 12 -toc: false -draft: false -menu: - sidebar: - parent: "usage" - name: "个人资料 README" - weight: 12 - identifier: "profile-readme" ---- - -# 个人资料 README - -要在您的 Gitea 个人资料页面显示一个 Markdown 文件，只需创建一个名为 ".profile" 的仓库，并编辑其中的 README.md 文件。Gitea 将自动获取该文件并在您的仓库上方显示。 - -注意：您可以将此仓库设为私有。这样可以隐藏您的源文件，使其对公众不可见，并允许您将某些文件设为私有。但是，README.md 文件将是您个人资料上唯一存在的文件。如果您希望完全私有化 .profile 仓库，则需删除或重命名 README.md 文件。 diff --git a/docs/content/doc/usage/protected-tags.en-us.md b/docs/content/doc/usage/protected-tags.en-us.md deleted file mode 100644 index c5e763659d..0000000000 --- a/docs/content/doc/usage/protected-tags.en-us.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -date: "2021-05-14T00:00:00-00:00" -title: "Protected tags" -slug: "protected-tags" -weight: 45 -toc: false -draft: false -aliases: - - /en-us/protected-tags -menu: - sidebar: - parent: "usage" - name: "Protected tags" - weight: 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. - -**Table of Contents** - -{{< toc >}} - -## 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 | diff --git a/docs/content/doc/usage/protected-tags.zh-cn.md b/docs/content/doc/usage/protected-tags.zh-cn.md deleted file mode 100644 index 7d43462d32..0000000000 --- a/docs/content/doc/usage/protected-tags.zh-cn.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "受保护的标签" -slug: "protected-tags" -weight: 45 -toc: false -draft: false -aliases: - - /zh-cn/protected-tags -menu: - sidebar: - parent: "usage" - name: "受保护的标签" - weight: 45 - identifier: "protected-tags" ---- - -# 受保护的标签 - -受保护的标签允许控制谁有权限创建或更新 Git 标签。每个规则可以匹配单个标签名称，或者使用适当的模式来同时控制多个标签。 - -**目录** - -{{< toc >}} - -## 设置受保护的标签 - -要保护一个标签，你需要按照以下步骤进行操作： - -1. 进入仓库的**设置** > **标签**页面。 -2. 输入一个用于匹配名称的模式。你可以使用单个名称、[glob 模式](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正则表达式。 -3. 选择允许的用户和/或团队。如果将这些字段留空，则不允许任何人创建或修改此标签。 -4. 选择**保存**以保存配置。 - -## 模式受保护的标签 - -该模式使用 [glob](https://pkg.go.dev/github.com/gobwas/glob#Compile) 或正则表达式来匹配标签名称。对于正则表达式，你需要将模式括在斜杠中。 - -示例： - -| 类型 | 模式受保护的标签 | 可能匹配的标签 | -| ----- | ------------------------ | --------------------------------------- | -| Glob | `v*` | `v`，`v-1`，`version2` | -| Glob | `v[0-9]` | `v0`，`v1` 到 `v9` | -| Glob | `*-release` | `2.1-release`，`final-release` | -| Glob | `gitea` | 仅限 `gitea` | -| Glob | `*gitea*` | `gitea`，`2.1-gitea`，`1_gitea-release` | -| Glob | `{v,rel}-*` | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` | -| Glob | `*` | 匹配所有可能的标签名称 | -| Regex | `/\Av/` | `v`，`v-1`，`version2` | -| Regex | `/\Av[0-9]\z/` | `v0`，`v1` 到 `v9` | -| Regex | `/\Av\d+\.\d+\.\d+\z/` | `v1.0.17`，`v2.1.0` | -| Regex | `/\Av\d+(\.\d+){0,2}\z/` | `v1`，`v2.1`，`v1.2.34` | -| Regex | `/-release\z/` | `2.1-release`，`final-release` | -| Regex | `/gitea/` | `gitea`，`2.1-gitea`，`1_gitea-release` | -| Regex | `/\Agitea\z/` | 仅限 `gitea` | -| Regex | `/^gitea$/` | 仅限 `gitea` | -| Regex | `/\A(v\|rel)-/` | `v-`，`v-1`，`v-final`，`rel-`，`rel-x` | -| Regex | `/.+/` | 匹配所有可能的标签名称 | diff --git a/docs/content/doc/usage/pull-request.en-us.md b/docs/content/doc/usage/pull-request.en-us.md deleted file mode 100644 index f9f4b38555..0000000000 --- a/docs/content/doc/usage/pull-request.en-us.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -date: "2018-06-01T19:00:00+02:00" -title: "Pull Request" -slug: "pull-request" -weight: 13 -toc: false -draft: false -aliases: - - /en-us/pull-request -menu: - sidebar: - parent: "usage" - name: "Pull Request" - weight: 13 - identifier: "pull-request" ---- - -# Pull Request - -A Pull Request (PR) is a way to propose changes to a repository. -It is a request to merge one branch into another, accompanied by a description of the changes that were made. -Pull Requests are commonly used as a way for contributors to propose changes and for maintainers to review and merge those changes. - -## Creating a pull request - -To create a PR, you'll need to follow these steps: - -1. **Fork the repository** - If you don't have permission to make changes to the repository directly, you'll need to fork the repository to your own account. -This creates a copy of the repository that you can make changes to. - -2. **Create a branch (optional)** - Create a new branch on your forked repository that contains the changes you want to propose. -Give the branch a descriptive name that indicates what the changes are for. - -3. **Make your changes** - Make the changes you want, commit, and push them to your forked repository. - -4. **Create the PR** - Go to the original repository and go to the "Pull Requests" tab. Click the "New Pull Request" button and select your new branch as the source branch. -Enter a descriptive title and description for your Pull Request and click "Create Pull Request". - -## Reviewing a pull request - -When a PR is created, it triggers a review process. The maintainers of the repository are notified of the PR and can review the changes that were made. -They can leave comments, request changes, or approve the changes. - -If the maintainers request changes, you'll need to make those changes in your branch and push the changes to your forked repository. -The PR will be updated automatically with the new changes. - -If the maintainers approve the changes, they can merge the PR into the repository. - -## Closing a pull request - -If you decide that you no longer want to merge a PR, you can close it. -To close a PR, go to the open PR and click the "Close Pull Request" button. This will close the PR without merging it. - -## "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). diff --git a/docs/content/doc/usage/pull-request.zh-cn.md b/docs/content/doc/usage/pull-request.zh-cn.md deleted file mode 100644 index baf57787c8..0000000000 --- a/docs/content/doc/usage/pull-request.zh-cn.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -date: "2018-06-01T19:00:00+02:00" -title: "合并请求" -slug: "pull-request" -weight: 13 -toc: false -draft: false -aliases: - - /zh-cn/pull-request -menu: - sidebar: - parent: "usage" - name: "Pull Request" - weight: 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) diff --git a/docs/content/doc/usage/pull-request.zh-tw.md b/docs/content/doc/usage/pull-request.zh-tw.md deleted file mode 100644 index 9bbfa87863..0000000000 --- a/docs/content/doc/usage/pull-request.zh-tw.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -date: "2018-06-01T19:00:00+02:00" -title: "合併請求" -slug: "pull-request" -weight: 13 -toc: false -draft: false -aliases: - - /zh-tw/pull-request -menu: - sidebar: - parent: "usage" - name: "合併請求" - weight: 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)找到更多關於合併請求範本的資訊。 diff --git a/docs/content/doc/usage/push.en-us.md b/docs/content/doc/usage/push.en-us.md deleted file mode 100644 index 45190d88ca..0000000000 --- a/docs/content/doc/usage/push.en-us.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -date: "2020-07-06T16:00:00+02:00" -title: "Push" -slug: "push" -weight: 15 -toc: false -draft: false -aliases: - - /en-us/push-to-create - - /en-us/push-options -menu: - sidebar: - parent: "usage" - name: "Push" - weight: 15 - identifier: "push" ---- - -**Table of Contents** - -{{< toc >}} - -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]({{< relref "doc/administration/config-cheat-sheet.en-us.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`. diff --git a/docs/content/doc/usage/push.zh-cn.md b/docs/content/doc/usage/push.zh-cn.md deleted file mode 100644 index a12e1b5349..0000000000 --- a/docs/content/doc/usage/push.zh-cn.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "推送" -slug: "push" -weight: 15 -toc: false -draft: false -aliases: - - /zh-cn/push-to-create - - /zh-cn/push-options -menu: - sidebar: - parent: "usage" - name: "推送" - weight: 15 - identifier: "push" ---- - -**目录** - -{{< toc >}} - -在将提交推送到 Gitea 服务器时，还有一些额外的功能。 - -# 通过推送打开 PR - -当您第一次将提交推送到非默认分支时，您将收到一个链接，您可以单击该链接访问分支与主分支的比较页面。 -从那里，您可以轻松创建一个拉取请求，即使您想要将其目标指向另一个分支。 - - - -# 推送选项 - -在 Gitea `1.13` 版本中，添加了对一些 [推送选项](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) 的支持。 - -## 支持的选项 - -- `repo.private` (true|false) - 更改仓库的可见性。 - - 这在与 push-to-create 结合使用时特别有用。 - -- `repo.template` (true|false) - 更改仓库是否为模板。 - -将仓库的可见性更改为公开的示例： - -```shell -git push -o repo.private=false -u origin main -``` - -# 推送创建 - -推送创建是一项功能，允许您将提交推送到在 Gitea 中尚不存在的仓库。这对于自动化和允许用户创建仓库而无需通过 Web 界面非常有用。此功能默认处于禁用状态。 - -## 启用推送创建 - -在 `app.ini` 文件中，将 `ENABLE_PUSH_CREATE_USER` 设置为 `true`，如果您希望允许用户在自己的用户帐户和所属的组织中创建仓库，将 `ENABLE_PUSH_CREATE_ORG` 设置为 `true`。重新启动 Gitea 以使更改生效。您可以在 [配置速查表]({{< relref "doc/administration/config-cheat-sheet.zh-cn.md#repository-repository" >}}) 中了解有关这两个选项的更多信息。 - -## 使用推送创建 - -假设您在当前目录中有一个 git 仓库，您可以通过运行以下命令将提交推送到在 Gitea 中尚不存在的仓库： - -```shell -# 添加要推送到的远程仓库 -git remote add origin git@{domain}:{username}/{尚不存在的仓库名称}.git - -# 推送到远程仓库 -git push -u origin main -``` - -这假设您使用的是 SSH 远程，但您也可以使用 HTTPS 远程。 - -推送创建将默认使用 `app.ini` 中定义的可见性 `DEFAULT_PUSH_CREATE_PRIVATE`。 diff --git a/docs/content/doc/usage/push.zh-tw.md b/docs/content/doc/usage/push.zh-tw.md deleted file mode 100644 index 5fe5052c11..0000000000 --- a/docs/content/doc/usage/push.zh-tw.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -date: "2020-07-06T16:00:00+02:00" -title: "使用: Push" -slug: "push" -weight: 15 -toc: false -draft: false -aliases: - - /zh-tw/push-options -menu: - sidebar: - parent: "usage" - name: "Push" - weight: 15 - identifier: "push" ---- - -**Table of Contents** - -{{< toc >}} - -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]({{< relref "doc/administration/config-cheat-sheet.zh-tw.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. diff --git a/docs/content/doc/usage/repo-mirror.en-us.md b/docs/content/doc/usage/repo-mirror.en-us.md deleted file mode 100644 index 157b6c124e..0000000000 --- a/docs/content/doc/usage/repo-mirror.en-us.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -date: "2021-05-13T00:00:00-00:00" -title: "Repository Mirror" -slug: "repo-mirror" -weight: 45 -toc: false -draft: false -aliases: - - /en-us/repo-mirror -menu: - sidebar: - parent: "usage" - name: "Repository Mirror" - weight: 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. - -**Table of Contents** - -{{< toc >}} - -## 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. - -### Mirror an existing ssh repository - -Currently gitea supports no ssh push mirrors. You can work around this by adding a `post-receive` hook to your gitea repository that pushes manually. - -1. Make sure the user running gitea has access to the git repo you are trying to mirror to from shell. -2. On the Webinterface at the repository settings > git hooks add a post-receive hook for the mirror. I.e. - -``` -#!/usr/bin/env bash -git push --mirror --quiet git@github.com:username/repository.git &>/dev/null & -echo "GitHub mirror initiated .." -``` diff --git a/docs/content/doc/usage/repo-mirror.zh-cn.md b/docs/content/doc/usage/repo-mirror.zh-cn.md deleted file mode 100644 index d327338bad..0000000000 --- a/docs/content/doc/usage/repo-mirror.zh-cn.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "仓库镜像" -slug: "repo-mirror" -weight: 45 -toc: false -draft: false -aliases: - - /zh-cn/repo-mirror -menu: - sidebar: - parent: "usage" - name: "仓库镜像" - weight: 45 - identifier: "repo-mirror" ---- - -# 仓库镜像 - -仓库镜像允许将仓库与外部源之间进行镜像。您可以使用它在仓库之间镜像分支、标签和提交。 - -**目录** - -{{< toc >}} - -## 使用场景 - -以下是一些仓库镜像的可能使用场景： - -- 您迁移到了 Gitea，但仍需要在其他源中保留您的项目。在这种情况下，您可以简单地设置它以进行镜像到 Gitea（拉取），这样您的 Gitea 实例中就可以获取到所有必要的提交历史、标签和分支。 -- 您在其他源中有一些旧项目，您不再主动使用，但出于归档目的不想删除。在这种情况下，您可以创建一个推送镜像，以便您的活跃的 Gitea 仓库可以将其更改推送到旧位置。 - -## 从远程仓库拉取 - -对于现有的远程仓库，您可以按照以下步骤设置拉取镜像： - -1. 在右上角的“创建...”菜单中选择“迁移外部仓库”。 -2. 选择远程仓库服务。 -3. 输入仓库的 URL。 -4. 如果仓库需要身份验证，请填写您的身份验证信息。 -5. 选中“该仓库将是一个镜像”复选框。 -6. 选择“迁移仓库”以保存配置。 - -现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。 - -:exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation: - -## 推送到远程仓库 - -对于现有的仓库，您可以按照以下步骤设置推送镜像： - -1. 在仓库中，转到**设置** > **仓库**，然后进入**镜像设置**部分。 -2. 输入一个仓库的 URL。 -3. 如果仓库需要身份验证，请展开**授权**部分并填写您的身份验证信息。请注意，所请求的**密码**也可以是您的访问令牌。 -4. 选择**添加推送镜像**以保存配置。 - -该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。 - -:exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation: - -### 从 Gitea 向 GitHub 设置推送镜像 - -要从 Gitea 设置镜像到 GitHub，您需要按照以下步骤进行操作： - -1. 创建一个具有选中 *public_repo* 选项的 [GitHub 个人访问令牌](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)。 -2. 在 GitHub 上创建一个同名的仓库。与 Gitea 不同，GitHub 不支持通过推送到远程来创建仓库。如果您的现有远程仓库与您的 Gitea 仓库具有相同的提交历史，您也可以使用现有的远程仓库。 -3. 在您的 Gitea 仓库设置中，填写**Git 远程仓库 URL**：`https://github.com/<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. 选择**添加推送镜像**以保存配置。 - -仓库会很快进行推送。要强制推送，请选择**立即同步**按钮。 diff --git a/docs/content/doc/usage/secrets.en-us.md b/docs/content/doc/usage/secrets.en-us.md deleted file mode 100644 index c82628f50c..0000000000 --- a/docs/content/doc/usage/secrets.en-us.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -date: "2022-12-19T21:26:00+08:00" -title: "Secrets" -slug: "secrets" -weight: 50 -draft: false -toc: false -aliases: - - /en-us/secrets -menu: - sidebar: - parent: "usage" - name: "Secrets" - weight: 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+ and are only visible in 1.20+ when ACTIONS are enabled. - -# 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. diff --git a/docs/content/doc/usage/secrets.zh-cn.md b/docs/content/doc/usage/secrets.zh-cn.md deleted file mode 100644 index 534fc52eeb..0000000000 --- a/docs/content/doc/usage/secrets.zh-cn.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "密钥管理" -slug: "secrets" -weight: 50 -draft: false -toc: false -aliases: - - /zh-cn/secrets -menu: - sidebar: - parent: "usage" - name: "密钥管理" - weight: 50 - identifier: "usage-secrets" ---- - -# 密钥管理 - -密钥管理允许您在用户、组织或仓库中存储敏感信息。 -密钥管理在 Gitea 1.19+ 版本中可用。 - -# 设置密钥名称 - -以下规则适用于密钥名称： - -- 密钥名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。 - -- 密钥名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。 - -- 密钥名称不能以数字开头。 - -- 密钥名称不区分大小写。 - -- 密钥名称在创建它们的级别上必须是唯一的。 - -例如，对于在仓库级别创建的密钥，它在该仓库中必须具有唯一的名称；对于在组织级别创建的密钥，它在该级别上必须具有唯一的名称。 - -如果在多个级别上存在具有相同名称的密钥，则最低级别的密钥优先生效。例如，如果组织级别的密钥与仓库级别的密钥具有相同的名称，则仓库级别的密钥将优先生效。 diff --git a/docs/content/doc/usage/template-repositories.en-us.md b/docs/content/doc/usage/template-repositories.en-us.md deleted file mode 100644 index 5687861b8c..0000000000 --- a/docs/content/doc/usage/template-repositories.en-us.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -date: "2019-11-28:00:00+02:00" -title: "Template Repositories" -slug: "template-repositories" -weight: 14 -toc: false -draft: false -aliases: - - /en-us/template-repositories -menu: - sidebar: - parent: "usage" - name: "Template Repositories" - weight: 14 - identifier: "template-repositories" ---- - -# Template Repositories - -**Table of Contents** - -{{< toc >}} - -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. - -Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems. - -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 | diff --git a/docs/content/doc/usage/template-repositories.zh-cn.md b/docs/content/doc/usage/template-repositories.zh-cn.md deleted file mode 100644 index f8dfe1064d..0000000000 --- a/docs/content/doc/usage/template-repositories.zh-cn.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -date: "2023-05-23T09:00:00+08:00" -title: "模板仓库" -slug: "template-repositories" -weight: 14 -toc: false -draft: false -aliases: - - /zh-cn/template-repositories -menu: - sidebar: - parent: "usage" - name: "模板仓库" - weight: 14 - identifier: "template-repositories" ---- - -# 模板仓库 - -**目录** - -{{< toc >}} - -Gitea `1.11.0` 及以上版本引入了模板仓库，并且其中一个实现的功能是自动展开模板文件中的特定变量。 - -要告诉 Gitea 哪些文件需要展开，您必须在模板仓库的 `.gitea` 目录中包含一个 `template` 文件。 - -Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。它与传统的 `.gitignore` 语法非常相似，但可能存在细微的差异。 - -## `.gitea/template` 文件示例 - -所有路径都是相对于仓库的根目录 - -```gitignore -# 仓库中的所有 .go 文件 -**.go - -# text 目录中的所有文本文件 -text/*.txt - -# 特定文件 -a/b/c/d.json - -# 匹配批处理文件的大小写变体 -**.[bB][aA][tT] -``` - -**注意：** 当从模板生成仓库时，`.gitea` 目录中的 `template` 文件将被删除。 - -## 参数展开 - -在与上述通配符匹配的任何文件中，将会扩展某些变量。 - -所有变量都必须采用`$VAR`或`${VAR}`的形式。要转义扩展，使用双重`$$`，例如`$$VAR`或`$${VAR}`。 - -| 变量 | 扩展为 | 可转换 | -| -------------------- | --------------------------------------------------- | ------------- | -| REPO_NAME | 生成的仓库名称 | ✓ | -| TEMPLATE_NAME | 模板仓库名称 | ✓ | -| REPO_DESCRIPTION | 生成的仓库描述 | ✘ | -| TEMPLATE_DESCRIPTION | 模板仓库描述 | ✘ | -| REPO_OWNER | 生成的仓库所有者 | ✓ | -| TEMPLATE_OWNER | 模板仓库所有者 | ✓ | -| REPO_LINK | 生成的仓库链接 | ✘ | -| TEMPLATE_LINK | 模板仓库链接 | ✘ | -| REPO_HTTPS_URL | 生成的仓库的 HTTP(S) 克隆链接 | ✘ | -| TEMPLATE_HTTPS_URL | 模板仓库的 HTTP(S) 克隆链接 | ✘ | -| REPO_SSH_URL | 生成的仓库的 SSH 克隆链接 | ✘ | -| TEMPLATE_SSH_URL | 模板仓库的 SSH 克隆链接 | ✘ | - -## 转换器 :robot: - -Gitea `1.12.0` 添加了一些转换器以应用于上述适用的变量。 - -例如，要以 `PASCAL`-case 获取 `REPO_NAME`，你的模板应使用 `${REPO_NAME_PASCAL}` - -将 `go-sdk` 传递给可用的转换器的效果如下... - -| 转换器 | 效果 | -| ----------- | ------------ | -| SNAKE | go_sdk | -| KEBAB | go-sdk | -| CAMEL | goSdk | -| PASCAL | GoSdk | -| LOWER | go-sdk | -| UPPER | GO-SDK | -| TITLE | Go-Sdk | diff --git a/docs/content/doc/usage/webhooks.en-us.md b/docs/content/doc/usage/webhooks.en-us.md deleted file mode 100644 index 24cd48c919..0000000000 --- a/docs/content/doc/usage/webhooks.en-us.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Webhooks" -slug: "webhooks" -weight: 30 -toc: false -draft: false -aliases: - - /en-us/webhooks -menu: - sidebar: - parent: "usage" - name: "Webhooks" - weight: 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. diff --git a/docs/content/doc/usage/webhooks.zh-cn.md b/docs/content/doc/usage/webhooks.zh-cn.md deleted file mode 100644 index 412dad251b..0000000000 --- a/docs/content/doc/usage/webhooks.zh-cn.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Webhooks" -slug: "webhooks" -weight: 30 -toc: false -draft: false -aliases: - - /zh-cn/webhooks -menu: - sidebar: - parent: "usage" - name: "Webhooks" - weight: 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)。 diff --git a/docs/content/doc/usage/webhooks.zh-tw.md b/docs/content/doc/usage/webhooks.zh-tw.md deleted file mode 100644 index ca5991354a..0000000000 --- a/docs/content/doc/usage/webhooks.zh-tw.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Webhook" -slug: "webhooks" -weight: 30 -toc: false -draft: false -aliases: - - /zh-tw/webhooks -menu: - sidebar: - parent: "usage" - name: "Webhook" - weight: 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 設定中有一個傳送測試資料按鈕，它可讓你測試您的設定並將結果顯示於最近傳送記錄。 |