Configuration

Configure Gitea using app.ini and environment variables

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

Related Resources

• Database Configuration
• Authentication Configuration
• Backup and Restore
• Command-Line Tools