# Ansible role gitea-docker

This Ansible role automates the deployment of Gitea - a self-hosted Git service, using Docker Compose. It provides a comprehensive setup with support for runners, backups, fail2ban integration, and extensive configuration options.

## Features
- **Docker-based deployment** - Runs Gitea in a rootless container for enhanced security
- **Complete security configuration** -  Password policies, 2FA, fail2ban integration, etc.
- **Built-in backup and restore** - Includes tasks for creating backups and restoring from backups
- **Gitea Actions support** - Supports creating multiple runners running in rootless containers using DinD (Docker-in-Docker)
- **Extensible** - Extra config variables for any Gitea setting not explicitly defined


## Requirements

- jmespath Python library (install with: `pip install jmespath`)

## Sample Usage in a Playbook
The following playbook was tested on the latest Debian 12, it should work on Ubuntu as well.

```yaml
# Installs Docker and Compose if not available
- name: Install Gitea using Docker Compose
  hosts: git.example.com
  become: yes
  roles:
    - role: gitea_docker
  vars:
    # The default vars assume you are running a reverse proxy that handles HTTPS
    gitea_fqdn: 'git.example.com'
    gitea_root_url: 'https://git.example.com'
    gitea_protocol: http
    gitea_http_listen: '0.0.0.0'
```

## Backup and Restore
The backup system currently backs up all the data mounts and creates a compressed archive. The archive is stored on the remote machine at the directory given by `gitea_root_backup_dir`. The Ansible controller then downloads the archive and stores it at `gitea_local_backup_dir`.

> ![NOTE]
> The backup task stops the Compose stack to avoid data corruption. There will be a short downtime.

### Creating a Backup
To trigger a backup:
```yaml
---
- name: Create Gitea backup
  hosts: git.example.com
  become: yes
  tasks:
    - name: Include gitea backup tasks
      include_role:
        name: gitea_docker
        tasks_from: backup
  vars:
    gitea_root_backup_dir: '/opt/gitea/backups'
    gitea_local_backup_dir: '~/backups/gitea'
```

> [!NOTE]
> Currently backups only work with Gitea using `sqlite3`. `PostgresSQL` and `MySQL/MariaDB` are planned for a future release.

### Restoring from Backup
To restore from a backup, set the `gitea_restore_backup` variable to `true`. The tasks will use the latest backup in your backups directory on the Ansible controller. You may also specify a backup file to use with `gitea_backup_file`.

> [!WARNING]
> Restore operations will **completely replace** all existing Gitea data

```yaml
---
- name: Restore Gitea from backup
  hosts: git.example.com
  become: yes
  roles:
    - role: gitea_docker
  vars:
    # Your defined variables
    # ...

    gitea_restore_backup: true
    gitea_backup_file: '~/gitea-backups/gitea-backup-20240115-020000.tar.gz'  # Optional
```

# Variables

## Container Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_home_path` | `/opt/gitea` | Base directory on the host where Gitea configuration, data, and logs are stored |
| `gitea_container_tag` | `latest-rootless` | Docker image tag for the Gitea container (e.g., `latest-rootless`, `1.21.5-rootless`) |
| `gitea_data_mount` | `./data` | Relative path for mounting Gitea data directory (relative to `gitea_home_path`) |
| `gitea_config_mount` | `./config` | Relative path for mounting Gitea configuration directory (relative to `gitea_home_path`) |
| `gitea_log_mount` | `./log` | Relative path for mounting Gitea log directory (relative to `gitea_home_path`) |
| `gitea_web_port` | `3000` | Host port that maps to Gitea's web interface |
| `gitea_ssh_port` | `2222` | Host port that maps to Gitea's SSH server |
| `gitea_mounted_log_path` | `/opt/gitea/log/gitea.log` | Full path to the Gitea log file on the host (used for fail2ban integration) |

## Initial User Setup

| Variable Name | Option | Description |
|---------------|---------------|-------------|
| `gitea_users` | `[]` | List of user objects to create or remove in Gitea |
| | `username` | Login username for the Gitea user |
| | `email` | Email address for the Gitea user |
| | `password` | Password for the user (should be encrypted with Ansible Vault) |
| | `must_change_password` | If `true`, user must change password on first login |
| | `admin` | If `true`, user is created with administrator privileges |
| | `state` | Set to `present` to create user or `absent` to delete user |

