# Ansible Role Forgejo Runners

Ansible role to manage [Forgejo](https://forgejo.org/) runners.

## Configuration

See [Variable
precedence](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#ansible-variable-precedence)
to find where you should put your own variables.

Then define at least `forgejo_db_password` with a strong and secure password,
encrypted using
[ansible-vault](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html).


## Table of Content

<!-- ANSIBLE DOCSMITH TOC START -->
* [Role variables](#variables)
  * [`forgejo_runners_version`](#variable-forgejo_runners_version)
  * [`forgejo_runners_user`](#variable-forgejo_runners_user)
  * [`forgejo_runners_home_dir`](#variable-forgejo_runners_home_dir)
  * [`forgejo_runners_config_dir`](#variable-forgejo_runners_config_dir)
  * [`forgejo_runners_instance`](#variable-forgejo_runners_instance)
  * [`forgejo_runners_settings`](#variable-forgejo_runners_settings)
<!-- ANSIBLE DOCSMITH TOC END -->
<!-- ANSIBLE DOCSMITH MAIN START -->

## Role variables<a id="variables"></a>

The following variables can be configured for this role:

| Variable | Type | Required | Default | Description (abstract) |
|----------|------|----------|---------|------------------------|
| `forgejo_runners_version` | `str` | No | `"9.1.1"` | Version of the runners |
| `forgejo_runners_user` | `str` | No | `"forgejo"` | Operating system user to run the runners |
| `forgejo_runners_home_dir` | `str` | No | `"/var/lib/forgejo"` | Home directory of the operating system user |
| `forgejo_runners_config_dir` | `path` | No | `"/etc/forgejo-runners"` | Path to the configuration directory of the runners |
| `forgejo_runners_instance` | `str` | No | N/A | URL of the Forgejo instance to register the runners |
| `forgejo_runners_settings` | `dict` | No | N/A | Dict of runners to configure<br><br>The key is the name of the repository on the instance<br><br>The value is a dict with a `token` key and optionally a dict of `labels` |

### `forgejo_runners_version`<a id="variable-forgejo_runners_version"></a>

[*⇑ Back to ToC ⇑*](#toc)

Version of the runners

- **Type**: `str`
- **Required**: No
- **Default**: `"9.1.1"`



### `forgejo_runners_user`<a id="variable-forgejo_runners_user"></a>

[*⇑ Back to ToC ⇑*](#toc)

Operating system user to run the runners

- **Type**: `str`
- **Required**: No
- **Default**: `"forgejo"`



### `forgejo_runners_home_dir`<a id="variable-forgejo_runners_home_dir"></a>

[*⇑ Back to ToC ⇑*](#toc)

Home directory of the operating system user

- **Type**: `str`
- **Required**: No
- **Default**: `"/var/lib/forgejo"`



### `forgejo_runners_config_dir`<a id="variable-forgejo_runners_config_dir"></a>

[*⇑ Back to ToC ⇑*](#toc)

Path to the configuration directory of the runners

- **Type**: `path`
- **Required**: No
- **Default**: `"/etc/forgejo-runners"`



### `forgejo_runners_instance`<a id="variable-forgejo_runners_instance"></a>

[*⇑ Back to ToC ⇑*](#toc)

URL of the Forgejo instance to register the runners

- **Type**: `str`
- **Required**: No



### `forgejo_runners_settings`<a id="variable-forgejo_runners_settings"></a>

[*⇑ Back to ToC ⇑*](#toc)

Dict of runners to configure

The key is the name of the repository on the instance

The value is a dict with a `token` key and optionally a dict of `labels`

- **Type**: `dict`
- **Required**: No




<!-- ANSIBLE DOCSMITH MAIN END -->

## Usage

Example of a basic playbook:

```yaml
- hosts: forgejo_runners
  roles:
    - forgejo_runners
  vars:
    forgejo_runners_instance: https://codeberg.org  # FIXME
    forgejo_runners:
      my_runner:
        token: **redacted**
        labels:
          node-latest: docker://data.forgejo.org/oci/node:latest
```

Then run the playbook:

```
ansible-playbook forgejo_runners.yml
```

## Donate

As we all love FOSS projects, you should consider [donating to
Codeberg](https://donate.codeberg.org/), the non-profit organization behind
Forgejo.