When you are using the docker image, you can specify the configuration file by using the `CONFIG_FILE` environment variable. Make sure that the file is mounted into the container as a volume:
```bash
docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
```
You may notice the commands above are both incomplete, because it is not the time to run the act runner yet.
Before running the act runner, we need to register it to your Gitea instance first.
## Registration
Registration is required before running the act runner, because the runner needs to know where to get jobs from.
And it is also important to Gitea instance to identify the runner.
### Runner levels
You can register a runner in different levels, it can be:
- Instance level: The runner will run jobs for all repositories in the instance.
- Organization level: The runner will run jobs for all repositories in the organization.
- Repository level: The runner will run jobs for the repository it belongs to.
Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this.
### Obtain a registration token
The level of the runner determines where to obtain the registration token.
- Instance level: The admin settings page, like `<your_gitea.com>/admin/runners`.
- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/runners`.
- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/runners`.
If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.
The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`.
### Register the runner
The act runner can be registered by running the following command:
```bash
./act_runner register
```
Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section.
```bash
./act_runner --config config.yaml register
```
You will be asked to input the registration information step by step. Includes:
- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`.
- The registration token.
- The runner name, which is optional. If you leave it blank, the hostname will be used.
- The runner labels, which is optional. If you leave it blank, the default labels will be used.
You may be confused about the runner labels, which will be explained later.
If you want to register the runner in a non-interactive way, you can use arguments to do it.
When you have registered the runner, you can find a new file named `.runner` in the current directory.
This file stores the registration information.
Please do not edit it manually.
If this file is missing or corrupted, you can simply remove it and register again.
If you want to store the registration information in another place, you can specify it in the configuration file,
and don't forget to specify the `--config` option.
### Register the runner with docker
If you are using the docker image, behaviour will be slightly different. Registration and running are combined into one step in this case, so you need to specify the registration information when running the act runner.
The labels of a runner are used to determine which jobs the runner can run, and how to run them.
The default labels are `ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`.
It is a comma-separated list, and each item is a label.
Let's take `ubuntu-22.04:docker://node:16-bullseye` as an example.
It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job will be run in a docker container with the image `node:16-bullseye`.
If the default image is insufficient for your needs, and you have enough disk space to use a better and bigger one, you can change it to `ubuntu-22.04:docker://<the image you like>`.
You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md).
If you want to run jobs in the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`, the `:host` is optional.
However, we suggest you to use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
One more thing is that it is recommended to register the runner if you want to change the labels.
It may be annoying to do this, so we may provide a better way to do it in the future.
## Running
After you have registered the runner, you can run it by running the following command:
```bash
./act_runner daemon
# or
./act_runner daemon --config config.yaml
```
The runner will fetch jobs from the Gitea instance and run them automatically.
Since act runner is still in development, it is recommended to check the latest version and upgrade it regularly.
