mash-playbook/docs/services/forgejo-runner.md

Forgejo Runner

Forgejo Runner is a runner to use with Forgejo Actions. It provides a way to perform CI using Forgejo. You might also be interested in Woodpecker CI (that this playbook also supports).

Warning

Upstream considers this software as being an alpha release, and says it should not be considered secure enough to deploy in production. Use at your own risk.

Configuration

To enable this service, add the following configuration to your vars.yml file and re-run the installation process:

########################################################################
#                                                                      #
# forgejo-runner                                                       #
#                                                                      #
########################################################################

forgejo_runner_enabled: true

forgejo_runner_runner_name: "Your Runner Name Here"

# The instance URL.
forgejo_runner_instance_url: "https://example.com"

# The registration token.
#
# Should be obtained via the web interface, by going to:
#
#   Site Administration -> Actions -> Runners -> Create new runner
forgejo_runner_registration_token: "TOKEN_HERE"

# The capacity of the runner, i.e., how many concurrent tasks it can run.
forgejo_runner_capacity: 1

# The labels associated with this runner.
forgejo_runner_labels:
  - ubuntu-22.04:docker://node:20-bullseye

########################################################################
#                                                                      #
# /forgejo-runner                                                      #
#                                                                      #
########################################################################

As mentioned in the example above, the registration token should be obtained via Forgejo's web interface, by going to Site Administration -> Actions -> Runners -> Create new runner.

Labels are an important aspect of the runner, and as such should be carefully chosen. Read the official documentation for more information.

Usage

After the installation, the runner will register with the Forgejo instance (provided via the forgejo_runner_instance_url variable) and generate a .runner file inside its configuration path. This file should not be modified manually. If for some reason you wish to force the registration to run again, you can delete the .runner file and restart the service.

If you with to change the labels associated with the runner, you can simply modify the forgejo_runner_labels variable and run the playbook again. There is no need to delete the .runner file and run the registration again.