gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-06-24 13:15:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into lunny/update_swagger

Browse Source
This commit is contained in:
Lunny Xiao
2024-09-11 06:35:27 +00:00
parent e84a95f4da a74adaaefd
commit 6564f98656
16 changed files with 472 additions and 336 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/administration/config-cheat-sheet.md
View File

@@ -1459,7 +1459,7 @@ PROXY_HOSTS = *.github.com
- `STORAGE_TYPE`: **local**: Storage type for actions logs, `local` for local disk or `minio` for s3 compatible object storage service, default is `local` or other name defined with `[storage.xxx]`
- `MINIO_BASE_PATH`: **actions_log/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
- `LOG_RETENTION_DAYS`: **365**: Logs retention time in days. Old logs will be deleted after this period.
- `LOG_COMPRESSION`: **none**: Log compression type, `none` for no compression, `zstd` for zstd compression.
- `LOG_COMPRESSION`: **zstd**: Log compression type, `none` for no compression, `zstd` for zstd compression.
Other compression types like `gzip` are NOT supported, since seekable stream is required for log view.
It's always recommended to use compression when using local disk as log storage if CPU or memory is not a bottleneck.
And for object storage services like S3, which is billed for requests, it would cause extra 2 times of get requests for each log view.

16
docs/help/faq.md
View File

