# Role: Gitea Server
Sets up and deploys Gitea server and Act Runner. 
It is recommended that only one server have this role. This prevents issues with multiple sources of truth.

## Tags
- core
- gitea

## Required Variables
Below is an annotated breakdown of the required variables and their structure for this role

These blocks should be defined in the `host_vars` file for the host you wish to be the designated gitea server

> [!WARNING]
> Any variable marked `# !SENSITIVE` **should not** be stored in plain text under any circumstance

### Gitea Info
Defines settings for the Gitea container to be deployed

```yaml
# (required) List of all Gitea containers to be deployed
# in theory you can run multiple containers, however it is highly recommend to only run one
# at least one service is required
gitea_services:

    # (required) name of the container in podman, and service name in systemd
    # This is unique to both podman and systemd
    # format: snake_case
  - name:

    # (required) URL of container image
    # can be from any container registry
    # format: url
    image:

    # (optional) name of container owner
    # best practice is to use the name of the user running this container
    # default: "jdelpilar"
    # format: string
    container_owner:

    # --- Traefik Labels --- #
    # (optional) subdomain for the WebUI of the container
    # This is used to build the FQDN that traefik will use
    # default: name value defined above
    # format: snake_case
    subdomain:

    # (optional) domain used in FQDN
    # default: "delpilar.net"
    # format: URL (domain only)
    domain:

    # (optional) Port of the WebUI as defined by the container
    # Please check the documentation of the specific container used to find this value
    # default: 80
    # format: int
    port: 3000

    # (optional) list of volume mounts to be used by the container
    # it is highly recommended to use volume mounts for Gitea containers to persist configs
    # format example is listed below
    # default: []
    # format: /local/path/:/container/path
    volumes:
      - /local/path:/container/path
```
### Act Runner Info
Defines settings for the Act Runner container to be deployed

```yaml

# (required) List of all Act Runner containers to be deployed
# defining multiple runners may result in better concurrency
# however for most users, one runner will be enough
# at least one service is required
runner_services:

    # (required) name of the container in podman, and service name in systemd
    # This is unique to both podman and systemd
    # format: snake_case
  - name:

    # (required) URL of container image
    # can be from any container registry
    # format: url
    image:


    # (optional) name of container owner
    # best practice is to use the name of the user running this container
    # default: "jdelpilar"
    # format: string
    container_owner:

    # (required) URL of the gitea instance
    # should match the URL generated by the subdomain and domain variables for the gitea service
    # format: URL
    gitea_url:

    # (required) Unique token for the runner. Authenticates the runner to gitea
    # Must be generated via the gitea instance. Any value can be used to allow this role to set up gitea
    # format: string
    # !SENSITIVE
    runner_token:
```


## Templates

### gitea_quadlet.j2
This template is used to generate .container files for Gitea services. This template includes a section for traefik labels.

### act_runner_quadlet.j2
This template is used to generate .container files for act_runner services. 

## Execution
> [!CAUTION]
> This role targets and can potentially restart core services. As such it is recommended to only run this role when 100% necessary 

To run this command without running all roles in the playbook, use the following command
```bash
ansible-playbook site.yaml --tags "gitea"
```