# Gitea Runner
We provide runners that you can use for the CI/CD in Gitea.

## Runner Images
Our runners can run different docker images for your workflows please refer to https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container for details

If none of the default runners available suits you, you can contact [Gitea Project](mailto:gitea@psi.ch) and we can find a solution that fits you best.

## Actions
Actions can sometimes be used from GitHub, but are likely to break. There are some actions in https://gitea.psi.ch/actions that are proven working. Also you can checkout https://gitea.com/actions/ and if you find any useful to you we can mirror these. [Gitea Project](mailto:gitea@psi.ch)

## Custom Runner

If you need/want to run your own runner, you can either install the runner by RPM or run it in a docker container. A version of the runner RPM is available on repos.psi.ch. The package itself can also be found at https://gitea.psi.ch/lx_packages/act-runner. 


However, we recommend to run the runner in a docker container, as it is easier to maintain and update.

Before you can register a runner (regardless whether you use the RPM or Docker method), you need to create a registration token. You can do this by following the steps below:

- On your organization or repository page, click on **Settings**
- In the left sidebar, click **Actions**
- Click **Runners**
- On the right side, click **Create new Runner**
- Copy and save the registration token (it will only be displayed once!)
- This token you will need to register your runner with your Gitea instance in the following steps.

![](_static/create_runner_token.png)


### RPM Runner

To setup an [RPM based runner](https://gitea.psi.ch/lx_packages/act-runner), please follow the steps below:

1. Install the runner package:
```bash
sudo dnf install act-runner
```
2. Create a config.yaml file in /etc/act-runner/config.yaml and register the runner with your Gitea instance:
```bash
act_runner generate-config > /etc/act_runner/config.yaml
# adapt location of .runner file
act_runner --config /etc/act_runner/config.yaml register
# need registration token
```
3. Start the runner:
```bash
sudo systemctl enable --now act_runner
```

### Docker Runner

A docker based runner can be deployes via the following steps:

1. Install docker on your machine
2. Create a directory with a config.yaml and docker-compose.yaml file:

config.yaml:
```yaml
# Example configuration file, it's safe to copy this as the default config file without any modification.

# You don't have to copy this file to your instance,
# just run `./act_runner generate-config > config.yaml` to generate a config file.

log:
  # The level of logging, can be trace, debug, info, warn, error, fatal
  level: warn

runner:
  # Where to store the registration result.
  file: .runner
  # Execute how many tasks concurrently at the same time.
  capacity: 5
  # Extra environment variables to run jobs.
  envs:
    # A_TEST_ENV_NAME_1: a_test_env_value_1
    # A_TEST_ENV_NAME_2: a_test_env_value_2
  # Extra environment variables to run jobs from a file.
  # It will be ignored if it's empty or the file doesn't exist.
  env_file: .env
  # The timeout for a job to be finished.
  # Please note that the Gitea instance also has a timeout (3h by default) for the job.
  # So the job could be stopped by the Gitea instance if it's timeout is shorter than this.
  timeout: 3h
  # The timeout for the runner to wait for running jobs to finish when shutting down.
  # Any running jobs that haven't finished after this timeout will be cancelled.
  shutdown_timeout: 0s
  # Whether skip verifying the TLS certificate of the Gitea instance.
  insecure: false
  # The timeout for fetching the job from the Gitea instance.
  fetch_timeout: 5s
  # The interval for fetching the job from the Gitea instance.
  fetch_interval: 5s
  # The labels of a runner are used to determine which jobs the runner can run, and how to run them.
  # Like: "macos-arm64:host" or "ubuntu-latest:docker://gitea/runner-images:ubuntu-latest"
  # Find more images provided by Gitea at https://gitea.com/gitea/runner-images .
  # If it's empty when registering, it will ask for inputting labels.
  # If it's empty when execute `daemon`, will use labels in `.runner` file.
  labels:
    - "your_runner_name:host"
cache:
  # Enable cache server to use actions/cache.
  enabled: true
  # The directory to store the cache data.
  # If it's empty, the cache data will be stored in $HOME/.cache/actcache.
  dir: "/toolcache"
  # The host of the cache server.
  # It's not for the address to listen, but the address to connect from job containers.
  # So 0.0.0.0 is a bad choice, leave it empty to detect automatically.
  host: "runner"
  # The port of the cache server.
  # 0 means to use a random available port.
  port: 8088
  # The external cache server URL. Valid only when enable is true.
  # If it's specified, act_runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself.
  # The URL should generally end with "/".
  external_server: ""

container:
  # Specifies the network to which the container will connect.
  # Could be host, bridge or the name of a custom network.
  # If it's empty, act_runner will create a network automatically.
  network: "runner_net"
  # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
  privileged: true
  # And other options to be used when the container is started (eg, --add-host=my.gitea.url:host-gateway).
  options:
  # The parent directory of a job's working directory.
  # NOTE: There is no need to add the first '/' of the path as act_runner will add it automatically.
  # If the path starts with '/', the '/' will be trimmed.
  # For example, if the parent directory is /path/to/my/dir, workdir_parent should be path/to/my/dir
  # If it's empty, /workspace will be used.
  workdir_parent:
  # Volumes (including bind mounts) can be mounted to containers. Glob syntax is supported, see https://github.com/gobwas/glob
  # You can specify multiple volumes. If the sequence is empty, no volumes can be mounted.
  # For example, if you only allow containers to mount the `data` volume and all the json files in `/src`, you should change the config to:
  # valid_volumes:
  #   - data
  #   - /src/*.json
  # If you want to allow any volume, please use the following configuration:
  # valid_volumes:
  #   - '**'
  valid_volumes:
    - "**"
  # overrides the docker client host with the specified one.
  # If it's empty, act_runner will find an available docker host automatically.
  # If it's "-", act_runner will find an available docker host automatically, but the docker host won't be mounted to the job containers and service containers.
  # If it's not empty or "-", the specified docker host will be used. An error will be returned if it doesn't work.
  docker_host: ""
  # Pull docker image(s) even if already present
  force_pull: true
  # Rebuild docker image(s) even if already present
  force_rebuild: false

host:
  # The parent directory of a job's working directory.
  # If it's empty, $HOME/.cache/act/ will be used.
  workdir_parent:
```

docker-compose.yaml:
```yaml
services:
  runner:
    container_name: your_runner_name
    image: "gitea.psi.ch/images/alpine-autodeploy:latest"
    restart: always
    environment:
      CONFIG_FILE: "/config.yaml"
      GITEA_INSTANCE_URL: "https://gitea.psi.ch"
      GITEA_RUNNER_REGISTRATION_TOKEN: "your_registration_token"
      GITEA_RUNNER_NAME: "your_runner_name"
    volumes:
      - ./config.yaml:/config.yaml
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/timezone:/etc/timezone:ro"
      # allow the runner to switch to a different image for jobs
      # - "/var/run/docker.sock:/var/run/docker.sock"
      # allow the runner to use a toolcache for caching tools
      # - "/srv/runner/data/toolcache:/toolcache"
      # allow the runner to use a cache for caching actions
      # - "/srv/runner/act:/var/run/act"
      # if you want to allow the runner to mount a volume from the host to the job container, you can add a volume here, for example:
      # - /data:/data
```

3. Run the runner with docker-compose:
```bash
docker-compose up -d
```