## Backup and Restore

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_root_backup_dir` | `/opt/gitea/backups` | Directory on the remote host where Gitea backups are stored |
| `gitea_local_backup_dir` | `~/backups/gitea` | Directory on the Ansible controller where backups are downloaded for safekeeping |
| `gitea_restore_backup` | `false` | If `true`, restores Gitea from a backup (WARNING: clears any existing data) |
| `gitea_backup_file` | | Path to specific backup archive file to restore from; if empty, uses the most recent backup in `gitea_local_backup_dir` |

## Runners Configuration

| Variable Name | Option | Description |
|---------------|---------------|-------------|
| `gitea_runner_global_registration_token` | | Global registration token that applies to all runners (can be found in Gitea admin settings) |
| `gitea_runners` | `{}` | Dictionary of Gitea Actions runner configurations |
| | `name` | Unique name identifier for the runner |
| | `data_mount` | Path on host for persistent runner data storage |
| | `config_file_mount` | Path on host for runner configuration files |
| | `cache_enabled` | If `true`, enables action cache functionality (for `actions/cache` support) |
| | `cache_port` | Port number on the host for accessing the runner's cache service (must be unique per runner) |
| | `registration_token` | Runner-specific registration token (optional if `gitea_runner_global_registration_token` is set) |

## Fail2Ban Security

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_fail2ban_enabled` | `false` | Enable fail2ban protection to automatically ban IPs after failed login attempts |
| `gitea_fail2ban_jail_maxretry` | `10` | Number of failed login attempts before an IP is banned |
| `gitea_fail2ban_jail_findtime` | `3600` | Time window in seconds during which failed attempts are counted |
| `gitea_fail2ban_jail_bantime` | `900` | Duration in seconds that an IP remains banned |
| `gitea_fail2ban_jail_action` | `iptables-allports[chain="FORWARD"]` | Fail2ban action/rule to execute when banning an IP |

## Overall Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_app_name` | `Gitea` | Application name displayed throughout the Gitea interface |
| `gitea_user` | `gitea` | System username that runs the Gitea process inside the container |
| `gitea_run_mode` | `prod` | Application run mode: `prod` (production), `dev` (development), or `test` |
| `gitea_fqdn` | `localhost` | Fully qualified domain name for accessing the Gitea instance |

## Server Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_protocol` | `http` | Protocol for the root URL: `http` or `https` |
| `gitea_http_domain` | `{{ gitea_fqdn }}` | Domain name used in HTTP headers and clone URLs |
| `gitea_root_url` | `{{ gitea_protocol }}://{{ gitea_fqdn }}` | Full public URL where Gitea is accessible |
| `gitea_http_listen` | `127.0.0.1` | IP address the HTTP server binds to; use `0.0.0.0` to allow external access |
| `gitea_internal_http_port` | `3000` | Port number Gitea listens on inside the container |
| `gitea_internal_ssh_port` | `2222` | Port number SSH server listens on inside the container |
| `gitea_ssh_listen` | `0.0.0.0` | IP address the SSH server binds to |
| `gitea_ssh_domain` | `{{ gitea_http_domain }}` | Domain name shown in SSH clone URLs |
| `gitea_start_ssh` | `true` | Enable or disable the built-in SSH server |
| `gitea_landing_page` | `home` | Default page for non-authenticated users: `home`, `explore`, `organizations`, or `login` |
| `gitea_server_extra_config` | `{}` | Dictionary of additional server configuration options not covered above |

