Gitea

Deploys a Gitea instance via Docker Compose with PostgreSQL, optionally routed through Traefik as a reverse proxy.

Requirements

• Docker
• community.docker Ansible collection (>=5.2.0)

Variables

Variable	Default	Description
gitea_instance	gitea	Unique instance name. Used as Compose project name and container name prefix. Change when running multiple instances on the same host.
gitea_version	1.26.1	Gitea image tag. Pin to a specific version in production.
gitea_db_version	14	PostgreSQL major version.
gitea_data_path	/data/gitea	Host path for persistent data (repositories, attachments, database).
gitea_docker_path	/docker/gitea	Host path for the compose.yml file.
gitea_db_user	gitea	PostgreSQL username.
gitea_db_name	gitea	PostgreSQL database name.
gitea_db_password	~	PostgreSQL user password. Required. Generate with openssl rand -hex 32.
gitea_domain	~	Public domain Gitea runs on (no protocol prefix). When set, enables Traefik HTTP routing labels, HTTPS config, and PROXY protocol.
gitea_traefik_ssh_entrypoint	~	When set, adds Traefik TCP router labels for SSH on the named entrypoint (e.g. ssh). Requires gitea_domain.
gitea_web_port	~	When set, exposes the web UI on this host port. Omit when using a reverse proxy.
gitea_ssh_port	~	When set, exposes SSH on this host port and enables Gitea's built-in SSH server.
gitea_uid	1000	UID the Gitea process runs as inside the container.
gitea_gid	1000	GID the Gitea process runs as inside the container.
gitea_app_name	Gitea: Git with a cup of tea	Name shown in the browser title bar and emails.
gitea_run_mode	prod	Run mode. prod or dev.
gitea_default_branch	master	Default branch name for new repositories.
gitea_disable_regular_org_creation	false	When true, prevents non-admin users from creating organizations.
gitea_disable_git_hooks	true	When true, disables git hook execution. Recommended — git hooks allow arbitrary server-side code execution.
gitea_register_email_confirm	false	When true, new accounts must confirm their email before logging in.
gitea_register_manual_confirm	false	When true, new accounts must be approved by an admin before logging in.
gitea_disable_registration	false	When true, disables public self-registration entirely.
gitea_enable_notify_mail	~	When true, enables email notifications. Defaults to true when gitea_mail_conf is set.
gitea_enable_captcha	false	When true, shows a CAPTCHA on the registration page.
gitea_require_captcha_for_login	false	When true, also shows a CAPTCHA on the login page.
gitea_captcha_type	image	CAPTCHA provider. Accepted values: image, recaptcha, hcaptcha, mcaptcha, cfturnstile.
gitea_default_keep_email_private	true	When true, new users' email addresses are hidden by default.
gitea_default_enable_timetracking	false	When true, enables time tracking on repositories by default.
gitea_log_level	warn	Log verbosity. Accepted values: trace, debug, info, warn, error, critical, fatal, none.
gitea_log_mode	file	Log output target.
gitea_cron_enabled	true	When true, enables Gitea's background cron tasks (repo archiving, GC, etc.).
gitea_default_ui_location	Europe/Berlin	Default UI timezone. IANA timezone name.
gitea_federation_enabled	false	When true, enables ActivityPub federation.
gitea_show_footer_powered_by	false	When true, shows "Powered by Gitea" in the footer.
gitea_show_footer_template_load_time	false	When true, shows page render time in the footer.
gitea_show_footer_version	false	When true, shows the Gitea version in the footer.
gitea_mail_conf	~	SMTP mail configuration dict. See Mail.
gitea_uninstall	false	Stops and removes containers and the compose directory.
gitea_purge	false	Also removes the data directory. Requires gitea_uninstall: true. Irreversible.

Usage

Minimal setup with Traefik:

gitea_domain: "git.example.com"
gitea_db_password: "{{ vault_gitea_db_password }}"

With SSH exposed through Traefik:

gitea_domain: "git.example.com"
gitea_traefik_ssh_entrypoint: ssh
gitea_db_password: "{{ vault_gitea_db_password }}"

Without Traefik (direct port exposure):

gitea_web_port: 3000
gitea_ssh_port: 2222
gitea_db_password: "{{ vault_gitea_db_password }}"

With mail and invite-only registration:

gitea_domain: "git.example.com"
gitea_db_password: "{{ vault_gitea_db_password }}"
gitea_disable_registration: true
gitea_mail_conf:
  host: smtp.example.com
  username: apikey
  password: "{{ vault_gitea_smtp_password }}"
  address: gitea@example.com

Multiple instances on the same host:

# instance 1
gitea_instance: gitea_team_a
gitea_domain: git-a.example.com
gitea_data_path: /data/gitea_team_a
gitea_docker_path: /docker/gitea_team_a
gitea_db_password: "{{ vault_gitea_team_a_db_password }}"

# instance 2
gitea_instance: gitea_team_b
gitea_domain: git-b.example.com
gitea_data_path: /data/gitea_team_b
gitea_docker_path: /docker/gitea_team_b
gitea_db_password: "{{ vault_gitea_team_b_db_password }}"

Mail

gitea_mail_conf is a dict. When unset, Gitea cannot send emails (invitations, notifications, password resets).

Key	Required	Default	Description
host	yes	—	SMTP server hostname.
username	yes	—	SMTP username.
password	yes	—	SMTP password.
port	no	465	SMTP port.
ssl	no	true	true for SMTPS (port 465), false for STARTTLS.
address	no	username	FROM address. Defaults to username.

Uninstall

To stop and remove all containers and the compose directory:

gitea_uninstall: true

To also wipe all data including repositories and the database (irreversible):

gitea_uninstall: true
gitea_purge: true

Notes

• gitea_db_password should be stored in Ansible Vault.
• gitea_mail_conf.password should be stored in Ansible Vault.
• Gitea's cron jobs default to disabled upstream; this role enables them by default.
• gitea_disable_git_hooks defaults to true — enabling git hooks allows repository owners to execute arbitrary code on the server.
• When gitea_domain is set, do not also set gitea_web_port — Traefik handles external access.