rename act runner to runner (#390)

Depends on gitea/runner#850

---------

Co-authored-by: Nicolas <bircni@icloud.com>
Co-authored-by: silverwind <me@silverwind.io>
Reviewed-on: https://gitea.com/gitea/docs/pulls/390
Reviewed-by: techknowlogick <9+techknowlogick@noreply.gitea.com>
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
Reviewed-by: Nicolas <bircni@icloud.com>
This commit is contained in:
Lunny Xiao
2026-05-07 17:18:58 +00:00
parent b6b8dbcc64
commit 54af905d63
25 changed files with 226 additions and 294 deletions

View File

@@ -9,7 +9,7 @@ Thank you for your interest in contributing to Gitea! This guide will help you u
## Getting Started
Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea.md) guide to set up your development environment.
Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea) guide to set up your development environment.
## Contribution Guidelines
@@ -17,7 +17,7 @@ We have specific guidelines for different types of contributions:
### Backend Development
If you're working on backend code (Go), please follow our [Guidelines for Backend Development](guidelines-backend.md). This includes:
If you're working on backend code (Go), please follow our [Guidelines for Backend Development](./guidelines-backend). This includes:
- Package design and dependencies
- Database operations and migrations
@@ -26,7 +26,7 @@ If you're working on backend code (Go), please follow our [Guidelines for Backen
### Frontend Development
For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](guidelines-frontend.md). This covers:
For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](./guidelines-frontend). This covers:
- Framework usage (Vue3, Fomantic-UI)
- Code style and best practices
@@ -35,7 +35,7 @@ For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for
### Refactoring
When refactoring existing code, follow our [Guidelines for Refactoring](guidelines-refactoring.md) to ensure:
When refactoring existing code, follow our [Guidelines for Refactoring](./guidelines-refactoring) to ensure:
- Clear refactoring objectives
- Proper review process
@@ -44,7 +44,7 @@ When refactoring existing code, follow our [Guidelines for Refactoring](guidelin
### Localization
To contribute translations or localization improvements, see our [Localization Guide](localization.md) which explains:
To contribute translations or localization improvements, see our [Localization Guide](./localization) which explains:
- How to contribute translations via Crowdin
- Supported languages

View File

@@ -8,33 +8,9 @@ sidebar_position: 140
Gitea Actions has multiple components. This document describes them individually.
## Act
## Gitea Runner
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.
Gitea Runner is based on a hard fork of [nektos/act](https://github.com/nektos/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.
@@ -47,7 +23,7 @@ That's why when you add custom labels during registration, you will need to inpu
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.
The runner 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.
@@ -62,7 +38,7 @@ So,
## Communication protocol
As act runner is an independent part of Gitea, we needed a protocol for runners to communicate with the Gitea instance.
As the 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.
@@ -79,9 +55,9 @@ This will help you troubleshoot some problems and explain why it's a bad idea to
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
### Connection 1, runner to Gitea instance
The act runner must be able to connect to Gitea to receive tasks and send back the execution results.
The runner must be able to connect to Gitea to receive tasks and send back the execution results.
### Connection 2, job containers to Gitea instance
@@ -92,9 +68,9 @@ Fetching code is not always necessary to run some jobs, but it is required in mo
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
### Connection 3, runner to internet
When you use some actions like `actions/checkout@v4`, the act runner downloads the scripts, not the job containers.
When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
By default, it downloads from [github.com](http://github.com/), so it requires access to the internet. If you configure the `DEFAULT_ACTIONS_URL` to `self`, then it will download from your Gitea instance by default. Then it will not connect to internet when downloading the action itself.
It also downloads some docker images from Docker Hub by default, which also requires internet access.

View File

@@ -55,7 +55,7 @@ If you want to give more permissions to the runner, allowing it to access more p
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.
## Which operating systems are supported by act runner?
## Which operating systems are supported by Gitea Runner?
We released official binaries for Linux, macOS, and Windows.
While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
@@ -101,7 +101,7 @@ It is exciting to be able to reuse them.
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 until v0.2.11.
Unfortunately, the runner does not work this way until v0.2.11.
As mentioned, we map labels to environments:
- `ubuntu``ubuntu:22.04`
@@ -117,9 +117,9 @@ 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).
See [runtime.go#L65](https://gitea.com/gitea/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.
Currently, the 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?
@@ -132,17 +132,17 @@ 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).
See [runtime.go#L71](https://gitea.com/gitea/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 at the moment.
Although we would like to provide more options, our limited manpower means that Gitea Runner will be the only officially supported runner at the moment.
However, both Gitea and act runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
However, both Gitea and Gitea Runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
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.
In case you fork Gitea 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?

View File

@@ -21,8 +21,8 @@ To avoid confusion, we have clarified the spelling here:
## 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.
An important part of the application comes from a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act).
The runner of Gitea Actions is called [Gitea Runner](https://gitea.com/gitea/runner), it is a standalone program and also written in Go.
An important part of the application comes from a hard fork 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:

View File

@@ -25,10 +25,10 @@ If you want to learn more or encounter any problems while configuring it, please
### Set up runner
Gitea Actions requires [act runner](https://gitea.com/gitea/act_runner) to run the jobs.
Gitea Actions requires [Gitea Runner](https://gitea.com/gitea/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.
You can use the [pre-built binaries](http://dl.gitea.com/gitea-runner) or the [docker images](https://hub.docker.com/r/gitea/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 localhost.
And it could be easier to debug if something goes wrong.
@@ -40,7 +40,7 @@ However, it is recommended to use Docker to run the jobs, because it is more sec
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>
./runner register --no-interactive --instance <instance> --token <token>
```
There are two arguments required, `instance` and `token`.
@@ -69,14 +69,14 @@ If this file is missing or corrupted, you can simply remove it and register agai
Finally, it's time to start the runner:
```bash
./act_runner daemon
./runner daemon
```
And you can see the new runner in the management page:
![view runner](/images/usage/actions/view-runner.png)
You can find more information by visiting [Act runner](act-runner.mdxc).
You can find more information by visiting [Gitea Runner](runner.mdx).
### Use Actions

View File

@@ -1,17 +1,19 @@
---
date: "2023-04-27T15:00:00+08:00"
slug: "act-runner"
slug: "runner"
sidebar_position: 20
aliases:
- /act-runner
---
# Act Runner
# Gitea Runner
This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner for Gitea Actions.
This page will introduce the [Gitea Runner](https://gitea.com/gitea/runner) in detail, which is the runner for Gitea Actions.
## Requirements
Currently the runner supports three modes in which it can be run.
1. Host: act_runner will run as an application on the host. This provides no encapsulation.
1. Host: runner will run as an application on the host. This provides no encapsulation.
2. Docker (recommended): Runs jobs in a [Docker](https://docker.com) container. If you choose this mode, you need to [install Docker](https://docs.docker.com/engine/install/) first and make sure that the Docker daemon is running.
3. Docker-in-Docker (DinD): Puts the runner into rootless mode. It then runs in a Docker container with its own Docker daemon that has fewer privileges. It will spawn job containers from there. Best security but more complex setup.
@@ -19,21 +21,21 @@ Other OCI container engines which are compatible with Docker's API should also w
However, if you are sure that you want to run jobs directly on the host only, then Docker is not required.
There are multiple ways to install the act runner.
There are multiple ways to install the 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/).
You can download the binary from the [release page](https://gitea.com/gitea/runner/releases).
However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/gitea-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 if you are in a Unix-style OS.
```bash
chmod +x act_runner
./act_runner --version
chmod +x runner
./runner --version
```
If you see the version information, it means that you have downloaded the correct binary.
@@ -82,30 +84,30 @@ Tokens are valid for registering multiple runners, until they are revoked and re
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
./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]
./runner generate-config > config.yaml
./runner --config config.yaml [command]
```
### Register the runner
Registration is required before running the act runner, because the runner needs to know where to get jobs from. It is also important for the Gitea instance to identify the runner.
Registration is required before running Gitea Runner, because the runner needs to know where to get jobs from. It is also important for the 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.
If this has been installed using the binary package, the runner can be registered by running the following command.
```bash
./act_runner register
./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
./runner --config config.yaml register
```
You will be asked to input the registration information step by step. This includes:
@@ -120,7 +122,7 @@ 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>
./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.
@@ -135,20 +137,20 @@ and don't forget to specify the `--config` option.
Ephemeral runners provide a security hardening mechanism for enabling organization- or instance-wide runners without requiring full user trust. Once a job is assigned within a spot VM or container, the runner's exposed credentials are automatically revoked—blocking it from polling further jobs before any untrusted code runs, while still allowing it to report progress until completion by either Gitea or the runner.
act_runner **0.2.12+** is required.
Gitea Runner **0.2.12+** is required.
The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the act_runner.
The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the runner.
```bash
./act_runner register --ephemeral
./runner register --ephemeral
```
```bash
./act_runner --config config.yaml register --ephemeral
./runner --config config.yaml register --ephemeral
```
```bash
./act_runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
./runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
```
The runner must be registered each time it is intended to receive a job. After completing the single job it is designed to execute, the runner terminates.
@@ -160,35 +162,35 @@ To automate the registration and startup of new runners when a job is queued, us
After you have registered the runner, you can run it with the following command:
```shell
./act_runner daemon
./runner daemon
```
or
```bash
./act_runner daemon --config config.yaml
./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 create 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.
It is also possible to run Gitea Runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `runner` user on your system, and create the following file in `/etc/systemd/system/runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `runner` binary, its configuration file, and the home directory of the `runner` user.
```ini
[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
Documentation=https://gitea.com/gitea/runner
After=docker.service
[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecStart=/usr/local/bin/runner daemon --config /etc/runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/act_runner
WorkingDirectory=/var/lib/runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner
User=runner
[Install]
WantedBy=multi-user.target
@@ -200,14 +202,14 @@ Then:
# load the new systemd unit file
sudo systemctl daemon-reload
# start the service and enable it at boot
sudo systemctl enable act_runner --now
sudo systemctl enable 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).
If using Docker, the `runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `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 in 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.
Mac uses `launchd` in place of systemd for registering daemon processes. By default, daemons run as the root user, so if desired an unprivileged `_runner` user can be created via the `dscl` tool. The following file should then be created in the directory `/Library/LaunchDaemon/com.gitea.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"?>
@@ -215,33 +217,33 @@ Mac uses `launchd` in place of systemd for registering daemon processes. By defa
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.gitea.act_runner</string>
<string>com.gitea.runner</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/act_runner</string>
<string>/usr/local/bin/runner</string>
<string>daemon</string>
<string>--config</string>
<string>/etc/act_runner/config.yaml</string>
<string>/etc/runner/config.yaml</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>WorkingDirectory</key>
<string>/var/lib/act_runner</string>
<string>/var/lib/runner</string>
<key>StandardOutPath</key>
<string>/var/lib/act_runner/act_runner.log</string>
<string>/var/lib/runner/runner.log</string>
<key>StandardErrorPath</key>
<string>/var/lib/act_runner/act_runner.err</string>
<string>/var/lib/runner/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>
<string>/var/lib/runner</string>
</dict>
<key>UserName</key>
<string>_act_runner</string>
<string>_runner</string>
</dict>
</plist>
```
@@ -249,7 +251,7 @@ Mac uses `launchd` in place of systemd for registering daemon processes. By defa
Then:
```bash
sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
sudo launchctl load /Library/LaunchDaemon/com.gitea.runner.plist
```
You can also set up a Linux or Windows service to let the runner run automatically.
@@ -258,16 +260,16 @@ You can also set up a Linux or Windows service to let the runner run automatical
### Pull the image
You can use the docker image from [Docker Hub](https://hub.docker.com/r/gitea/act_runner/tags).
You can use the docker image from [Docker Hub](https://hub.docker.com/r/gitea/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 docker.io/gitea/act_runner:latest # for the latest stable release
docker pull docker.io/gitea/runner:latest # for the latest stable release
```
If you want to use the newest or experimental features, you can also use the nightly image.
```bash
docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
docker pull docker.io/gitea/runner:nightly # for the latest nightly build
```
### Configuration
@@ -275,7 +277,7 @@ docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
Configuration is optional, but you can also generate a config file with docker:
```bash
docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
docker run --entrypoint="" --rm -it docker.io/gitea/runner:latest 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:
@@ -284,12 +286,12 @@ When you are using the docker image, you can specify the configuration file by u
docker run -v $PWD/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
```
You may notice the commands above are incomplete because it is not time to run the act runner yet.
Before running the act runner, we need to register it to your Gitea instance first.
You may notice the commands above are incomplete because it is not time to run the runner yet.
Before running the runner, we need to register it to your Gitea instance first.
### Start the runner with docker
If you are using the docker image, behavior 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.
If you are using the docker image, behavior 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 runner.
A quick start with docker run along with a minimal parameter set is shown below. You need to get the `<registration_token>` from the above step, and set a unique name for `<gitea_runner_name>` and for `<container_name>`.
@@ -300,7 +302,7 @@ docker run \
-e GITEA_RUNNER_NAME=<gitea_runner_name> \
--name <container_name> \
-v /var/run/docker.sock:/var/run/docker.sock \
-d docker.io/gitea/act_runner:latest
-d docker.io/gitea/runner:latest
```
You can add more parameters to use a custom config, add a `data` directory for non-volatile file storage, etc.
@@ -316,13 +318,13 @@ docker run \
-e GITEA_RUNNER_NAME=<gitea_runner_name> \
-e GITEA_RUNNER_LABELS=<runner_labels> \
--name <container_name> \
-d docker.io/gitea/act_runner:latest
-d docker.io/gitea/runner:latest
```
You may notice that we have mounted `/var/run/docker.sock` into the container.
This is because with this setup, act runner will execute jobs in temporary Docker containers, so it needs to communicate with the Docker daemon.
This is because with this setup, the runner will execute jobs in temporary Docker containers, so it needs to communicate with the Docker daemon.
As mentioned, you can remove it if you want to run jobs on the host directly.
To be clear, the "host" actually means the container that is running the act runner now, instead of the host machine.
To be clear, the "host" actually means the container that is running the runner now, instead of the host machine.
---
@@ -335,7 +337,7 @@ docker run \
-e GITEA_RUNNER_EPHEMERAL=1 \
-e GITEA_RUNNER_NAME=<runner_name> \
--name my_runner \
-d docker.io/gitea/act_runner:nightly
-d docker.io/gitea/runner:nightly
```
```bash
@@ -349,7 +351,7 @@ docker run \
-e GITEA_RUNNER_NAME=<runner_name> \
-e GITEA_RUNNER_LABELS=<runner_labels> \
--name my_runner \
-d docker.io/gitea/act_runner:nightly
-d docker.io/gitea/runner:nightly
```
Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
@@ -362,7 +364,7 @@ You could also set up the runner using the following `docker-compose.yml`:
version: "3.8"
services:
runner:
image: docker.io/gitea/act_runner:nightly
image: docker.io/gitea/runner:nightly
environment:
CONFIG_FILE: /config.yaml
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
@@ -375,7 +377,7 @@ 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.
When using docker, there is no requirement to enter the container and manually run `./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.
---
@@ -385,7 +387,7 @@ To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERA
version: "3.8"
services:
runner:
image: docker.io/gitea/act_runner:nightly
image: docker.io/gitea/runner:nightly
environment:
CONFIG_FILE: /config.yaml
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
@@ -401,7 +403,7 @@ services:
Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
### More start examples
A couple more usage examples can be found in the [act_runner](https://gitea.com/gitea/act_runner/src/branch/main/examples) repository.
A couple more usage examples can be found in the [runner](https://gitea.com/gitea/runner/src/branch/main/examples) repository.
## Advanced Configurations
@@ -436,7 +438,7 @@ cache:
docker run \
--name gitea-docker-runner \
-p 8088:8088 \
-d docker.io/gitea/act_runner:nightly
-d docker.io/gitea/runner:nightly
```
### Labels
@@ -456,4 +458,4 @@ If you want to run jobs on the host directly, you can change it to `ubuntu-22.04
However, we suggest you use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
Starting with Gitea 1.21, you can change labels by modifying `runners.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`.
The runner will use these new labels as soon as you restart it, i.e., by calling `./runner daemon --config config.yaml`.

View File

@@ -84,7 +84,7 @@ These environment variables are set automatically in every workflow run and can
|---|---|---|
| `CI` | Always set to `true`. | `true` |
| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the act runner executing the workflow. | `0.2.11` |
| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `0.2.11` |
| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |

View File

@@ -8,33 +8,9 @@ sidebar_position: 40
Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
## Act
## Gitea Runner
[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。
Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支
与其他CI Runner一样我们将其设计为Gitea的外部部分这意味着它应该在与Gitea不同的服务器上运行。
@@ -47,7 +23,7 @@ Gitea的Runner被称为act runner因为它基于act。
这意味着Runner可以接受需要在`my_custom_label`上运行的Job并通过使用`centos:7`镜像的Docker容器来运行它。
然而Docker不是唯一的选择。
act 也支持直接在主机上运行Job。
Runner 也支持直接在主机上运行Job。
这是通过像`linux_arm:host`这样的标签实现的。
这个标签表示Runner可以接受需要在`linux_arm`上运行的Job并直接在主机上运行它们。
@@ -63,7 +39,7 @@ act 也支持直接在主机上运行Job。
## 通信协议
由于act runnerGitea的独立部分我们需要一种协议让RunnerGitea实例进行通信。
由于 runnerGitea 的独立部分,我们需要一种协议让 RunnerGitea 实例进行通信。
然而我们不认为让Gitea监听一个新端口是个好主意。
相反我们希望重用HTTP端口这意味着我们需要一个与HTTP兼容的协议。
因此我们选择使用基于HTTP的gRPC。
@@ -80,9 +56,9 @@ act 也支持直接在主机上运行Job。
图片中标记了四个网络连接,并且箭头的方向表示建立连接的方向。
### 连接 1act runnerGitea实例
### 连接 1runnerGitea 实例
act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
### 连接 2Job 容器到 Gitea 实例
@@ -93,9 +69,9 @@ act runner 必须能够连接到Gitea以接收任务并发送执行结果回来
如果您使用回环地址注册Runner当Runner与Gitea在同一台机器上时Runner可以连接到Gitea。
然而如果Job容器尝试从本地主机获取代码它将失败因为Gitea不在同一个容器中。
### 连接 3act runner到互联网
### 连接 3runner 到互联网
当您使用诸如 `actions/checkout@v4` 的一些Actions时act runner下载的是脚本而不是Job容器。
当您使用诸如 `actions/checkout@v4` 的一些Actions时 runner下载的是脚本而不是Job容器。
默认情况下,它从[github.com](http://github.com/)下载,因此需要访问互联网。如果您设置的是 self
那么默认将从您的当前Gitea实例下载那么此步骤不需要连接到互联网。
它还默认从Docker Hub下载一些Docker镜像这也需要互联网访问。

View File

@@ -73,7 +73,7 @@ Runner仅具有连接到您的Gitea实例的权限。
- 对于 fork 的拉取请求需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
- 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner我们不会反对只是不会在我们的组织中使用它。然而他们应该注意确保该Runner不被他们不认识的其他用户使用。
## act runner支持哪些操作系统
## Runner 支持哪些操作系统?
它在Linux、macOS和Windows上运行良好。
虽然理论上支持其他操作系统,但需要进一步测试。
@@ -101,7 +101,7 @@ defaults:
这是有效的语法。
它意味着它应该在具有`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 并不支持这种方式。
不幸的是runner 并不支持这种方式。
如上所述,我们将标签映射到环境:
- `ubuntu``ubuntu:22.04`
@@ -117,9 +117,9 @@ defaults:
具有`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)。
参见[runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
目前,act runner尝试匹配标签中的每一个并使用找到的第一个匹配项。
目前runner 尝试匹配标签中的每一个,并使用找到的第一个匹配项。
## 代理标签和自定义标签对于Runner有什么区别
@@ -132,16 +132,16 @@ defaults:
您可以向已注册的Runner添加自定义标签比如 `centos`这意味着该Runner将接收具有`runs-on: centos`的Job。
然而Runner可能不知道要使用哪个环境来执行该标签导致它使用默认镜像或导致逻辑死胡同。
这个默认值可能与用户的期望不符。
参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
参见[runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
与此同时如果您想更改Runner的标签我们建议您重新注册Runner。
## Gitea Actions runner会有更多的实现吗
虽然我们希望提供更多的选择,但由于我们有限的人力资源,act runner将是唯一受支持的官方Runner。
然而无论您如何决定Gitea 和act runner都是完全开源的所以任何人都可以创建一个新的/更好的实现。
虽然我们希望提供更多的选择但由于我们有限的人力资源runner 将是唯一受支持的官方 Runner。
然而无论您如何决定Gitea 和 runner都是完全开源的所以任何人都可以创建一个新的/更好的实现。
我们支持您的选择,无论您如何决定。
如果您选择分支act runner来创建自己的版本请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
如果您选择分支 runner来创建自己的版本请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
## Gitea 支持哪些工作流触发事件?

View File

@@ -21,8 +21,8 @@ Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且
## 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)
Gitea Actions的Runner被称为[Gitea Runner](https://gitea.com/gitea/runner)它是一个独立的程序也是用Go语言编写的。
的重要部分来自[nektos/act](http://github.com/nektos/act)的一个硬分支
由于Runner是独立部署的可能存在潜在的安全问题。
为了避免这些问题,请遵循两个简单的规则:

View File

@@ -25,10 +25,10 @@ ENABLED=true
### 设置Runner
Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
为了避免消耗过多资源并影响Gitea实例建议您在与Gitea实例分开的机器上启动Runner。
您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。
在进一步操作之前建议您先使用预构建的二进制文件以命令行方式运行它以确保它与您的环境兼容尤其是如果您在本地主机上运行Runner。
如果出现问题,这样调试起来会更容易。
@@ -40,7 +40,7 @@ Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job
在运行Runner之前您需要使用以下命令将其注册到Gitea实例中
```bash
./act_runner register --no-interactive --instance <instance> --token <token>
./runner register --no-interactive --instance <instance> --token <token>
```
需要两个必需的参数:`instance``token`
@@ -68,14 +68,14 @@ Runner和Job容器由Runner启动以执行Job将连接到此地址。
最后是时候启动Runner了
```bash
./act_runner daemon
./runner daemon
```
您可以在管理页面上看到新的Runner
![view runner](/images/usage/actions/view-runner.png)
您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
您可以通过访问[Gitea Runner](runner) 获取更多信息。
### 使用Actions

View File

@@ -1,12 +1,14 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "act-runner"
slug: "runner"
sidebar_position: 20
aliases:
- /zh-cn/act-runner
---
# Act Runner
# Runner
本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)这是Gitea Actions的Runner。
本页面将详细介绍[Gitea Runner](https://gitea.com/gitea/runner)这是Gitea Actions的Runner。
## 要求
@@ -19,31 +21,31 @@ sidebar_position: 20
## 安装
有多种安装Act Runner的方法。
有多种安装 Runner 的方法。
### 下载二进制文件
您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
然而,如果您想使用最新的夜间构建版本,可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
您可以从[发布页面](https://gitea.com/gitea/runner/releases)下载二进制文件。
然而,如果您想使用最新的夜间构建版本,可以从[下载页面](https://dl.gitea.com/gitea-runner/)下载。
下载二进制文件时,请确保您已经下载了适用于您的平台的正确版本。
您可以通过运行以下命令进行检查:
```bash
chmod +x act_runner
./act_runner --version
chmod +x runner
./runner --version
```
如果看到版本信息,则表示您已经下载了正确的二进制文件。
### 使用 Docker 镜像
您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
您可以使用[docker hub](https://hub.docker.com/r/gitea/runner/tags)上的Docker镜像。
与二进制文件类似,您可以使用`nightly`标签使用最新的夜间构建版本,而`latest`标签是最新的稳定版本。
```bash
docker pull docker.io/gitea/act_runner:latest # for the latest stable release
docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
docker pull docker.io/gitea/runner:latest # for the latest stable release
docker pull docker.io/gitea/runner:nightly # for the latest nightly build
```
## 配置
@@ -53,20 +55,20 @@ docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
您可以通过运行以下命令生成配置文件:
```bash
./act_runner generate-config
./runner generate-config
```
默认配置是安全的,可以直接使用。
```bash
./act_runner generate-config > config.yaml
./act_runner --config config.yaml [command]
./runner generate-config > config.yaml
./runner --config config.yaml [command]
```
您亦可以如下使用 docker 创建配置文件:
```bash
docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
docker run --entrypoint="" --rm -it docker.io/gitea/runner:latest runner generate-config > config.yaml
```
当使用Docker镜像时可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中:
@@ -75,12 +77,12 @@ docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner
docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
```
您可能注意到上面的命令都是不完整的,因为现在还不是运行Act Runner的时候。
在运行Act Runner之前我们需要首先将其注册到您的Gitea实例中。
您可能注意到上面的命令都是不完整的,因为现在还不是运行 Runner 的时候。
在运行 Runner 之前我们需要首先将其注册到您的Gitea实例中。
## 注册
在运行Act Runner之前需要进行注册因为Runner需要知道从哪里获取Job并且对于Gitea实例来说识别Runner也很重要。
在运行 Runner 之前需要进行注册因为Runner需要知道从哪里获取Job并且对于Gitea实例来说识别Runner也很重要。
### Runner级别
@@ -124,16 +126,16 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
### 注册Runner
可以通过运行以下命令来注册Act Runner
可以通过运行以下命令来注册 Runner
```bash
./act_runner register
./runner register
```
或者,您可以使用 `--config` 选项来指定前面部分提到的配置文件。
```bash
./act_runner --config config.yaml register
./runner --config config.yaml register
```
您将逐步输入注册信息,包括:
@@ -148,7 +150,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
如果您想以非交互方式注册Runner可以使用参数执行以下操作。
```bash
./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
./runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
```
注册Runner后您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
@@ -159,7 +161,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
### 使用Docker注册Runner
如果您使用的是Docker镜像注册行为会略有不同。在这种情况下注册和运行合并为一步因此您需要在运行Act Runner时指定注册信息。
如果您使用的是Docker镜像注册行为会略有不同。在这种情况下注册和运行合并为一步因此您需要在运行 Runner 时指定注册信息。
```bash
docker run \
@@ -172,13 +174,13 @@ docker run \
-e GITEA_RUNNER_NAME=<runner_name> \
-e GITEA_RUNNER_LABELS=<runner_labels> \
--name my_runner \
-d gitea/act_runner:nightly
-d gitea/runner:nightly
```
您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
这是因为Act Runner将在Docker容器中运行Job因此它需要与Docker守护进程进行通信。
这是因为 Runner 将在Docker容器中运行Job因此它需要与Docker守护进程进行通信。
如前所述如果要在主机上直接运行Job可以将其移除。
需要明确的是,这里的 "主机" 实际上指的是当前运行 Act Runner的容器而不是主机机器本身。
需要明确的是,这里的 "主机" 实际上指的是当前运行 Runner 的容器,而不是主机机器本身。
### 使用 Docker compose 运行 Runner
@@ -188,7 +190,7 @@ docker run \
version: "3.8"
services:
runner:
image: gitea/act_runner:nightly
image: gitea/runner:nightly
environment:
CONFIG_FILE: /config.yaml
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
@@ -231,14 +233,14 @@ cache:
docker run \
--name gitea-docker-runner \
-p 8088:8088 \
-d gitea/act_runner:nightly
-d gitea/runner:nightly
```
### 标签
```mermaid
flowchart TD
A[Workflow: runs-on: ubuntu-22.04] --> B[Act Runner 收到 Job 请求]
A[Workflow: runs-on: ubuntu-22.04] --> B[Runner 收到 Job 请求]
B --> C[匹配标签: ubuntu-22.04:docker://node:16-bullseye]
C --> D[启动 Docker 容器: node:16-bullseye]
D --> E[在容器中运行 Job 步骤]
@@ -259,18 +261,16 @@ Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们
如果您想直接在主机上运行Job您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04``:host`是可选的。
然而,我们建议您使用类似`linux_amd64:host``windows:host`的特殊名称,以避免误用。
从 Gitea 1.21 开始,您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签(如果没有配置文件,请参考 [配置教程](#配置)),通过执行 `./act_runner daemon --config config.yaml` 命令重启 runner 之后,这些新定义的标签就会生效。
从 Gitea 1.21 开始,您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签(如果没有配置文件,请参考 [配置教程](#配置)),通过执行 `./runner daemon --config config.yaml` 命令重启 runner 之后,这些新定义的标签就会生效。
## 运行
注册完Runner后您可以通过运行以下命令来运行它
```bash
./act_runner daemon
./runner daemon
# or
./act_runner daemon --config config.yaml
./runner daemon --config config.yaml
```
Runner将从Gitea实例获取Job并自动运行它们。
由于Act Runner仍处于开发中建议定期检查最新版本并进行升级。

View File

@@ -75,7 +75,7 @@ Runner和Job容器由Runner启动以执行Job将连接到此地址。
![view runner](/images/usage/actions/view-runner.png)
您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
您可以通过访问[act runner](act-runner) 获取更多信息。
### 使用Actions

View File

@@ -75,7 +75,7 @@ Runner和Job容器由Runner启动以执行Job将连接到此地址。
![view runner](/images/usage/actions/view-runner.png)
您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
您可以通过访问[act runner](act-runner) 获取更多信息。
### 使用Actions

View File

@@ -8,33 +8,9 @@ sidebar_position: 40
Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
## Act
## Gitea Runner
[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。
Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支
与其他CI Runner一样我们将其设计为Gitea的外部部分这意味着它应该在与Gitea不同的服务器上运行。
@@ -47,7 +23,7 @@ Gitea的Runner被称为act runner因为它基于act。
这意味着Runner可以接受需要在`my_custom_label`上运行的Job并通过使用`centos:7`镜像的Docker容器来运行它。
然而Docker不是唯一的选择。
act 也支持直接在主机上运行Job。
Runner 也支持直接在主机上运行Job。
这是通过像`linux_arm:host`这样的标签实现的。
这个标签表示Runner可以接受需要在`linux_arm`上运行的Job并直接在主机上运行它们。
@@ -63,7 +39,7 @@ act 也支持直接在主机上运行Job。
## 通信协议
由于act runner是Gitea的独立部分我们需要一种协议让Runner与Gitea实例进行通信。
由于 runner 是Gitea的独立部分我们需要一种协议让Runner与Gitea实例进行通信。
然而我们不认为让Gitea监听一个新端口是个好主意。
相反我们希望重用HTTP端口这意味着我们需要一个与HTTP兼容的协议。
因此我们选择使用基于HTTP的gRPC。
@@ -80,9 +56,9 @@ act 也支持直接在主机上运行Job。
图片中标记了四个网络连接,并且箭头的方向表示建立连接的方向。
### 连接 1act runner到Gitea实例
### 连接 1 runner到Gitea实例
act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
### 连接 2Job容器到Gitea实例
@@ -93,9 +69,9 @@ act runner 必须能够连接到Gitea以接收任务并发送执行结果回来
如果您使用回环地址注册Runner当Runner与Gitea在同一台机器上时Runner可以连接到Gitea。
然而如果Job容器尝试从本地主机获取代码它将失败因为Gitea不在同一个容器中。
### 连接 3act runner到互联网
### 连接 3runner到互联网
当您使用诸如 `actions/checkout@v4` 的一些Actions时act runner下载的是脚本而不是Job容器。
当您使用诸如 `actions/checkout@v4` 的一些Actions时runner 下载的是脚本而不是Job容器。
默认情况下,它从[github.com](http://github.com/)下载,因此需要访问互联网。如果您设置的是 self
那么默认将从您的当前Gitea实例下载那么此步骤不需要连接到互联网。
它还默认从Docker Hub下载一些Docker镜像这也需要互联网访问。

View File

@@ -73,7 +73,7 @@ Runner仅具有连接到您的Gitea实例的权限。
- 对于 fork 的拉取请求需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
- 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner我们不会反对只是不会在我们的组织中使用它。然而他们应该注意确保该Runner不被他们不认识的其他用户使用。
## act runner支持哪些操作系统
## runner支持哪些操作系统
它在Linux、macOS和Windows上运行良好。
虽然理论上支持其他操作系统,但需要进一步测试。
@@ -101,7 +101,7 @@ defaults:
这是有效的语法。
它意味着它应该在具有`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 并不支持这种方式。
不幸的是runner 并不支持这种方式。
如上所述,我们将标签映射到环境:
- `ubuntu``ubuntu:22.04`
@@ -117,9 +117,9 @@ defaults:
具有`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)。
参见[runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
目前,act runner尝试匹配标签中的每一个并使用找到的第一个匹配项。
目前, runner尝试匹配标签中的每一个并使用找到的第一个匹配项。
## 代理标签和自定义标签对于Runner有什么区别
@@ -132,16 +132,16 @@ defaults:
您可以向已注册的Runner添加自定义标签比如 `centos`这意味着该Runner将接收具有`runs-on: centos`的Job。
然而Runner可能不知道要使用哪个环境来执行该标签导致它使用默认镜像或导致逻辑死胡同。
这个默认值可能与用户的期望不符。
参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
参见[runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
与此同时如果您想更改Runner的标签我们建议您重新注册Runner。
## Gitea Actions runner会有更多的实现吗
虽然我们希望提供更多的选择,但由于我们有限的人力资源,act runner将是唯一受支持的官方Runner。
然而无论您如何决定Gitea 和act runner都是完全开源的所以任何人都可以创建一个新的/更好的实现。
虽然我们希望提供更多的选择,但由于我们有限的人力资源, runner将是唯一受支持的官方Runner。
然而无论您如何决定Gitea 和 runner都是完全开源的所以任何人都可以创建一个新的/更好的实现。
我们支持您的选择,无论您如何决定。
如果您选择分支act runner来创建自己的版本请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
如果您选择分支 runner 来创建自己的版本,请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
## Gitea 支持哪些工作流触发事件?

View File

@@ -21,8 +21,8 @@ Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且
## 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)
Gitea Actions的Runner被称为[Gitea Runner](https://gitea.com/gitea/runner)它是一个独立的程序也是用Go语言编写的。
的重要部分来自[nektos/act](http://github.com/nektos/act)的一个硬分支
由于Runner是独立部署的可能存在潜在的安全问题。
为了避免这些问题,请遵循两个简单的规则:

View File

@@ -25,10 +25,10 @@ ENABLED=true
### 设置Runner
Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
为了避免消耗过多资源并影响Gitea实例建议您在与Gitea实例分开的机器上启动Runner。
您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。
在进一步操作之前建议您先使用预构建的二进制文件以命令行方式运行它以确保它与您的环境兼容尤其是如果您在本地主机上运行Runner。
如果出现问题,这样调试起来会更容易。
@@ -40,7 +40,7 @@ Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job
在运行Runner之前您需要使用以下命令将其注册到Gitea实例中
```bash
./act_runner register --no-interactive --instance <instance> --token <token>
./runner register --no-interactive --instance <instance> --token <token>
```
需要两个必需的参数:`instance``token`
@@ -68,14 +68,14 @@ Runner和Job容器由Runner启动以执行Job将连接到此地址。
最后是时候启动Runner了
```bash
./act_runner daemon
./runner daemon
```
您可以在管理页面上看到新的Runner
![view runner](/images/usage/actions/view-runner.png)
您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
您可以通过访问[runner](runner) 获取更多信息。
### 使用Actions

View File

@@ -1,12 +1,14 @@
---
date: "2023-05-24T15:00:00+08:00"
slug: "act-runner"
slug: "runner"
sidebar_position: 20
aliases:
- /zh-tw/act-runner
---
# Act Runner
# Gitea Runner
本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)这是Gitea Actions的Runner。
本页面将详细介绍[Gitea Runner](https://gitea.com/gitea/runner)这是Gitea Actions的Runner。
## 要求
@@ -19,31 +21,31 @@ sidebar_position: 20
## 安装
有多种安装Act Runner的方法。
有多种安装Gitea Runner的方法。
### 下载二进制文件
您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
然而,如果您想使用最新的夜间构建版本,可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
您可以从[发布页面](https://gitea.com/gitea/runner/releases)下载二进制文件。
然而,如果您想使用最新的夜间构建版本,可以从[下载页面](https://dl.gitea.com/gitea-runner/)下载。
下载二进制文件时,请确保您已经下载了适用于您的平台的正确版本。
您可以通过运行以下命令进行检查:
```bash
chmod +x act_runner
./act_runner --version
chmod +x runner
./runner --version
```
如果看到版本信息,则表示您已经下载了正确的二进制文件。
### 使用 Docker 镜像
您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
您可以使用[docker hub](https://hub.docker.com/r/gitea/runner/tags)上的Docker镜像。
与二进制文件类似,您可以使用`nightly`标签使用最新的夜间构建版本,而`latest`标签是最新的稳定版本。
```bash
docker pull docker.io/gitea/act_runner:latest # for the latest stable release
docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
docker pull docker.io/gitea/runner:latest # for the latest stable release
docker pull docker.io/gitea/runner:nightly # for the latest nightly build
```
## 配置
@@ -53,20 +55,20 @@ docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
您可以通过运行以下命令生成配置文件:
```bash
./act_runner generate-config
./runner generate-config
```
默认配置是安全的,可以直接使用。
```bash
./act_runner generate-config > config.yaml
./act_runner --config config.yaml [command]
./runner generate-config > config.yaml
./runner --config config.yaml [command]
```
您亦可以如下使用 docker 创建配置文件:
```bash
docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
docker run --entrypoint="" --rm -it docker.io/gitea/runner:latest runner generate-config > config.yaml
```
当使用Docker镜像时可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中:
@@ -75,12 +77,12 @@ docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner
docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
```
您可能注意到上面的命令都是不完整的,因为现在还不是运行Act Runner的时候。
在运行Act Runner之前我们需要首先将其注册到您的Gitea实例中。
您可能注意到上面的命令都是不完整的,因为现在还不是运行 Runner 的时候。
在运行 Runner 之前我们需要首先将其注册到您的Gitea实例中。
## 注册
在运行Act Runner之前需要进行注册因为Runner需要知道从哪里获取Job并且对于Gitea实例来说识别Runner也很重要。
在运行 Runner 之前,需要进行注册,因为 Runner 需要知道从哪里获取Job并且对于Gitea实例来说识别Runner也很重要。
### Runner级别
@@ -124,16 +126,16 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
### 注册 Runner
可以通过运行以下命令来注册Act Runner
可以通过运行以下命令来注册 Runner
```bash
./act_runner register
./runner register
```
或者,您可以使用 `--config` 选项来指定前面部分提到的配置文件。
```bash
./act_runner --config config.yaml register
./runner --config config.yaml register
```
您将逐步输入注册信息,包括:
@@ -148,7 +150,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
如果您想以非交互方式注册Runner可以使用参数执行以下操作。
```bash
./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
./runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
```
注册Runner后您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
@@ -159,7 +161,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
### 使用Docker注册Runner
如果您使用的是Docker镜像注册行为会略有不同。在这种情况下注册和运行合并为一步因此您需要在运行Act Runner时指定注册信息。
如果您使用的是Docker镜像注册行为会略有不同。在这种情况下注册和运行合并为一步因此您需要在运行 Runner 时指定注册信息。
```bash
docker run \
@@ -172,13 +174,13 @@ docker run \
-e GITEA_RUNNER_NAME=<runner_name> \
-e GITEA_RUNNER_LABELS=<runner_labels> \
--name my_runner \
-d gitea/act_runner:nightly
-d gitea/runner:nightly
```
您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
这是因为Act Runner将在Docker容器中运行Job因此它需要与Docker守护进程进行通信。
这是因为 Runner 将在Docker容器中运行Job因此它需要与Docker守护进程进行通信。
如前所述如果要在主机上直接运行Job可以将其移除。
需要明确的是,这里的 "主机" 实际上指的是当前运行 Act Runner的容器而不是主机机器本身。
需要明确的是,这里的 "主机" 实际上指的是当前运行 Runner的容器而不是主机机器本身。
### 使用 Docker compose 运行 Runner
@@ -188,7 +190,7 @@ docker run \
version: "3.8"
services:
runner:
image: gitea/act_runner:nightly
image: gitea/runner:nightly
environment:
CONFIG_FILE: /config.yaml
GITEA_INSTANCE_URL: "${INSTANCE_URL}"
@@ -231,14 +233,14 @@ cache:
docker run \
--name gitea-docker-runner \
-p 8088:8088 \
-d gitea/act_runner:nightly
-d gitea/runner:nightly
```
### 标签
```mermaid
flowchart TD
A[Workflow: runs-on: ubuntu-22.04] --> B[Act Runner 收到 Job 請求]
A[Workflow: runs-on: ubuntu-22.04] --> B[Runner 收到 Job 請求]
B --> C[匹配標籤: ubuntu-22.04:docker://node:16-bullseye]
C --> D[啟動 Docker 容器: node:16-bullseye]
D --> E[在容器中執行 Job 步驟]
@@ -259,18 +261,18 @@ Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们
如果您想直接在主机上运行Job您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04``:host`是可选的。
然而,我们建议您使用类似`linux_amd64:host``windows:host`的特殊名称,以避免误用。
从 Gitea 1.21 开始,您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签(如果没有配置文件,请参考 [配置教程](#配置)),通过执行 `./act_runner daemon --config config.yaml` 命令重启 runner 之后,这些新定义的标签就会生效。
从 Gitea 1.21 开始,您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签(如果没有配置文件,请参考 [配置教程](#配置)),通过执行 `./runner daemon --config config.yaml` 命令重启 runner 之后,这些新定义的标签就会生效。
## 运行
注册完Runner后您可以通过运行以下命令来运行它
```bash
./act_runner daemon
./runner daemon
# or
./act_runner daemon --config config.yaml
./runner daemon --config config.yaml
```
Runner将从Gitea实例获取Job并自动运行它们。
由于Act Runner仍处于开发中,建议定期检查最新版本并进行升级。
由于Gitea Runner仍在不断升级中,建议定期检查最新版本并进行升级。

View File

@@ -1,6 +1,6 @@
---
date: "2023-05-15T00:00:00+00:00"
slug: "container"
slug: "arch"
sidebar_position: 5
---

View File

@@ -75,7 +75,7 @@ Runner和Job容器由Runner启动以执行Job将连接到此地址。
![view runner](/images/usage/actions/view-runner.png)
您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
您可以通过访问[act runner](act-runner) 获取更多信息。
### 使用Actions

View File

@@ -75,7 +75,7 @@ Runner和Job容器由Runner启动以执行Job将连接到此地址。
![view runner](/images/usage/actions/view-runner.png)
您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
您可以通过访问[act runner](act-runner) 获取更多信息。
### 使用Actions

View File

@@ -3,6 +3,6 @@ sidebar_position: 1
slug: /
---
import ActRunnerDoc from '@site/docs/usage/actions/act-runner.mdx';
import RunnerDoc from '@site/docs/usage/actions/runner.mdx';
<ActRunnerDoc />
<RunnerDoc />

View File

@@ -9,7 +9,7 @@ Thank you for your interest in contributing to Gitea! This guide will help you u
## Getting Started
Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea.md) guide to set up your development environment.
Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea) guide to set up your development environment.
## Contribution Guidelines
@@ -17,7 +17,7 @@ We have specific guidelines for different types of contributions:
### Backend Development
If you're working on backend code (Go), please follow our [Guidelines for Backend Development](guidelines-backend.md). This includes:
If you're working on backend code (Go), please follow our [Guidelines for Backend Development](./guidelines-backend). This includes:
- Package design and dependencies
- Database operations and migrations
@@ -26,7 +26,7 @@ If you're working on backend code (Go), please follow our [Guidelines for Backen
### Frontend Development
For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](guidelines-frontend.md). This covers:
For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](./guidelines-frontend). This covers:
- Framework usage (Vue3, Fomantic-UI)
- Code style and best practices
@@ -35,7 +35,7 @@ For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for
### Refactoring
When refactoring existing code, follow our [Guidelines for Refactoring](guidelines-refactoring.md) to ensure:
When refactoring existing code, follow our [Guidelines for Refactoring](./guidelines-refactoring) to ensure:
- Clear refactoring objectives
- Proper review process
@@ -44,7 +44,7 @@ When refactoring existing code, follow our [Guidelines for Refactoring](guidelin
### Localization
To contribute translations or localization improvements, see our [Localization Guide](localization.md) which explains:
To contribute translations or localization improvements, see our [Localization Guide](./localization) which explains:
- How to contribute translations via Crowdin
- Supported languages

View File

@@ -76,7 +76,7 @@ And you can see the new runner in the management page:
![view runner](/images/usage/actions/view-runner.png)
You can find more information by visiting [Act runner](act-runner.mdxc).
You can find more information by visiting [Act runner](act-runner.mdx).
### Use Actions