## Security Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_secret_key` | | Secret key used for encrypting cookies and tokens (generate with `gitea generate secret SECRET_KEY`) |
| `gitea_internal_token` | | Token used for internal API authentication (generate with `gitea generate secret INTERNAL_TOKEN`) |
| `gitea_install_lock` | `false` | If `true`, prevents the installation wizard from running |
| `gitea_disable_git_hooks` | `true` | If `true`, disables custom Git hooks for security |
| `gitea_disable_webhooks` | `false` | If `true`, disables all webhook functionality |
| `gitea_reverse_proxy_limit` | `1` | Number of reverse proxy hops to trust for obtaining the real client IP |
| `gitea_reverse_proxy_trusted_proxies` | `127.0.0.0/8,::1/128` | Comma-separated list of trusted proxy IP addresses or CIDR ranges |
| `gitea_password_complexity` | `off` | Password requirements: `off`, or comma-separated list of `lower`, `upper`, `digit`, `spec` |
| `gitea_password_min_length` | `8` | Minimum number of characters required for passwords |
| `gitea_password_check_pwn` | `false` | If `true`, checks passwords against the HaveIBeenPwned breach database |
| `gitea_2fa` | | Two-factor authentication setting; set to `enforced` to require 2FA for all users |
| `gitea_login_remember_days` | `31` | Number of days to keep users logged in when they select "Remember Me" |
| `gitea_cookie_remember_name` | `gitea_incredible` | Name of the cookie used for "Remember Me" functionality |
| `gitea_security_extra_config` | `{}` | Dictionary of additional security configuration options |

## Service Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_disable_registration` | `false` | If `true`, disables new user registration entirely |
| `gitea_register_email_confirm` | `false` | If `true`, requires email verification to complete registration |
| `gitea_register_manual_confirm` | `false` | If `true`, requires admin approval for new registrations |
| `gitea_require_signin_view` | `false` | If `true`, requires users to sign in to view any content |
| `gitea_enable_notify_mail` | `false` | If `true`, enables email notifications for events |
| `gitea_enable_captcha` | `false` | If `true`, shows CAPTCHA on registration form |
| `gitea_captcha_type` | `image` | Type of CAPTCHA to use: `image`, `recaptcha`, `hcaptcha`, or `mcaptcha` |
| `gitea_show_registration_button` | `true` | If `true`, displays registration button on login page |
| `gitea_default_keep_email_private` | `false` | If `true`, new users have email privacy enabled by default |
| `gitea_default_allow_create_organization` | `true` | If `true`, new users can create organizations |
| `gitea_default_user_is_restricted` | `false` | If `true`, new users are created with restricted permissions |
| `gitea_default_user_visibility` | `public` | Default visibility for new user profiles: `public`, `limited`, or `private` |
| `gitea_default_org_visibility` | `public` | Default visibility for new organizations: `public`, `limited`, or `private` |
| `gitea_default_org_member_visible` | `false` | If `true`, organization members are visible by default |
| `gitea_allow_only_internal_registration` | `false` | If `true`, only allows registration via internal authentication |
| `gitea_allow_only_external_registration` | `false` | If `true`, only allows registration via external authentication sources |
| `gitea_email_domain_allowlist` | | Comma-separated list of allowed email domains for registration |
| `gitea_email_domain_blocklist` | | Comma-separated list of blocked email domains for registration |
| `gitea_no_reply_address` | | No-reply email address used for system-generated emails |
| `gitea_enable_user_heatmap` | `true` | If `true`, displays user activity heatmap on profiles |
| `gitea_enable_timetracking` | `true` | If `true`, enables time tracking features for issues |
| `gitea_auto_watch_new_repos` | `true` | If `true`, users automatically watch repositories they create |
| `gitea_auto_watch_on_changes` | `false` | If `true`, users automatically watch repositories they contribute to |
| `gitea_show_milestones_dashboard_page` | `true` | If `true`, shows milestones on the dashboard page |
| `gitea_service_extra_config` | `{}` | Dictionary of additional service configuration options |

## Repository Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_repo_force_private` | `false` | If `true`, forces all new repositories to be private |
| `gitea_repo_default_private` | `last` | Default visibility for new repositories: `public`, `private`, or `last` (uses last selection) |
| `gitea_repo_default_push_create_private` | `true` | If `true`, repositories created via push are private by default |
| `gitea_repo_preferred_licenses` | `Apache License 2.0,MIT License` | Comma-separated list of license names to show at the top when creating repositories |
| `gitea_repo_disable_http_git` | `false` | If `true`, disables HTTP(S) Git operations (clone, push, pull) |
| `gitea_repo_disable_migrations` | `false` | If `true`, disables repository migration feature |
| `gitea_repo_disable_stars` | `false` | If `true`, disables the ability to star repositories |
| `gitea_repo_default_branch` | `main` | Default branch name for new repositories |
| `gitea_repository_extra_config` | `{}` | Dictionary of additional repository configuration options |

