gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-06-11 04:31:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

rename act runner to runner (#390)

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/contributing/contributing.md
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

40
docs/usage/actions/design.md
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.

16
docs/usage/actions/faq.md
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?

4
docs/usage/actions/overview.md
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:

10
docs/usage/actions/quickstart.md
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

122
docs/usage/actions/act-runner.mdx → docs/usage/actions/runner.mdx
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`.

2
docs/usage/actions/variables.md
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_***` |