centersl/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-03-27 05:58:30 +07:00
Code Issues Packages Projects Releases Wiki Activity

Fix act runner doc typos and errors and simplify some grammar. (#328)

Browse Source 
Fix act runner doc typos and errors and simplify some grammar.

Co-authored-by: Peter Ryszkiewicz <prizz@noreply.gitea.com>
Co-committed-by: Peter Ryszkiewicz <prizz@noreply.gitea.com>
This commit is contained in:
Peter Ryszkiewicz
2026-02-03 00:52:06 +00:00
committed by techknowlogick
parent ed033ac9ed
commit 8a40822acd
1 changed files with 37 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/usage/actions/act-runner.mdx
View File

@@ -6,18 +6,18 @@ sidebar_position: 20
# Act Runner
This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner of Gitea Actions.
This page will introduce the [act runner](https://gitea.com/gitea/act_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.
2. Docker (recommended): Runs 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.
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 less privileges. Will spawn job containers from there. Best security but more complex setup.
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.
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.
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.
@@ -29,7 +29,7 @@ You can download the binary from the [release page](https://gitea.com/gitea/act_
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 if you are in a Unix-Style OS.
You can check it by running the following command if you are in a Unix-style OS.
```bash
chmod +x act_runner
@@ -40,7 +40,7 @@ If you see the version information, it means that you have downloaded the correc
### Obtain a registration token
You can register a runner in different levels, it can be:
You can register a runner at different levels. It can be:
- Instance level: The runner will run jobs for all repositories in the instance.
- Organization level: The runner will run jobs for all repositories in the organization.
@@ -49,7 +49,7 @@ 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.
Before register the runner and run it, you need a registration token. The level of the runner determines where to obtain the registration token.
Before registering the runner and running 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`.
@@ -59,13 +59,13 @@ If you cannot see the settings page, please make sure that you have the right pe
The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`.
A registration token can also be obtained from the gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
A registration token can also be obtained from the Gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
```
gitea --config /etc/gitea/app.ini actions generate-runner-token
```
You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variable to set a global runner registration token when Gitea starts, for example:
You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variables to set a global runner registration token when Gitea starts, for example:
```
openssl rand -hex 24 > /some-dir/runner-token
@@ -73,7 +73,7 @@ export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
./gitea --config ...
```
The token from environment is valid until you reset the token (re-create a new one) via web UI or API.
The token from the environment is valid until you reset the token (re-create a new one) via the web UI or API.
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.
@@ -94,7 +94,7 @@ The default configuration is safe to use without any modification, so you can ju
### Register the runner
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.
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.
If this has been installed using the binary package, the act runner can be registered by running the following command.
@@ -108,7 +108,7 @@ Alternatively, you can use the `--config` option to specify the configuration fi
./act_runner --config config.yaml register
```
You will be asked to input the registration information step by step. Includes:
You will be asked to input the registration information step by step. This includes:
- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`.
- The registration token.
@@ -135,7 +135,7 @@ 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+** required.
act_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.
@@ -155,9 +155,9 @@ The runner must be registered each time it is intended to receive a job. After c
To automate the registration and startup of new runners when a job is queued, use the `workflow_job` webhook.
### Start the runner in command line
### Start the runner from the command line
After you have registered the runner, you can run it by running the following command:
After you have registered the runner, you can run it with the following command:
```shell
./act_runner daemon
@@ -173,7 +173,7 @@ 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.
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.
```ini
[Unit]
@@ -205,9 +205,9 @@ 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)
### 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.
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.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -252,27 +252,27 @@ Then:
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.
You can also set up a Linux 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).
You can use the docker image from [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 docker.io/gitea/act_runner:latest # for the latest stable release
```
If you want to use the newest or experimental features, you could also use the nightly image
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
```
### Configuration
Configuration is optional, but you could also generate config file with docker:
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
@@ -284,14 +284,14 @@ 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 both incomplete, because it is not the time to run the act runner yet.
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.
### 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.
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 `<container_name>`
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>`.
```bash
docker run \
@@ -303,7 +303,7 @@ docker run \
-d docker.io/gitea/act_runner:latest
```
You can add more parameters to use a custom config, add a `data` directory for non-voltatile file storage etc.
You can add more parameters to use a custom config, add a `data` directory for non-volatile file storage, etc.
```bash
docker run \
@@ -320,9 +320,9 @@ docker run \
```
You may notice that we have mounted `/var/run/docker.sock` into the container.
It is because with this setup, act 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 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.
This is because with this setup, act 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.
---
@@ -401,13 +401,13 @@ 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 of 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 [act_runner](https://gitea.com/gitea/act_runner/src/branch/main/examples) repository.
## Advanced Configurations
### Configuring cache when starting a Runner using docker image
### Configuring cache when starting a runner using the docker image
If you do not intend to use `actions/cache` in workflow, you can ignore this section.
If you do not intend to use `actions/cache` in your workflow, you can ignore this section.
If you use `actions/cache` without any additional configuration, it will return the following error:
> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
@@ -416,9 +416,9 @@ The error occurs because the runner container and job container are on different
Therefore, it is essential to configure the cache action to ensure its proper functioning. Follow these steps:
- 1.Obtain the LAN IP address of the host machine where the runner container is running.
- 2.Find an available port number on the host machine where the runner container is running.
- 3.Configure the following settings in the configuration file:
- 1. Obtain the LAN IP address of the host machine where the runner container is running.
- 2. Find an available port number on the host machine where the runner container is running.
- 3. Configure the following settings in the configuration file:
```yaml
cache:
@@ -430,7 +430,7 @@ cache:
port: 8088
```
- 4.When starting the container, map the cache port to the host machine:
- 4. When starting the container, map the cache port to the host machine:
```bash
docker run \
@@ -452,8 +452,8 @@ It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job
If the default image is insufficient for your needs, and you have enough disk space to use a better and bigger one, you can change it to `ubuntu-22.04:docker://<the image you like>`.
You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md).
If you want to run jobs in the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`, the `:host` is optional.
However, we suggest you to use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
If you want to run jobs on the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`; `:host` is optional.
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`.