## CORS Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_cors_enabled` | `false` | Enable Cross-Origin Resource Sharing (CORS) headers |
| `gitea_cors_allowed_domains` | `*` | Domains allowed to make cross-origin requests; `*` allows all |
| `gitea_cors_allowed_methods` | `GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS` | HTTP methods allowed for cross-origin requests |
| `gitea_cors_max_age` | `10m` | Duration to cache preflight CORS request results |
| `gitea_cors_allowed_credentials` | `false` | If `true`, allows credentials (cookies, auth headers) in cross-origin requests |
| `gitea_cors_headers` | `Content-Type,User-Agent` | Custom headers allowed in cross-origin requests |
| `gitea_cors_x_frame_options` | `SAMEORIGIN` | X-Frame-Options header value: `SAMEORIGIN`, `DENY`, or `ALLOW-FROM uri` |

## UI Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_ui_default_theme` | `gitea-auto` | Default theme for the UI; `gitea-auto` switches based on system preference |
| `gitea_ui_themes` | | Comma-separated list of themes to make available; if empty, all themes are available |
| `gitea_ui_show_user_email` | `true` | If `true`, displays user email addresses in the UI (respects privacy settings) |
| `gitea_ui_show_full_name` | `false` | If `true`, displays full names instead of usernames where applicable |
| `gitea_ui_extra_config` | `{}` | Dictionary of additional UI configuration options |

## UI Meta Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_ui_meta_author` | `Gitea - Git with a cup of tea` | Content for the HTML meta author tag |
| `gitea_ui_meta_description` | `Gitea (Git with a cup of tea) is a painless self-hosted Git service written in Go` | Content for the HTML meta description tag (used by search engines) |
| `gitea_ui_meta_keywords` | `go,git,self-hosted,gitea` | Comma-separated keywords for the HTML meta keywords tag |

## Indexer Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_issue_indexer_type` | `bleve` | Issue search indexer engine: `bleve` (built-in), `db` (database), `elasticsearch`, or `meilisearch` |
| `gitea_issue_indexer_connection_string` | | Connection string for external indexer (required for `elasticsearch` or `meilisearch`) |
| `gitea_issue_indexer_name` | `gitea_issues` | Index name used in external indexer services |
| `gitea_issue_indexer_path` | `indexers/issues.bleve` | File path for bleve index storage (relative to Gitea data directory) |
| `gitea_repo_indexer_enabled` | `false` | Enable code search functionality (WARNING: requires significant disk space, ~6x repository size) |
| `gitea_repo_indexer_repo_types` | `sources,forks,mirrors,templates` | Types of repositories to include in code search index |
| `gitea_repo_indexer_type` | `bleve` | Code search indexer engine: `bleve` (built-in) or `elasticsearch` |
| `gitea_repo_indexer_path` | `indexers/repos.bleve` | File path for bleve code index storage (relative to Gitea data directory) |
| `gitea_repo_indexer_connection_string` | | Connection string for elasticsearch code indexer |
| `gitea_repo_indexer_name` | `gitea_codes` | Index name for code search in elasticsearch |
| `gitea_repo_indexer_include` | | Glob patterns for files to include in code search (e.g., `**.txt,**.md`); empty includes all |
| `gitea_repo_indexer_exclude` | | Glob patterns for files to exclude from code search (takes precedence over includes) |
| `gitea_repo_indexer_exclude_vendored` | `true` | If `true`, excludes vendored/third-party code from indexing |
| `gitea_repo_indexer_max_file_size` | `1048576` | Maximum file size in bytes to index (default 1 MiB); larger files are skipped |
| `gitea_indexer_startup_timeout` | `30s` | Maximum time to wait for indexer initialization; `-1` disables timeout |
| `gitea_indexer_extra_config` | `{}` | Dictionary of additional indexer configuration options |

## Packages Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_packages_enabled` | `true` | Enable package registry functionality (for npm, Maven, Docker, etc.) |
| `gitea_packages_extra_config` | `{}` | Dictionary of additional package registry configuration options |

