Skip to main content
Version: 21.5 - latest

Install on Windows

Run Gitea Enterprise as a Windows service by adapting the upstream Gitea Windows instructions.

Prerequisites​

  • Windows Server 2019 or later (desktop versions such as Windows 11 also work for evaluation).
  • Local administrator rights.
  • Git for Windows installed and added to the PATH.
  • nssm (the Non-Sucking Service Manager) to run Gitea as a service.
  • (Optional) An Enterprise license to enable premium features. Use License Activation to request a trial or apply the license after installation.

1. Create the Gitea directories​

  1. Create C:\gitea for program files and C:\gitea-data for repositories and configuration.

  2. In PowerShell, create the directory structure and set permissions so only the service account can access the data directory:

    @('custom','data','log') | ForEach-Object { New-Item -ItemType Directory -Path "C:\gitea-data\$_" -Force | Out-Null }
    icacls C:\gitea-data /inheritance:r
    icacls C:\gitea-data /grant "Users:(OI)(CI)(RX)"
    icacls C:\gitea-data /grant "Administrators:(OI)(CI)(F)"

    Replace Users with a dedicated account if you plan to run the service as a non-admin identity.

2. Download the Enterprise binary​

  1. Pick the Enterprise release you intend to deploy (for example 24.6.0).
  2. Download gitea-ee-<version>-windows-4.0-amd64.exe from commitgo/gitea-ee releases and place it in C:\gitea\gitea.exe.
  3. Optionally copy an existing app.ini to C:\gitea-data\custom\conf\app.ini to reuse your configuration.

3. Configure the database (optional)​

Gitea Enterprise requires MySQL/MariaDB or PostgreSQL. Create the database ahead of time and set the connection string in custom/conf/app.ini.

MySQL / MariaDB​

[database]
DB_TYPE  = mysql
HOST     = db.internal:3306
NAME     = gitea
USER     = gitea
PASSWD   = change-me-now
SSL_MODE = disable

PostgreSQL​

[database]
DB_TYPE  = postgres
HOST     = db.internal:5432
NAME     = gitea
USER     = gitea
PASSWD   = change-me-now
SSL_MODE = disable

Use Windows Credential Manager, Secrets Manager, or your orchestration tool to store passwords securely.

4. Run the setup wizard​

  1. Launch PowerShell as Administrator and start Gitea interactively the first time:

    cd C:\gitea
    .\gitea.exe web --config C:\gitea-data\custom\conf\app.ini

  2. Browse to http://localhost:3000 (or the host address) and complete the setup wizard, pointing the AppDataPath to C:\gitea-data.

  3. Stop the process once the initial configuration is saved.

5. Install Gitea as a Windows service​

  1. Extract nssm.exe to C:\nssm (or any directory in PATH).

  2. Register the service:

    nssm install Gitea "C:\gitea\gitea.exe" "web" "--config" "C:\gitea-data\custom\conf\app.ini"

  3. In the NSSM service editor:

    • Set Startup directory to C:\gitea.
    • Under I/O, redirect Output and Error to C:\gitea-data\log\gitea.log.
    • Optionally run under a dedicated service account.

  4. Start the service with nssm start Gitea or via the Services MMC snap-in.

6. Configure HTTP/HTTPS access​

  • Use Windows Defender Firewall rules or your load balancer to expose ports 3000 and 22 (or the SSH port you configure).
  • To serve HTTPS directly, install a TLS certificate and configure reverse proxy settings in app.ini, or place Gitea behind IIS/NGINX/Traefik.

7. Post-install configuration​

  • Review the upstream Configuration Cheat Sheet to fine-tune app.ini (authentication providers, email, storage backends, etc.).
  • Edit C:\gitea-data\custom\conf\app.ini, then run nssm restart Gitea (or restart the Windows service) to apply the new settings.

8. Upgrades and maintenance​

  • Stop the Gitea service, download the newer Enterprise executable, replace C:\gitea\gitea.exe, then start the service.
  • Keep the Enterprise version current by following the Gitea Enterprise release notes.
  • Back up C:\gitea-data frequently and test upgrades in a staging environment when possible.
  • Follow License Activation once the service is running to apply or renew the Enterprise license.
  • To scale out across multiple Windows hosts, replicate the shared storage, database, and load-balancer patterns you use on Linux so each node stays stateless.

Gitea Enterprise relies on consistent configuration files and directories across upgrades, so any existing automation or scripts continue to work after you replace the binary.