This role installs and manages [gitea](https://gitea.io) or [forgejo](https://forgejo.org). A painless self-hosted Git service. Gitea is a community managed lightweight code hosting solution written in Go. Forgejo is a fork of it.
This role is also Part of the Ansible-Collection [l3d.git](https://galaxy.ansible.com/l3d/git). [](https://github.com/roles-ansible/ansible_collection_git.git).
## Sample Usage in a playbook
The following code has been tested with the latest Debian Stable, it should work on Ubuntu and RedHat as well.
```yaml
# ansible-galaxy install l3d.gitea
- name: "Install gitea"
hosts: git.example.com
roles:
- {role: l3d.gitea, tags: gitea}
vars:
#Here we assume we are behind a reverse proxy that will
# handle https for us, so we bind on localhost:3000 using HTTP
# see https://docs.gitea.io/en-us/reverse-proxies/#nginx
gitea_fqdn: 'git.example.com'
gitea_root_url: 'https://git.example.com'
gitea_protocol: http
gitea_start_ssh: true
```
Variables
-----------
Here is a deeper insight into the variables of this gitea role. For the exact function of some variables and the possibility to add more options we recommend a look at this [config cheat sheet](https://docs.gitea.io/en-us/config-cheat-sheet/).
### Chose between gitea and forgejo
There is a fork of gitea called forgejo. Why? Read the [forgejo FAQ](https://forgejo.org/faq/).
You have the option to choose between [gitea](https://gitea.io) and [forgejo](https://forgejo.org) by modifying the ``gitea_fork`` variable.
| variable name | default value | description |
| ------------- | ------------- | ----------- |
| `gitea_fork` | `gitea` | optional choose to install forgejo instead of gitea by setting this value to `forgejo`. |
### gitea update mechanism
To determine which gitea version to install, you can choose between two variants.
Either you define exactly which release you install. Or you use the option ``latest`` to always install the latest release from the [gitea releases](https://github.com/go-gitea/gitea/releases/latest).
### gitea update
| variable name | default value | description |
| ------------- | ------------- | ----------- |
| `gitea_version` | `latest` | Define either the exact release to install *(eg. `1.16.0`)* or use ``latest`` *(default)* to install the latest release. |
| `gitea_version_check` | `true` | Check if installed version != `gitea_version` before initiating binary download |
| `gitea_gpg_key` | `7C9E68152594688862D62AF62D9AE806EC1592E2` | the gpg key the gitea binary is signed with |
| `gitea_forgejo_gpg_key` | `EB114F5E6C0DC2BCDD183550A4B61A2DC5923710` | the gpg key the forgejo binary is signed with |
| `gitea_gpg_server` | `hkps://keys.openpgp.org` | A gpg key server where this role can download the gpg key |
| `gitea_backup_on_upgrade` | `false` | Optionally a backup can be created with every update of gitea. |
| `gitea_backup_location` | `{{ gitea_home }}/backups/` | Where to store the gitea backup if one is created with this role. |
| `submodules_versioncheck` | `false` | a simple version check that can prevent you from accidentally running an older version of this role. *(recomended)* |
### gitea in the linux world
| variable name | default value | description |
| ------------- | ------------- | ----------- |
| `gitea_group` | `gitea` | Primary UNIX group used by Gitea |
| `gitea_groups` | null | Optionally a list of secondary UNIX groups used by Gitea |
| `gitea_home` | `/var/lib/gitea` | Base directory to work |
| `gitea_user_home` | `{{ gitea_home }}` | home of gitea user |
| `gitea_executable_path` | `/usr/local/bin/gitea` | Path for gitea executable |
| `gitea_forgejo_executable_path` | `/usr/local/bin/forgejo` | Path for forgejo executable |
| `gitea_configuraion_path` | `/etc/gitea` | Where to put the gitea.ini config |
| `gitea_shell` | `/bin/false` | UNIX shell used by gitea. Set it to `/bin/bash` if you don't use the gitea built-in ssh server. |
| `gitea_systemd_cap_net_bind_service` | `false` | Adds `AmbientCapabilities=CAP_NET_BIND_SERVICE` to systemd service file |
| `gitea_app_name` | `Gitea` | Displayed application name |
| `gitea_user` | `gitea ` | UNIX user used by Gitea |
| `gitea_run_mode`| `prod`| Application run mode, affects performance and debugging. Either “dev”, “prod” or “test”. |
| `gitea_fqdn` | `localhost` | Base FQDN for the installation, used as default for other variables. Set it to the FQDN where you can reach your gitea server |
| `gitea_repository_upload_extra_config` | | you can use this variable to pass additional config parameters in the `[repository.upload]` section of the config. |
| `gitea_enable_repo_signing_extra` | | you can use this variable to pass additional config parameters in the `[repository.signing]` section of the config. |
### CORS ([cors](https://docs.gitea.io/en-us/config-cheat-sheet/#cors-cors))
| variable name | default value | description |
| ------------- | ------------- | ----------- |
| `gitea_enable_cors` | `false` | enable cors headers (disabled by default) |
| `gitea_cors_scheme` | `http` | scheme of allowed requests |
| `gitea_cors_allow_domain` | `*` | list of requesting domains that are allowed |
| `gitea_cors_allow_subdomain` | `false` |allow subdomains of headers listed above to request |
| `gitea_cors_methods` | *(see defaults)* | list of methods allowed to request |
| `gitea_cors_max_age` | `10m` | max time to cache response |
| `gitea_cors_allow_credentials` | `false` | allow request with credentials |
| `gitea_cors_headers` | `Content-Type,User-Agent` | additional headers that are permitted in requests |
| `gitea_cors_x_frame_options` | `SAMEORIGIN` | Set the `X-Frame-Options` header value. |
| `gitea_cors_extra` | | you can use this variable to pass additional config parameters in the `[cors]` section of the config. |
| `gitea_lfs_server_enabled` | `false` | Enable GIT-LFS Support *(git large file storage: [git-lfs](https://git-lfs.github.com/))*. |
| `gitea_lfs_jwt_secret` | | LFS authentication secret. Can be generated with ``gitea generate secret JWT_SECRET``. Will be autogenerated if not defined |
| `gitea_redirect_other_port` | `false` | If true and `gitea_protocol` is https, allows redirecting http requests on `gitea_port_to_redirect` to the https port Gitea listens on. |
| `gitea_port_to_redirect` | `80` | Port for the http redirection service to listen on, if enabled |
| `gitea_enable_tls_certs` | `false` | Write TLS Cert and Key Path to config file |
| `gitea_tls_cert_file` | `https/cert.pem` | Cert file path used for HTTPS. |
| `gitea_tls_key_file` | `https/key.pem` | Key file path used for HTTPS. |
| `gitea_enable_acme` | `false` | Flag to enable automatic certificate management via an ACME capable CA Server. *(default is letsencrypt)* |
| `gitea_acme_url` | | The CA’s ACME directory URL |
| `gitea_acme_accepttos` | `false` | This is an explicit check that you accept the terms of service of the ACME provider. |
| `gitea_acme_directory` | `https` | Directory that the certificate manager will use to cache information such as certs and private keys. |
| `gitea_acme_email` | | Email used for the ACME registration |
| `gitea_acme_ca_root` | | The CA’s root certificate. If left empty, it defaults to using the system’s trust chain. |
| `gitea_server_extra_config` | | you can use this variable to pass additional config parameters in the `[server]` section of the config. |
| `gitea_db_ssl` | `disable` | Configure SSL only if your database type supports it. Have a look into the [config-cheat-sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#database-database) for more detailed information |
| `gitea_db_path` | `{{ gitea_home }}/data/gitea.db` | DB path, if you use `sqlite3`. |
| `gitea_db_log_sql` | `false` | Log the executed SQL. |
| `gitea_database_extra_config` | | you can use this variable to pass additional config parameters in the `[database]` section of the config. |
| `gitea_repo_indexer_max_file_size` | `1048576` | Maximum size in bytes of files to be indexed. |
| `gitea_indexer_extra_config` | | you can use this variable to pass additional config parameters in the `[indexer]` section of the config. |
| `gitea_queue_issue_indexer_extra_config` | | | you can use this variable to pass additional config parameters in the `[queue.issue_indexer]` section of the config. |
| `gitea_secret_key` | | Global secret key. Will be autogenerated if not defined. Should be unique. |
| `gitea_disable_git_hooks` | `true` | Set to false to enable users with git hook privilege to create custom git hooks. Can be dangerous. |
| `gitea_disable_webhooks` | `false` | Set to true to disable webhooks feature. |
| `gitea_internal_token` | | Internal API token. Will be autogenerated if not defined. Should be unique. |
| `gitea_password_check_pwn` | `false` | Check [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) to see if a password has been exposed. |
| `gitea_security_extra_config` | | you can use this variable to pass additional config parameters in the `[security]` section of the config. |
### Service ([service](https://docs.gitea.io/en-us/config-cheat-sheet/#service-service))
| variable name | default value | description |
| ------------- | ------------- | ----------- |
| `gitea_disable_registration` | `false` | Do you want to disable user registration? (true/false) |
| `gitea_register_email_confirm` | `false` | Enable this to ask for mail confirmation of registration. Requires `gitea_mailer_enabled` to be enabled. |
| `gitea_require_signin` | `true` | Do you require a signin to see repo's (even public ones)? (true/false)|
| `gitea_default_keep_mail_private` | `true` | By default set users to keep their email address privat |
| `gitea_enable_captcha` | `true` | Do you want to enable captcha's ? (true/false)|
| `gitea_show_registration_button` | `true` | Here you can hide the registration button. This will not disable registration! (true/false)|
| `gitea_only_allow_external_registration` | `false` | Set to true to force registration only using third-party services (true/false) |
| `gitea_enable_notify_mail` | `false` | Enable this to send e-mail to watchers of a repository when something happens, like creating issues (true/false) |
| `gitea_auto_watch_new_repos` | `true` | Enable this to let all organisation users watch new repos when they are created (true/false) |
| `gitea_service_extra_config` | | you can use this variable to pass additional config parameters in the `[service]` section of the config. |
| `gitea_mailer_force_trust_server_cert` | `false` | completely ignores server certificate validation errors. This option is unsafe. Consider adding the certificate to the system trust store instead. |
| `gitea_mailer_user` | | Username of mailing user (usually the sender’s e-mail address). |
| `gitea_mailer_password ` | |Password of mailing user. Use `your password` for quoting if you use special characters in the password. |
| `gitea_attachment_types` | see Docs | Comma-separated list of allowed file extensions (`.zip,.txt`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types. |
| `gitea_attachment_max_size` | `4` | Maximum size (MB). |
| `gitea_actions_enabled` | `false` | Enable/Disable actions capabilities globaly. You may want to add `repo.actions` to `gitea_default_repo_units` to enable actions on all new repositories |
| `gitea_actions_default_actions_url` | `https://gitea.com/` | Default address to get action plugins, e.g. the default value means downloading from `https://gitea.com/actions/checkout` for `uses: actions/checkout@v3` |
| `gitea_actions_extra` | | you can use this variable to pass additional config parameters in the `[actions]` section of the config. |
| `gitea_extra_config` | | Additional gitea configuration. Have a look at the [config-cheat-sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) before using it! |
### Fail2Ban configuration
If enabled, this will deploy a fail2ban filter and jail config for Gitea as described in the [Gitea Documentation](https://docs.gitea.io/en-us/fail2ban-setup/).
As this will only deploy config files, fail2ban already has to be installed or otherwise the role will fail.
| variable name | default value | description |
| ------------- | ------------- | ----------- |
| `gitea_fail2ban_enabled` | `false` | Whether to deploy the fail2ban config or not |
You can optionally customize your gitea using this ansible role. We got our information about customisation from [docs.gitea.io/en-us/customizing-gitea](https://docs.gitea.io/en-us/customizing-gitea/).
To deploy multiple files we created the ``gitea_custom_search`` variable, that can point to the path where you put the custom gitea files *( default ``"files/host_files/{{ inventory_hostname }}/gitea"``)*.
+ **LOGO**:
- Set ``gitea_customize_logo`` to ``true``
- We search for:
* ``logo.svg`` - Used for favicon, site icon, app icon
* ``logo.png`` - Used for Open Graph
* ``favicon.png`` - Used as fallback for browsers that don’t support SVG favicons
* ``apple-touch-icon.png`` - Used on iOS devices for bookmarks
- We search in *(using [first_found](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/first_found_lookup.html))*:
- Create a directory with the files you want to deploy.
- Point ``gitea_customize_files_path`` to this directory. *(Default ``{{ gitea_custom_search }}/gitea_files/``)*
## Requirements
This role uses the ``ansible.builtin`` and ``community.general`` ansible Collections. To download the latest forgejo/gitea release we use json_query. This requires ``jmespath`` to be available.
### Python packages
+ jmespath
### Galaxy Collections
+ community.general
### Example requirements Installation
```
ansible-galaxy install community.general
pip3 install jmespath
```
## Contribute
Don't hesitate to create a pull request, and if in doubt you can reach me at
this ansible role was originally developed on [github.com/thomas-maurice/ansible-role-gitea](https://github.com/thomas-maurice/ansible-role-gitea.git). Since the role there has some problems like default values for the location of the gitea repositories and the merging of pull requests usually takes several months, a fork of the role was created that offers the same. Only tidier and with the claim to react faster to issues and pull requests. It is now Part of the [l3d.git](https://galaxy.ansible.com/l3d/git) Collection too.