## Actions Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_actions_enabled` | `false` | Enable Gitea Actions (CI/CD pipeline functionality) |
| `gitea_actions_default_actions_url` | `github` | Default URL for Actions marketplace; `github`, `self`, or custom URL |
| `gitea_actions_extra_config` | `{}` | Dictionary of additional Actions configuration options |

## Logging Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_log_root_path` | | Root directory for log files; required if `gitea_log_mode` is `file` or for fail2ban integration |
| `gitea_log_mode` | `console` | Log output destination: `console`, `file`, `conn` (network), or `smtp` (email) |
| `gitea_log_level` | `Info` | Logging verbosity level: `Trace`, `Debug`, `Info`, `Warn`, `Error`, or `Critical` |
| `gitea_enable_ssh_log` | `false` | If `true`, enables detailed logging for SSH operations |
| `gitea_log_extra_config` | `{}` | Dictionary of additional logging configuration options |

## Mailer Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_mailer_enabled` | `false` | Enable email functionality for notifications and registration |
| `gitea_mailer_protocol` | | Mail protocol: `smtp`, `smtps`, `smtp+starttls`, `smtp+unix`, `sendmail`, or `dummy` (logs only) |
| `gitea_mailer_smtp_addr` | | Hostname or IP address of the SMTP server |
| `gitea_mailer_smtp_port` | | Port number for the SMTP server (typically 25, 465, or 587) |
| `gitea_mailer_user` | | Username for SMTP authentication |
| `gitea_mailer_password` | | Password for SMTP authentication (should be encrypted with Ansible Vault) |
| `gitea_mailer_from` | `noreply@{{ gitea_http_domain }}` | Email address used as the sender for all outgoing emails |
| `gitea_mailer_subject_prefix` | | Text prepended to all email subject lines |
| `gitea_mailer_send_as_plain_text` | `false` | If `true`, sends emails as plain text instead of HTML |
| `gitea_mailer_extra_config` | `{}` | Dictionary of additional mailer configuration options |

## Mirror Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_mirror_enabled` | `true` | Enable repository mirroring functionality |
| `gitea_mirror_disable_new_pull` | `false` | If `true`, prevents creation of new pull mirrors (mirroring from external repos) |
| `gitea_mirror_disable_new_push` | `false` | If `true`, prevents creation of new push mirrors (mirroring to external repos) |
| `gitea_mirror_default_interval` | `8h` | Default synchronization interval for new mirrors |
| `gitea_mirror_min_interval` | `10m` | Minimum allowed interval between mirror synchronizations |
| `gitea_mirror_extra_config` | `{}` | Dictionary of additional mirror configuration options |

## Metrics Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_metrics_enabled` | `false` | Enable Prometheus metrics endpoint at `/metrics` |
| `gitea_metrics_token` | | Authentication token required to access the metrics endpoint |
| `gitea_metrics_extra_config` | `{}` | Dictionary of additional metrics configuration options |

## API Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_api_enable_swagger` | `true` | Enable Swagger UI for API documentation at `/api/swagger` |
| `gitea_api_max_response_items` | `50` | Maximum number of items returned in a single API response page |
| `gitea_api_default_paging_num` | `30` | Default number of items per page for API responses |
| `gitea_api_extra_config` | `{}` | Dictionary of additional API configuration options |

## OAuth2 Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_oauth2_enabled` | `true` | Enable OAuth2 provider functionality (allows other apps to use Gitea for authentication) |
| `gitea_oauth2_access_token_expiration_time` | `3600` | OAuth2 access token lifetime in seconds (default 1 hour) |
| `gitea_oauth2_refresh_token_expiration_time` | `730` | OAuth2 refresh token lifetime in hours (default ~30 days) |
| `gitea_oauth2_jwt_signing_algorithm` | `RS256` | Algorithm used to sign JWT tokens: `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, or `ES512` |
| `gitea_oauth2_jwt_secret` | | Secret key for signing JWT tokens (auto-generated if not provided) |
| `gitea_oauth2_extra_config` | `{}` | Dictionary of additional OAuth2 configuration options |

## Other Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_show_footer_version` | `true` | If `true`, displays Gitea version number in the page footer |
| `gitea_show_footer_template_load_time` | `true` | If `true`, displays page generation time in the footer |
| `gitea_enable_sitemap` | `true` | If `true`, generates XML sitemap at `/sitemap.xml` for search engines |
| `gitea_enable_feed` | `true` | If `true`, enables RSS and Atom feeds for repositories and users |
| `gitea_other_extra_config` | `{}` | Dictionary of additional miscellaneous configuration options |

