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).
## Choosing between Gitea's built-in SSH and host SSH Server
Gitea has a built-in SSH server which is running on port 2222 (to not conflict with the host SSH server which usually running on port 22).
This one is used by default in this role and results in a SSH clone URL of `gitea@<fqdn>:2222:<user>/<repo>.git` because `gitea` is the default `RUN_AS` user.
Often enough, one wants to have a "clean" SSH URL like `git@<fqdn>:<user>/<repo>.git`.
This is possible by using the host SSH server with the following variable configuration:
```yaml
gitea_ssh_port: 22 # assuming the host SSH server is running on port 22
gitea_user: git # otherwise there will be permission issues
gitea_start_ssh: false # to not start the built-in SSH server
```
The above configuration works out of the box for new installations.
When migrating from a running instance with existing SSH keys from the built-in SSH server to the host SSH server, you need to make sure that the host SSH server is running and that the `gitea_user` has the necessary permissions to access the repository data and the keys (stored in `<gitea_home>/.ssh/`).
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.com/administration/config-cheat-sheet).
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).
It is advisable to define exactly which Forgejo release you want to install. See [Forgejo releases](https://forgejo.org/releases/) for the correct value to use in `gitea_version` eg `v1.21.5`.
This is because the Forgejo project maintains both `stable` and `old stable` releases and the `latest` tag will refer to the _most recent release_ regardless of whether it is `stable` or `old stable`. This can lead to a situation where `latest` refers to an _older release_ than the version you have installed.
| `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_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_max_size` | `4` | Max size of each file in megabytes. |
| `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. |
| `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.com/administration/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_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_autowatch_on_change` | `true` | Enable this to make users watch a repository after their first commit to it (true/false) |
| `gitea_register_manual_confirm` | `false` | Enable this to manually confirm new registrations. Requires REGISTER_EMAIL_CONFIRM to be disabled. |
| `gitea_default_allow_create_organization` | `false` | Allow new users to create organizations by default (true/false) |
| `gitea_email_domain_allowlist` | | If non-empty, comma separated list of domain names that can only be used to register on this instance, wildcard is supported. |
| `gitea_default_user_visibility` | `public` | Set default visibility mode for users, either "public", "limited" or "private". |
| `gitea_default_org_visibility` | `public` | Set default visibility mode for organisations, either "public", "limited" or "private". |
| `gitea_allow_only_internal_registration` | `false` | Set to true to force registration only via Gitea. |
| `gitea_allow_only_external_registration` | `false` | Set to true to force registration only using third-party services. |
| `gitea_show_milestones_dashboard_page` | `true` | Enable this to show the milestones dashboard page - a view of all the user's milestones |
| `gitea_default_user_is_restricted` | `false` | Give new users restricted permissions by default (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. |
| `attachment_enabled` | `true` | Whether issue and pull request attachments are enabled. |
| `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_attachment_extra_config` | | you can use this variable to pass additional config parameters in the `[attachment]` section of the config. |
| `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_extra_config` | | Additional gitea configuration. Have a look at the [config-cheat-sheet](https://docs.gitea.com/administration/config-cheat-sheet) before using it! |
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/).
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"`)_.
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.
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.
