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.
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.
After Gitea 1.21 released, you can change labels by modfiying `container.labels` in configuration file (if you don't have a configuration file, please refer to [configuration tutorials](#configuration)), and runner will declare the new labels which you defined in configuration file after executing `./act_runner daemon --config config.yaml`.
You can create configuration varibales with user, organization, repository level. And the level of the variable depends on which setting panel you created in.
### Naming conventions
The following rules apply to variable names:
- Varibale names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
- Varibale names must not start with the `GITHUB_` and `GITEA_` prefix.
- Varibale names must not start with a number.
- Varibale names are not case-sensitive.
- Varibale names must be unique at the level they are created at.
- Varibale names must not be 'CI'.
### Using varibales
After creating configuration varibales, they will be automatically filled in the `vars` context. They are available to you with expression like `{{ vars.VARIABLE_NAME }}` in workflow.
### Precedence
If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence(the level of organization and user is higher than repository's).
For example, if an organization-level variable has the same name as a repository-level variable, then the repository-level variable takes precedence.
