jriou.forgejo/README.md

# Ansible Role Forgejo

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

## Installation

Use Ansible Galaxy to install the role locally:

```
ansible-galaxy role install git+https://git.riou.xyz/jriou/jriou.forgejo.git
```

Or use a requirements.yml file:

```yaml
roles:
  - src: git+https://git.riou.xyz/jriou/jriou.forgejo.git
    type: git
```

See [Storing and finding
roles](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#storing-and-finding-roles).

## 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_server`](#variable-forgejo_server)
  * [`forgejo_version`](#variable-forgejo_version)
  * [`forgejo_home_dir`](#variable-forgejo_home_dir)
  * [`forgejo_config_dir`](#variable-forgejo_config_dir)
  * [`forgejo_web_port`](#variable-forgejo_web_port)
  * [`forgejo_ssh_port`](#variable-forgejo_ssh_port)
  * [`forgejo_db_username`](#variable-forgejo_db_username)
  * [`forgejo_db_password`](#variable-forgejo_db_password)
  * [`forgejo_db_database`](#variable-forgejo_db_database)
  * [`forgejo_mailer`](#variable-forgejo_mailer)
  * [`forgejo_service`](#variable-forgejo_service)
  * [`forgejo_manage_iptables`](#variable-forgejo_manage_iptables)
  * [`forgejo_allowed_sources`](#variable-forgejo_allowed_sources)
  * [`forgejo_runners_version`](#variable-forgejo_runners_version)
  * [`forgejo_runners_config_dir`](#variable-forgejo_runners_config_dir)
  * [`forgejo_runners_instance`](#variable-forgejo_runners_instance)
  * [`forgejo_runners`](#variable-forgejo_runners)
<!-- 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_server` | `bool` | No | `true` | Enable the server mode |
| `forgejo_version` | `int` | No | `14` | Version of the Forgejo binaries |
| `forgejo_home_dir` | `path` | No | `"/var/lib/forgejo"` | Path to the home directory |
| `forgejo_config_dir` | `path` | No | `"/etc/forgejo"` | Path to the configuration directory |
| `forgejo_web_port` | `int` | No | `3000` | Port to listen for the web UI |
| `forgejo_ssh_port` | `int` | No | `222` | Port to listen for SSH |
| `forgejo_db_username` | `str` | No | `"forgejo"` | Name of the user in the database |
| `forgejo_db_password` | `str` | Yes | N/A | Password of the user in the database |
| `forgejo_db_database` | `str` | No | `"forgejo"` | Name of the database |
| `forgejo_mailer` | `dict` | No | N/A | Configure the mailer to send e-mail notifications<br><br>Define a `enabled` key with a boolean to enable the mailer<br><br>Define a `from` key with the source e-mail address<br><br>See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/) |
| `forgejo_service` | `dict` | No | N/A | Configure service settings<br><br>See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service) |
| `forgejo_manage_iptables` | `bool` | No | `false` | Configure iptables rules |
| `forgejo_allowed_sources` | `list` | No | N/A | List of IP ranges to allow when `forgejo_manage_iptables` is enabled |
| `forgejo_runners_version` | `str` | No | `"9.1.1"` | Version of the runners |
| `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` | `dict` | No | N/A | List 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_server`<a id="variable-forgejo_server"></a>

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

Enable the server mode

- **Type**: `bool`
- **Required**: No
- **Default**: `true`



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

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

Version of the Forgejo binaries

- **Type**: `int`
- **Required**: No
- **Default**: `14`



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

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

Path to the home directory

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



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

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

Path to the configuration directory

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



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

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

Port to listen for the web UI

- **Type**: `int`
- **Required**: No
- **Default**: `3000`



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

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

Port to listen for SSH

- **Type**: `int`
- **Required**: No
- **Default**: `222`



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

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

Name of the user in the database

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



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

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

Password of the user in the database

- **Type**: `str`
- **Required**: Yes



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

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

Name of the database

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



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

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

Configure the mailer to send e-mail notifications

Define a `enabled` key with a boolean to enable the mailer

Define a `from` key with the source e-mail address

See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/)

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



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

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

Configure service settings

See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service)

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



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

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

Configure iptables rules

- **Type**: `bool`
- **Required**: No
- **Default**: `false`



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

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

List of IP ranges to allow when `forgejo_manage_iptables` is enabled

- **Type**: `list`
- **Required**: No



### `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_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`<a id="variable-forgejo_runners"></a>

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

List 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 forgejo.yml playbook:

```yaml
- hosts: forgejo
  roles:
    - jriou.forgejo
```

Then run the playbook:

```
ansible-playbook forgejo.yml
```

## Runners

Example of runners configuration:

```yaml
- hosts: forgejo
  roles:
    - jriou.forgejo
  vars:
    forgejo_runners:
      coller:
        token: **redacted**
        labels:
          debian12: docker://data.forgejo.org/oci/debian:bookworm
          debian13: docker://data.forgejo.org/oci/debian:trixie
      ansible:
        token: **redacted**
        labels:
          docker: docker://data.forgejo.org/oci/node:latest
```


## Donate

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