Skip to main content

Documentation Index

Fetch the complete documentation index at: https://gogs.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. Embedded defaults: The conf/app.ini file is compiled into the binary. You should never edit this file directly.
  2. 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
Values support INI variable interpolation with the %(KEY)s syntax. The embedded defaults use this extensively, for example: 
EXTERNAL_URL = %(PROTOCOL)s://%(DOMAIN)s:%(HTTP_PORT)s/
Values also support environment variable expansion, so you can reference system environment variables directly in your configuration: 
[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:
MethodExample
DefaultThe custom/ subdirectory next to the binary
Environment variableGOGS_CUSTOM=/etc/gogs
The work directory (parent of 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
All of these are optional. Gogs falls back to embedded defaults when a custom file does not exist.

​
Repository templates

Gogs ships with embedded templates used when creating new repositories:
Template typeEmbedded location
.gitignoreconf/gitignore/
Licenseconf/license/
READMEconf/readme/
Issue labelsconf/label/
You can add your own by placing files in the corresponding 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
The [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.