@@ -26,22 +26,6 @@ The nightly builds (1.x) downloads will change as commits are merged to their re
If a bug fix is targeted on 1.20.1 but 1.20.1 is not released yet, you can get the "1.20-nightly" build to get the bug fix.
## How to migrate from Gogs/GitHub/etc. to Gitea
To migrate from Gogs to Gitea:
- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
[Example (requires login)](https://demo.gitea.com/repo/migrate)
To migrate from GitLab to Gitea, you can use this non-affiliated tool:
https://github.com/loganinak/MigrateGitlabToGogs
## Where does Gitea store what file
- _`AppWorkPath`_

333
docs/usage/actions/act-runner.md
View File

@@ -10,24 +10,23 @@ This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in
## 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.
Currently the runner supports run in two modes. One is running in docker container, another is running in host. It is recommended to run jobs in a [docker](https://docker.com) container, if you chose this mode, you need to [install docker](https://docs.docker.com/engine/install/) 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.
## Installation with binary
### 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:
You can check it by running the following command if you are in a Unix-Style OS.
```bash
chmod +x act_runner
@@ -36,58 +35,7 @@ chmod +x act_runner
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.
### Binary configuration
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]
```
### Docker configuration
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
### Obtain a registration token
You can register a runner in different levels, it can be:
@@ -97,9 +45,8 @@ You can register a runner in different levels, it can be:
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.
Before register the runner and run it, you need 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`.
@@ -117,9 +64,26 @@ gitea --config /etc/gitea/app.ini actions generate-runner-token
Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.
### 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]
```
### Register the runner
If this has been installed using the binary package, the act runner can be registered by running the following command:
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.
If this has been installed using the binary package, the act runner can be registered by running the following command.
```bash
./act_runner register
@@ -154,10 +118,156 @@ If this file is missing or corrupted, you can simply remove it and register agai
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
### Start the runner in command line
After you have registered the runner, you can run it by running the following command:
```shell
./act_runner daemon
```
or
```bash
./act_runner daemon --config config.yaml
```
The runner will fetch jobs from the Gitea instance and run them automatically.
### Start the runner with Systemd
It is also possible to run act-runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `act_runner` user on your system, and the following file in `/etc/systemd/system/act_runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `act_runner` binary, its configuration file, and the home directory of the `act_runner` user.
```ini
[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
After=docker.service
[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/act_runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner
[Install]
WantedBy=multi-user.target
```
Then:
```bash
# load the new systemd unit file
sudo systemctl daemon-reload
# start the service and enable it at boot
sudo systemctl enable act_runner --now
```
If using Docker, the `act_runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `act_runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
### Start the runner with LaunchDaemon(macOS)
Mac uses `launchd` in place of systemd for registering daemon processes. By default daemons run as the root user, so if desired an unprivileged `_act_runner` user can be created via the `dscl` tool. The following file should then be created at the directory `/Library/LaunchDaemon/com.gitea.act_runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.gitea.act_runner</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/act_runner</string>
<string>daemon</string>
<string>--config</string>
<string>/etc/act_runner/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>WorkingDirectory</key>
<string>/var/lib/act_runner</string>
<key>StandardOutPath</key>
<string>/var/lib/act_runner/act_runner.log</string>
<key>StandardErrorPath</key>
<string>/var/lib/act_runner/act_runner.err</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME></key>
<string>/var/lib/act_runner</string>
</dict>
<key>UserName</key>
<string>_act_runner</string>
</dict>
</plist>
```
Then:
```bash
sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
```
You can also set up a Linux service or Windows service to let the runner run automatically.
## Install with the docker image
### Pull the 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
```
If you want to test newly features, you could also use nightly image
```bash
docker pull gitea/act_runner:nightly # for the latest nightly build
```
### Configuration
Configuration is optional, but 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.
### Start 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.
A quick start with docker run like below. You need to get `<registration_token>` from the above step, and give
a special unique name for `<runner_name>`
```bash
docker run \
-e GITEA_INSTANCE_URL=<instance_url> \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-e GITEA_RUNNER_NAME=<runner_name> \
--name my_runner \
-d gitea/act_runner:nightly
```
There are more parameters so that you can configure it.
```bash
docker run \
-v $PWD/config.yaml:/config.yaml \
@@ -177,7 +287,7 @@ It is because the act runner will run jobs in docker containers, so it needs to
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
### Start the runner using docker compose
You could also set up the runner using the following `docker-compose.yml`:
@@ -200,6 +310,8 @@ services:
When using docker, there is no requirement to enter the container and manually run `./act_runner daemon` command as shown below. Once the container has been started successfully, it will show up as an active runner in your Gitea instance.
## Advantage Configurations
### 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.
@@ -252,100 +364,3 @@ However, we suggest you to use a special name like `linux_amd64:host` or `window
Starting with Gitea 1.21, you can change labels by modifying `container.labels` in the runner configuration file (if you don't have a configuration file, please refer to [configuration tutorials](#configuration)).
The runner will use these new labels as soon as you restart it, i.e., by calling `./act_runner daemon --config config.yaml`.
## 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.
## Daemon Services
### Systemd
It is also possible to run act-runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `act_runner` user on your system, and the following file in `/etc/systemd/system/act_runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `act_runner` binary, its configuration file, and the home directory of the `act_runner` user.
```ini
[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
After=docker.service
[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/act_runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner
[Install]
WantedBy=multi-user.target
```
Then:
```bash
# load the new systemd unit file
sudo systemctl daemon-reload
# start the service and enable it at boot
sudo systemctl enable act_runner --now
```
If using Docker, the `act_runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `act_runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
### LaunchDaemon
Mac uses `launchd` in place of systemd for registering daemon processes. By default daemons run as the root user, so if desired an unprivileged `_act_runner` user can be created via the `dscl` tool. The following file should then be created at the directory `/Library/LaunchDaemon/com.gitea.act_runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.gitea.act_runner</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/act_runner</string>
<string>daemon</string>
<string>--config</string>
<string>/etc/act_runner/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>WorkingDirectory</key>
<string>/var/lib/act_runner</string>
<key>StandardOutPath</key>
<string>/var/lib/act_runner/act_runner.log</string>
<key>StandardErrorPath</key>
<string>/var/lib/act_runner/act_runner.err</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME></key>
<string>/var/lib/act_runner</string>
</dict>
<key>UserName</key>
<string>_act_runner</string>
</dict>
</plist>
```
Then:
```bash
sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
```

16
versioned_docs/version-1.22/usage/agit-support.md → docs/usage/agit.md
View File

@@ -1,19 +1,23 @@
---
date: " 2022-09-01T20:50:42+0000"
slug: "agit-setup"
slug: "agit"
sidebar_position: 12
aliases:
- /en-us/agit-setup
- /agit-setup
---
# Agit Setup
# AGit
In Gitea `1.13`, support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added.
**Note**: git version 2.29 or higher is required on the server side for this to work.
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
## Creating PRs with Agit
:::note
Git version 2.29 or higher is required on the server side for this to work.
:::
Agit allows to create PRs while pushing code to the remote repo.
## 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:

53
docs/usage/migration.md Normal file
View File

@@ -0,0 +1,53 @@
---
date: "2024-09-11T09:30:00+08:00"
slug: "migration"
sidebar_position: 45
---
# Migration
You can migrate repositories from other Git services to your Gitea instance.
## How to migrate from Gogs/GitHub/GitLab to Gitea
To migrate from Gogs to Gitea:
- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
[Example (requires login)](https://demo.gitea.com/repo/migrate)
To migrate from GitLab to Gitea, you can use this non-affiliated tool:
https://github.com/loganinak/MigrateGitlabToGogs
## How to migrate from AWS CodeCommit to Gitea
- To use the AWS CodeCommit API, Gitea requires an access key ID and a secret access key. For security reasons, we recommend creating a new user with the minimum necessary permissions and generating an access key ID and secret access key for the migration. The minimum permissions required for this user are as follows:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"codecommit:GetRepository",
"codecommit:GitPull",
"codecommit:ListPullRequests",
"codecommit:GetPullRequest",
"codecommit:GetCommentsForPullRequest"
],
"Resource": [
"arn:aws:codecommit:<region>:<account>:<Repo-to-Migrate>
}
]
}
```
- If you do not need to migrate pull requests, you can remove the `ListPullRequests`, `GetPullRequest`, and `GetCommentsForPullRequest` actions.
- For instructions on how to create an IAM user and assign permissions, you can refer to this [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
- To clone this repository, Gitea requires HTTPS Git credentials. You can create HTTPS Git credentials according to this [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html).

2
i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md
View File

@@ -1333,7 +1333,7 @@ PROXY_HOSTS = *.github.com
- `STORAGE_TYPE`: **local**：用于操作日志的存储类型，`local`表示本地磁盘，`minio`表示与S3兼容的对象存储服务，默认为`local`，或者使用定义为`[storage.xxx]`的其他名称。
- `MINIO_BASE_PATH`: **actions_log/**：Minio存储桶上的基本路径，仅在`STORAGE_TYPE`为`minio`时可用。
- `LOG_RETENTION_DAYS`: **365**：日志保留时间（天）。此期限后将删除旧日志。
- `LOG_COMPRESSION`: **none**：日志压缩方式，`none`表示不压缩，`zstd`表示 zstd 压缩。
- `LOG_COMPRESSION`: **zstd**：日志压缩方式，`none`表示不压缩，`zstd`表示 zstd 压缩。
其它的压缩方式如`gzip`是不支持的，因为查看日志需要可寻址流。
如果 CPU 或内存不是瓶颈，建议在使用本地磁盘作为日志存储时总是使用压缩。
对于像 S3 这样的会对请求次数计费的对象存储服务，每次查看日志会导致额外的 2 次获取请求。

14
i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/agit-support.md
View File

@@ -1,18 +1,22 @@
---
date: "2023-05-23T09:00:00+08:00"
slug: "agit-setup"
slug: "agit"
sidebar_position: 12
aliases:
- /zh-cn/agit-setup
---
# Agit 设置
# AGit
在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。
在 Gitea `1.13` 版本中，添加了对 [AGit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。AGit 允许用户在没有仓库写入权限的情况下直接创建拉取请求，也不需要分叉仓库。这有助于减少重复仓库的数量，降低不必要的磁盘使用量。
## 使用 Agit 创建 PR
:::note
服务器端需要 Git 版本 2.29 或更高版本才能正常运行。
:::
Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。
## 使用 AGit 创建 PR
AGit 允许在推送代码到远程仓库时创建 PR（合并请求）。
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
下面的示例说明了这一点：

6
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/agit-support.md
View File

@@ -6,13 +6,13 @@ aliases:
- /zh-cn/agit-setup
---
# Agit 设置
# AGit 设置
在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。
## 使用 Agit 创建 PR
## 使用 AGit 创建 PR
Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。
AGit 允许在推送代码到远程仓库时创建 PR（合并请求）。
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
下面的示例说明了这一点：

6
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/agit-support.md
View File

@@ -9,13 +9,13 @@ aliases:
---
# Agit 设置
# AGit 设置
在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。
## 使用 Agit 创建 PR
## 使用 AGit 创建 PR
Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。
AGit 允许在推送代码到远程仓库时创建 PR（合并请求）。
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
下面的示例说明了这一点：

6
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/agit-support.md
View File

@@ -9,13 +9,13 @@ aliases:
---
# Agit 设置
# AGit 设置
在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。
## 使用 Agit 创建 PR
## 使用 AGit 创建 PR
Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。
AGit 允许在推送代码到远程仓库时创建 PR（合并请求）。
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
下面的示例说明了这一点：

6
i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/agit-support.md
View File

@@ -9,13 +9,13 @@ aliases:
---
# Agit 设置
# AGit 设置
在 Gitea `1.13` 版本中，添加了对 [agit](https://git-repo.info/zh/2020/03/agit-flow-and-git-repo/) 的支持。
## 使用 Agit 创建 PR
## 使用 AGit 创建 PR
Agit 允许在推送代码到远程仓库时创建 PR（合并请求）。
AGit 允许在推送代码到远程仓库时创建 PR（合并请求）。
通过在推送时使用特定的 refspec（git 中已知的位置标识符），可以实现这一功能。
下面的示例说明了这一点：

17
versioned_docs/version-1.19/usage/agit-support.md → versioned_docs/version-1.19/usage/agit.md
View File

@@ -1,19 +1,20 @@
---
date: " 2022-09-01T20:50:42+0000"
slug: "agit-setup"
slug: "agit"
sidebar_position: 12
---
# Agit Setup
# AGit
In Gitea `1.13`, support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added.
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
## Creating PRs with Agit
:::note
Git version 2.29 or higher is required on the server side for this to work.
:::
Agit allows to create PRs while pushing code to the remote repo. \
## 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:

17
versioned_docs/version-1.20/usage/agit-support.md → versioned_docs/version-1.20/usage/agit.md
View File

@@ -1,21 +1,22 @@
---
date: " 2022-09-01T20:50:42+0000"
slug: "agit-setup"
slug: "agit"
sidebar_position: 12
aliases:
- /en-us/agit-setup
---
# 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.
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
## Creating PRs with Agit
:::note
Git version 2.29 or higher is required on the server side for this to work.
:::
Agit allows to create PRs while pushing code to the remote repo.
## 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:

17
versioned_docs/version-1.21/usage/agit-support.md → versioned_docs/version-1.21/usage/agit.md
View File

@@ -1,21 +1,22 @@
---
date: " 2022-09-01T20:50:42+0000"
slug: "agit-setup"
slug: "agit"
sidebar_position: 12
aliases:
- /en-us/agit-setup
---
# 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.
In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
## Creating PRs with Agit
:::note
Git version 2.29 or higher is required on the server side for this to work.
:::
Agit allows to create PRs while pushing code to the remote repo.
## 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:

282
versioned_docs/version-1.22/usage/actions/act-runner.md
View File

@@ -10,24 +10,23 @@ This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in
## 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.
Currently the runner supports run in two modes. One is running in docker container, another is running in host. It is recommended to run jobs in a [docker](https://docker.com) container, if you chose this mode, you need to [install docker](https://docs.docker.com/engine/install/) 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.
## Installation with binary
### 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:
You can check it by running the following command if you are in a Unix-Style OS.
```bash
chmod +x act_runner
@@ -36,54 +35,7 @@ chmod +x act_runner
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
### Obtain a registration token
You can register a runner in different levels, it can be:
@@ -93,9 +45,8 @@ You can register a runner in different levels, it can be:
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.
Before register the runner and run it, you need 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`.
@@ -113,9 +64,26 @@ gitea --config /etc/gitea/app.ini actions generate-runner-token
Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.
### 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]
```
### Register the runner
The act runner can be registered by running the following command:
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.
If this has been installed using the binary package, the act runner can be registered by running the following command.
```bash
./act_runner register
@@ -150,10 +118,156 @@ If this file is missing or corrupted, you can simply remove it and register agai
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
### Start the runner in command line
After you have registered the runner, you can run it by running the following command:
```shell
./act_runner daemon
```
or
```bash
./act_runner daemon --config config.yaml
```
The runner will fetch jobs from the Gitea instance and run them automatically.
### Start the runner with Systemd
It is also possible to run act-runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `act_runner` user on your system, and the following file in `/etc/systemd/system/act_runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `act_runner` binary, its configuration file, and the home directory of the `act_runner` user.
```ini
[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
After=docker.service
[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/act_runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner
[Install]
WantedBy=multi-user.target
```
Then:
```bash
# load the new systemd unit file
sudo systemctl daemon-reload
# start the service and enable it at boot
sudo systemctl enable act_runner --now
```
If using Docker, the `act_runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `act_runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
### Start the runner with LaunchDaemon(macOS)
Mac uses `launchd` in place of systemd for registering daemon processes. By default daemons run as the root user, so if desired an unprivileged `_act_runner` user can be created via the `dscl` tool. The following file should then be created at the directory `/Library/LaunchDaemon/com.gitea.act_runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.gitea.act_runner</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/act_runner</string>
<string>daemon</string>
<string>--config</string>
<string>/etc/act_runner/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>WorkingDirectory</key>
<string>/var/lib/act_runner</string>
<key>StandardOutPath</key>
<string>/var/lib/act_runner/act_runner.log</string>
<key>StandardErrorPath</key>
<string>/var/lib/act_runner/act_runner.err</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
<key>HOME></key>
<string>/var/lib/act_runner</string>
</dict>
<key>UserName</key>
<string>_act_runner</string>
</dict>
</plist>
```
Then:
```bash
sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
```
You can also set up a Linux service or Windows service to let the runner run automatically.
## Install with the docker image
### Pull the 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
```
If you want to test newly features, you could also use nightly image
```bash
docker pull gitea/act_runner:nightly # for the latest nightly build
```
### Configuration
Configuration is optional, but 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.
### Start 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.
A quick start with docker run like below. You need to get `<registration_token>` from the above step, and give
a special unique name for `<runner_name>`
```bash
docker run \
-e GITEA_INSTANCE_URL=<instance_url> \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
-e GITEA_RUNNER_NAME=<runner_name> \
--name my_runner \
-d gitea/act_runner:nightly
```
There are more parameters so that you can configure it.
```bash
docker run \
-v $PWD/config.yaml:/config.yaml \
@@ -173,7 +287,7 @@ It is because the act runner will run jobs in docker containers, so it needs to
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
### Start the runner using docker compose
You could also set up the runner using the following `docker-compose.yml`:
@@ -194,6 +308,10 @@ services:
- /var/run/docker.sock:/var/run/docker.sock
```
When using docker, there is no requirement to enter the container and manually run `./act_runner daemon` command as shown below. Once the container has been started successfully, it will show up as an active runner in your Gitea instance.
## Advantage Configurations
### 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.
@@ -246,51 +364,3 @@ However, we suggest you to use a special name like `linux_amd64:host` or `window
Starting with Gitea 1.21, you can change labels by modifying `container.labels` in the runner configuration file (if you don't have a configuration file, please refer to [configuration tutorials](#configuration)).
The runner will use these new labels as soon as you restart it, i.e., by calling `./act_runner daemon --config config.yaml`.
## 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.
## Systemd service
It is also possible to run act-runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `act_runner` user on your system, and the following file in `/etc/systemd/system/act_runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `act_runner` binary, its configuration file, and the home directory of the `act_runner` user.
```ini
[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
After=docker.service
[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/act_runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner
[Install]
WantedBy=multi-user.target
```
Then:
```bash
# load the new systemd unit file
sudo systemctl daemon-reload
# start the service and enable it at boot
sudo systemctl enable act_runner --now
```
If using Docker, the `act_runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `act_runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).

15
docs/usage/agit-support.md → versioned_docs/version-1.22/usage/agit.md
View File

@@ -1,19 +1,22 @@
---
date: " 2022-09-01T20:50:42+0000"
slug: "agit-setup"
slug: "agit"
sidebar_position: 12
aliases:
- /en-us/agit-setup
---
# Agit Setup
# AGit
In Gitea `1.13`, support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added.
**Note**: git version 2.29 or higher is required on the server side for this to work.
In Gitea `1.13`, support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
## Creating PRs with Agit
:::note
Git version 2.29 or higher is required on the server side for this to work.
:::
Agit allows to create PRs while pushing code to the remote repo.
## 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: