Move Certain Configurations from app.ini to Database #35635
Description
Feature Description
Background
As Gitea continues to evolve, more and more configuration options have been added to the app.ini file. While this approach is simple and effective for static configurations, it has introduced several drawbacks:
- It is increasingly difficult to locate and manage specific configuration options as the number of settings grows.
- Any modification to configuration values requires restarting the Gitea instance for changes to take effect.
- Although Gitea restarts quickly, unnecessary restarts can disrupt user experience and impact uptime for production environments.
To address these issues, we propose moving certain dynamic configuration options from the INI file to the database. This will allow live configuration updates without requiring restarts, simplify management, and better support distributed and containerized deployments.
Which Configurations Should Be Moved
Only configuration options that do not affect Gitea’s startup process should be migrated to the database. These include settings that control runtime behavior or user-visible features rather than system initialization.
Examples:
- UI and branding options
- Feature toggles
- Repository-related settings (e.g., default branch, PR settings, etc.)
- Email, notification, and service integrations
- API rate limits and other tunable runtime parameters
These configurations are safe to load dynamically at runtime and can be refreshed from the database without restarting Gitea.
Which Configurations Should Remain in app.ini
The following configurations should continue to reside in the INI file because they are tightly coupled with system startup, runtime environment, or service dependencies:
- Directory configurations
- Database configurations
- HTTP server configurations
- SSH server configurations
- LFS server configurations
- Internal token configurations
- Reverse proxy configurations
- Logging configurations
- Storage configurations
- Indexer configurations
These settings directly affect how Gitea starts or how its subsystems are initialized. They are typically stable and infrequently modified, so keeping them in the INI file ensures reliable startup behavior and compatibility with existing Docker and Helm configurations.
Migration Strategy
Retain Existing User Values
A migration mechanism should be introduced to automatically move configuration values from the INI file to the database when a corresponding entry exists.
This ensures no user-configured values are lost during the transition.
Deprecation of INI Items
Once a configuration option is successfully migrated to the database:
- The original INI entry will be considered deprecated.
- A warning log should be emitted if the deprecated option is still defined in the INI file.
- After two stable release cycles, the deprecated option can be fully removed from INI parsing logic.
Runtime Update Mechanism
Gitea should reload the relevant configuration values from the database automatically when they are modified through the admin interface or API.
Backward Compatibility
Migrating configuration options from the INI file to the database may introduce backward compatibility concerns, especially for environments that rely on Dockerfile or Helm-based deployments.
In particular, some users utilize the env-to-ini mechanism, where environment variables are converted into INI values during container startup. Once these configurations are moved to the database, this mechanism will no longer apply to the migrated options.
However, since all configurations being moved are non-startup-critical, this change will not prevent Gitea from starting when users upgrade to newer Docker images.
In such cases, the affected configurations will simply fall back to their database defaults or previously stored values. Administrators can then modify these settings directly through the web interface or API.
One notable case that requires special attention is the UI theme configuration, which is currently referenced by the Helm chart.
Because this configuration interacts with deployment templates, moving it to the database would cause a breaking change for existing Helm users. Therefore, the Helm chart should be updated and released with a corresponding breaking change before the UI theme configuration is migrated.
Benefits
- Zero-downtime configuration changes — administrators can modify settings via the UI or API without restarting the instance.
- Simplified configuration management — reduces confusion and duplication between runtime settings and static configurations.
- Improved scalability — database-backed configurations are better suited for clustered and containerized deployments where multiple Gitea instances share a single configuration source.
- Future flexibility — lays the groundwork for per-instance or per-organization dynamic settings in multi-tenant environments.
Screenshots
No response