Skip to main content

​
Overview

Gitea is configured through the app.ini file located in custom/conf/app.ini. You can also use environment variables to override configuration values.

​
Configuration File Location

The configuration file path is determined by the following hierarchy:
  1. --config flag passed to the binary
  2. Built-in value set at build time
  3. Default: {CustomPath}/conf/app.ini
To find your configuration location, run: 
gitea help

​
General Settings

​
Application Settings

​
APP_NAME
string
default:"Gitea: Git with a cup of tea"
Application name shown in page titles
​
RUN_USER
string
default:"git"
Operating system user that runs Gitea. Automatically detected if not set.
​
RUN_MODE
string
default:"prod"
Application run mode: dev or prod. Dev mode provides easier debugging.
​
WORK_PATH
string
Working directory for Gitea. Defaults to the directory containing the binary.

​
Server Configuration

All server settings are configured in the [server] section.

​
Protocol and Domain

​
PROTOCOL
string
default:"http"
Protocol the server listens on: http, https, http+unix, fcgi, or fcgi+unix
​
DOMAIN
string
default:"localhost"
Domain name of the server
​
ROOT_URL
string
Public URL of the Gitea instance. Defaults to {PROTOCOL}://{DOMAIN}:{HTTP_PORT}/
​
HTTP_ADDR
string
default:"0.0.0.0"
HTTP listen address. Can be an IPv4/IPv6 address or Unix socket path.
​
HTTP_PORT
string
default:"3000"
HTTP listen port

​
SSH Configuration

​
DISABLE_SSH
boolean
default:"false"
Disable SSH feature when not available
​
START_SSH_SERVER
boolean
default:"false"
Use built-in SSH server instead of system SSH
​
SSH_DOMAIN
string
Domain name exposed in clone URLs. Defaults to DOMAIN or ROOT_URL domain.
​
SSH_PORT
number
default:"22"
SSH port exposed in clone URLs
​
SSH_LISTEN_PORT
number
Port the built-in SSH server listens on. Defaults to SSH_PORT.

​
TLS Configuration

​
ENABLE_ACME
boolean
default:"false"
Enable automatic TLS certificate generation via ACME (Let’s Encrypt)
​
CERT_FILE
string
default:"https/cert.pem"
Path to TLS certificate file (manual TLS only)
​
KEY_FILE
string
default:"https/key.pem"
Path to TLS key file (manual TLS only)

​
Storage Configuration

​
APP_DATA_PATH
string
default:"data"
Default path for storing application data
​
STATIC_ROOT_PATH
string
Root directory containing templates and static files

​
LFS Configuration

​
LFS_START_SERVER
boolean
default:"false"
Enable Git LFS support
​
LFS_JWT_SECRET
string
LFS authentication secret. Change this to a random value.
​
LFS_HTTP_AUTH_EXPIRY
duration
default:"24h"
LFS authentication validity period
​
LFS_MAX_FILE_SIZE
number
default:"0"
Maximum allowed LFS file size in bytes (0 = no limit)

​
Security Configuration

All security settings are in the [security] section.
​
INSTALL_LOCK
boolean
default:"false"
Disable the web installer. Set to true after installation.
​
SECRET_KEY
string
Global secret key for encryption. CRITICAL: Do not lose this key.
​
INTERNAL_TOKEN
string
Secret for internal API communication between Gitea components
​
PASSWORD_HASH_ALGO
string
default:"pbkdf2"
Password hashing algorithm: pbkdf2, argon2, scrypt, bcrypt

​
Admin Settings

Configure admin-specific behavior in the [admin] section.
​
DISABLE_REGULAR_ORG_CREATION
boolean
default:"false"
Prevent non-admin users from creating organizations
​
DEFAULT_EMAIL_NOTIFICATIONS
string
default:"enabled"
Default email notification preference for new users
​
USER_DISABLED_FEATURES
string
Comma-separated list of disabled features for all users:
  • deletion - Account deletion
  • manage_ssh_keys - SSH key management
  • manage_gpg_keys - GPG key management
  • manage_mfa - Multi-factor authentication
  • manage_credentials - Access token management
  • change_username - Username changes
  • change_full_name - Full name changes
​
EXTERNAL_USER_DISABLE_FEATURES
string
Additional disabled features for external authentication users (LDAP, OAuth2, etc.)

​
Environment Variables

You can override any configuration value using environment variables with the format: 
GITEA__SECTION__KEY=value

​
Examples

# Override database type
export GITEA__database__DB_TYPE=postgres

# Override server port
export GITEA__server__HTTP_PORT=8080

# Override admin settings
export GITEA__admin__DISABLE_REGULAR_ORG_CREATION=true

​
Viewing Configuration

To view the current configuration, use: 
gitea manager show-config
This displays the effective configuration, including defaults and overrides.

​
Configuration Validation

After modifying app.ini, validate your configuration: 
gitea doctor check --run config

​
Best Practices

1

Use Version Control

Keep your app.ini in version control (excluding secrets)
2

Externalize Secrets

Use *_URI options to store secrets in external files:
SECRET_KEY_URI = file:/etc/gitea/secret_key
LFS_JWT_SECRET_URI = file:/etc/gitea/lfs_jwt_secret
3

Minimal Configuration

Only set values that differ from defaults. Smaller config files are easier to maintain.
4

Test Changes

Always test configuration changes in a non-production environment first

Build docs developers (and LLMs) love

Get started for freeTalk to us