## Additional Configuration

> [!NOTE]
> Not all variables that Gitea supports have been implemented yet. Read the following secion to add additional configuration options.

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `gitea_extra_config` | `{}` | Dictionary of any additional environment variables to pass to Gitea; consult the [Gitea configuration cheat sheet](https://docs.gitea.com/administration/config-cheat-sheet) for available options |

### Example: Using `gitea_extra_config`

```yaml
gitea_extra_config:
  GITEA__webhook__ALLOWED_HOST_LIST: "external"
  GITEA__webhook__SKIP_TLS_VERIFY: "false"
  GITEA__cron__ENABLED: "true"
```

## Understanding Extra Configuration Variables

Many configuration sections include an `*_extra_config` variable (e.g., `gitea_server_extra_config`, `gitea_security_extra_config`, etc.). These variables allow you to add additional Gitea configuration options that aren't explicitly defined as separate variables in this role.

### How Extra Config Variables Work

Each `*_extra_config` variable is a dictionary that gets merged into the corresponding section of the Gitea configuration. The role converts these dictionaries into the appropriate environment variable format that Gitea expects.

### Naming Convention

Gitea uses environment variables with a specific naming pattern:
```
GITEA__<section>__<key>
```

When you use an `*_extra_config` variable, the role automatically handles the section name for you. You only need to provide the key-value pairs.

### Available Extra Config Variables

| Variable | Maps to Gitea Section |
|----------|----------------------|
| `gitea_server_extra_config` | `[server]` |
| `gitea_security_extra_config` | `[security]` |
| `gitea_service_extra_config` | `[service]` |
| `gitea_repository_extra_config` | `[repository]` |
| `gitea_ui_extra_config` | `[ui]` |
| `gitea_indexer_extra_config` | `[indexer]` |
| `gitea_packages_extra_config` | `[packages]` |
| `gitea_actions_extra_config` | `[actions]` |
| `gitea_log_extra_config` | `[log]` |
| `gitea_mailer_extra_config` | `[mailer]` |
| `gitea_mirror_extra_config` | `[mirror]` |
| `gitea_metrics_extra_config` | `[metrics]` |
| `gitea_api_extra_config` | `[api]` |
| `gitea_oauth2_extra_config` | `[oauth2]` |
| `gitea_other_extra_config` | `[other]` |

### Examples

#### Adding Server Configuration

```yaml
gitea_server_extra_config:
  OFFLINE_MODE: true
  DISABLE_ROUTER_LOG: false
  ENABLE_GZIP: true
```

This translates to these environment variables:
```
GITEA__server__OFFLINE_MODE=true
GITEA__server__DISABLE_ROUTER_LOG=false
GITEA__server__ENABLE_GZIP=true
```

#### Using gitea_extra_config for Any Section

If you need to configure a section that doesn't have a dedicated `*_extra_config` variable, or want to set options across multiple sections, use `gitea_extra_config`:

```yaml
gitea_extra_config:
  # Webhook configuration
  GITEA__webhook__ALLOWED_HOST_LIST: "external"
  GITEA__webhook__SKIP_TLS_VERIFY: "false"
  
  # Cron configuration
  GITEA__cron__ENABLED: "true"
  GITEA__cron_DOT_update_checker__ENABLED: "false"
  
  # Git configuration
  GITEA__git__DISABLE_DIFF_HIGHLIGHT: "false"
  GITEA__git__timeout__DEFAULT: "360"
```

### Finding Available Options

For a complete list of available configuration options, refer to the official [Gitea Configuration Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet).

### Important Notes

1. **Values**: All values in `*_extra_config` dictionaries should be strings, numbers, or booleans.

2. **Priority**: Variables defined in `*_extra_config` can override the explicitly defined role variables if they conflict.

3. **Validation**: The role does not validate extra configuration options. Ensure you're using valid Gitea configuration keys by consulting the official documentation.

# License
MIT License