Gogs uses a layered configuration system. A default configuration is embedded in the binary, and you provide overrides in a custom file. Beyond app.ini, the custom/ directory lets you override templates, static assets, locale files, and more.
Two-layer configuration
Gogs reads configuration from two sources, in order:
- Embedded defaults: The
conf/app.ini file is compiled into the binary. You should never edit this file directly.
- Custom overrides: Your
custom/conf/app.ini file. Any value you set here takes precedence over the embedded default.
This separation means binary users can upgrade without losing their settings, and source installers benefit from custom/ being in .gitignore.
The embedded conf/app.ini contains every available option with detailed inline comments. Use it as your canonical reference. Overriding a value
You only need to include the values you want to change. For example, to set a custom repository storage path and switch to production mode:
RUN_MODE = prod
[repository]
ROOT = /home/git/gogs-repositories
%(KEY)s syntax. The embedded defaults use this extensively, for example:
EXTERNAL_URL = %(PROTOCOL)s://%(DOMAIN)s:%(HTTP_PORT)s/
[database]
PASSWORD = ${DATABASE_PASSWORD}
If a password or value contains special characters (like backticks or #), wrap it in backticks, e.g., PASSWORD = `p@ss#word!`.
Gogs uses go-ini/ini as the configuration library, please refer to its documentation for the full syntax specification including multi-line values, key/value separators, and section handling. The custom/ directory
The custom/ directory is Gogs’ extension point. It sits alongside the binary by default, and contains much more than just app.ini.
Finding the path
Run gogs web --help to see the custom directory path in the output. You can also override it:
| Method | Example |
|---|
| Default | The custom/ subdirectory next to the binary |
| Environment variable | GOGS_CUSTOM=/etc/gogs |
custom/) can also be overridden with GOGS_WORK_DIR.
Specifying a custom config path
Every Gogs subcommand accepts -c, --config to point to a configuration file at a non-default location:
./gogs web --config /etc/gogs/app.ini
What lives in custom/
custom/
├── conf/
│ ├── app.ini # Your configuration overrides
│ ├── auth.d/ # Authentication source files
│ │ └── *.conf
│ ├── gitignore/ # Custom .gitignore templates
│ ├── license/ # Custom license templates
│ ├── readme/ # Custom README templates
│ ├── label/ # Custom issue label sets
│ └── locale/ # Translation overrides
│ └── locale_*.ini
├── templates/ # HTML template overrides
├── public/ # Static asset overrides (CSS, JS, images)
└── robots.txt # Search engine crawling rules
Repository templates
Gogs ships with embedded templates used when creating new repositories:
| Template type | Embedded location |
|---|
.gitignore | conf/gitignore/ |
| License | conf/license/ |
| README | conf/readme/ |
| Issue labels | conf/label/ |
custom/conf/ subdirectory. Custom files take priority over embedded ones with the same name, so you can also override built-in templates.
For example, to add a custom .gitignore template that appears in the repository creation form:
custom/conf/gitignore/MyFramework
[repository] PREFERRED_LICENSES option controls which licenses appear at the top of the selection list. The names must match filenames in conf/license/ or custom/conf/license/.
Custom templates and static assets
You can override any of Gogs’ HTML templates or static assets by mirroring the file structure under custom/.
Templates — Place files in custom/templates/ matching the path of the embedded template you want to override. See Custom templates for details.
Static assets — Place files in custom/public/ to override CSS, JavaScript, or images. Custom public files are served with higher priority than embedded ones.
Locale overrides — Place locale_*.ini files in custom/conf/locale/ to override translation strings for any supported language.
Loading assets from disk
By default, Gogs serves templates, locale files, and public assets from the binary’s embedded data. If you set LOAD_ASSETS_FROM_DISK = true in [server], Gogs will load them from the work directory instead. This is mainly useful during development. 
