Configuration - GitRiver Docs

All GitRiver parameters: TOML file, environment variables, CI/CD, SMTP, LDAP, S3

GitRiver is configured via a TOML file and/or environment variables with the GITRIVER_* prefix. Environment variables always take priority over values from the file.

Where the Config is Stored

In Docker, the config is stored at /var/lib/gitriver/gitriver.toml and is created automatically on first launch. Most parameters can be set via GITRIVER_* environment variables in docker-compose - this is the recommended approach.

Core Parameters

These parameters define how GitRiver listens for connections and where it stores data.

host = "0.0.0.0"
port = 3000
base_url = "https://git.example.com"
database_url = "postgres://gitriver:password@postgres/gitriver"
git_repos_path = "/var/lib/gitriver/repos"

Parameter	Env Variable	Default	Purpose
`host`	`GITRIVER_HOST`	`0.0.0.0`	Address to listen on
`port`	`GITRIVER_PORT`	`3000`	HTTP port
`base_url`	`GITRIVER_BASE_URL`	`http://{host}:{port}`	External URL - used in email links, CI variables, webhooks. In production, be sure to specify with https://
`database_url`	`GITRIVER_DATABASE_URL`	-	PostgreSQL URL. If not set - the setup wizard launches
`git_repos_path`	`GITRIVER_GIT_REPOS_PATH`	`/var/lib/gitriver/repos`	Directory for bare git repositories
`web_dist_path`	`GITRIVER_WEB_DIST_PATH`	-	Directory with a different build of the web interface. If unset, the interface embedded in the binary is served

Database Connection via Separate Parameters

Instead of database_url, you can set the connection components individually. This is convenient in Docker Compose:

GITRIVER_DB_HOST=postgres
GITRIVER_DB_PORT=5432
GITRIVER_DB_USER=gitriver
GITRIVER_DB_PASS=strong_password
GITRIVER_DB_NAME=gitriver

If GITRIVER_DATABASE_URL is set - the individual parameters are ignored.

JWT Secret

jwt_secret = "your-secret-at-least-32-characters"

Env Variable	Default
`GITRIVER_JWT_SECRET`	Automatically generated and saved to the `.jwt_secret` file

Used for signing session tokens. If the .jwt_secret file is deleted - all active sessions become invalid.

Forbidden values: secret, changeme, change-me-in-production, jwt_secret. GitRiver will refuse to start with these values.

SSH Access

authorized_keys_path = "/home/gitriver/.ssh/authorized_keys"

Path to the authorized_keys file for SSH access via OpenSSH. User SSH keys are stored in the database; GitRiver automatically writes them to this file. If not set - automatic key writing does not happen and SSH access must be configured manually.

CI/CD

Parameters controlling the built-in continuous integration system.

ci_data_path = "/var/lib/gitriver/ci-data"
ci_max_concurrent_jobs = 4
ci_job_timeout_secs = 3600
ci_docker_runtime = "default"

Parameter	Env Variable	Default	Purpose
`ci_data_path`	`GITRIVER_CI_DATA_PATH`	`{repos}/../ci-data`	Directory for CI logs and workspaces
`ci_local_executor_enabled`	`GITRIVER_CI_LOCAL_EXECUTOR`	`true`	Built-in executor: the server runs jobs itself, in Docker containers. `false` - jobs go to external runners and the server needs no Docker
`ci_max_concurrent_jobs`	`GITRIVER_CI_MAX_CONCURRENT_JOBS`	`4`	How many CI tasks run concurrently on the built-in runner
`ci_job_timeout_secs`	`GITRIVER_CI_JOB_TIMEOUT_SECS`	`3600` (1 hour)	Timeout for a single task. Maximum - 21600 (6 hours)
`ci_pipeline_retention_days`	`GITRIVER_CI_PIPELINE_RETENTION_DAYS`	`90`	How many days to keep pipeline data. 0 = forever
`ci_docker_memory`	`GITRIVER_CI_DOCKER_MEMORY`	`2g`	RAM limit for each CI task’s Docker container
`ci_docker_cpus`	`GITRIVER_CI_DOCKER_CPUS`	`2`	CPU limit for Docker containers
`ci_docker_runtime`	`GITRIVER_CI_DOCKER_RUNTIME`	`default`	Docker runtime for CI containers
`ci_git_clone_timeout_secs`	`GITRIVER_CI_GIT_CLONE_TIMEOUT_SECS`	`120`	Timeout for git clone when preparing the workspace
`ci_job_token_ttl_secs`	`GITRIVER_CI_JOB_TOKEN_TTL_SECS`	`28800` (8 h)	Lifetime of `CI_JOB_TOKEN`

A server without Docker

ci_local_executor_enabled = false (GITRIVER_CI_LOCAL_EXECUTOR=false) turns off the built-in executor. The server no longer needs Docker or access to its socket: it only serves git, the database and HTTP, while builds move to the external runner machines. This is how GitRiver fits on a light machine, or into an environment where Docker is forbidden by policy.

In this mode the server does not touch Docker at all: orphaned BuildKit containers are not cleaned up, the build cache is not maintained, the ci_docker_memory, ci_docker_cpus and ci_job_pids_limit limits do not apply, and ci_max_concurrent_jobs stays unused - it belongs to the built-in executor.

A runner first, the switch second. The whole queue goes out, including jobs with runs_on: default and jobs with no runs_on at all. There is no fallback to “run it on the server”: with no runner connected, a job fails right away. How to connect runners is in CI/CD Advanced.

Docker Runtime

The ci_docker_runtime parameter determines how GitRiver runs CI containers:

default - standard Docker. Suitable for most tasks.
sysbox - rootless Docker-in-Docker via sysbox-runc. Secure, but requires sysbox to be installed.
rootless - rootless Docker. Secure, but limited in compatibility.
privileged - full Docker-in-Docker. Allows building images inside CI, but unsafe for production - the container gains access to the host.

If your CI tasks build Docker images (docker build), use sysbox or privileged. For regular tests, default is sufficient.

SMTP (Email Notifications)

To send email notifications (invitations, password reset, repository events), configure an SMTP server.

[smtp]
host = "smtp.example.com"
port = 587
username = "gitriver@example.com"
password = "email_password"
from = "GitRiver <gitriver@example.com>"
starttls = true

Field	Purpose
`host`	SMTP server address
`port`	Port: 587 (STARTTLS) or 465 (implicit TLS)
`username`	Authentication login (optional)
`password`	Password (optional)
`from`	Sender address - what the recipient will see
`starttls`	Use STARTTLS (default `true`)

Also configurable via UI: Administration -> SMTP -> test sending.

LDAP (Corporate Authentication)

Connect a corporate directory (Active Directory, OpenLDAP) for single sign-on.

[ldap]
url = "ldaps://ldap.example.com:636"
bind_dn = "cn=service,dc=example,dc=com"
bind_password = "service_account_password"
search_base = "ou=users,dc=example,dc=com"
user_filter = "(&(objectClass=person)(uid={login}))"
email_attr = "mail"
display_name_attr = "displayName"
admin_group_dn = "cn=admins,ou=groups,dc=example,dc=com"

Field	Purpose
`url`	LDAP server URL. `ldap://` for plain, `ldaps://` for TLS
`bind_dn`	DN of the service account for user lookups
`bind_password`	Service account password
`search_base`	Where to search for users in the LDAP tree
`user_filter`	Search filter. `{login}` is replaced with the entered login
`email_attr`	Attribute containing the email address (usually `mail`)
`display_name_attr`	Attribute containing the display name (usually `displayName`)
`admin_group_dn`	DN of the group - members receive GitRiver administrator rights

Also configurable via UI: Administration -> LDAP -> “Test Connection” button.

LDAP sign-in is a Max edition capability; Community does not have it. An account that signs in only through the directory needs a Max seat, and once the licence’s grace period ends, directory sign-in closes - see Corporate sign-in and Max seats.

S3 (Storage for Container Registry)

By default, Container Registry images and LFS files are stored on the filesystem. For production, an S3-compatible storage is recommended (MinIO, AWS S3, Yandex Object Storage).

[s3]
endpoint = "http://minio:9000"
bucket = "gitriver-registry"
access_key = "minioadmin"
secret_key = "minioadmin"
region = "us-east-1"
temp_dir = "/tmp/gitriver-uploads"
part_size_mb = 5

Field	Purpose
`endpoint`	S3 endpoint URL
`bucket`	Bucket name (must exist)
`access_key`, `secret_key`	Access keys
`region`	Region (for MinIO - any value)
`temp_dir`	Directory for temporary files during upload
`part_size_mb`	Part size for multipart upload (5-100 MB)

Also configurable via UI: Administration -> Storage -> test connection.

Without the [s3] section, everything is stored on the filesystem ({git_repos_path}).

Backups

GITRIVER_BACKUP_ENCRYPTION_KEY=your_key_base64

AES-256 key for encrypting backups. Generate with: openssl rand -base64 32. If not set - backups are saved without encryption.

Licensing

GITRIVER_LICENSE_SERVER_URL=https://gitriver.ru

URL of the license check-in server (once every 24 hours). Default - https://gitriver.ru.

Connectivity is not what makes it run: after activation the installation works without it for the length of the confirmation period, which is extended by the next check-in or by an activation file pasted by hand. Air-gapped installations are given a longer confirmation period - see Licensing.

Other Parameters

Parameter	Env Variable	Default	Purpose
`webhook_timeout_secs`	`GITRIVER_WEBHOOK_TIMEOUT_SECS`	`10`	HTTP request timeout for webhook delivery
`lfs_token_ttl_secs`	`GITRIVER_LFS_TOKEN_TTL_SECS`	`900` (15 min)	JWT lifetime for LFS operations
`registry_token_expiry_secs`	`GITRIVER_REGISTRY_TOKEN_EXPIRY_SECS`	`7200` (2 h)	Docker Registry token lifetime
`sse_keepalive_secs`	`GITRIVER_SSE_KEEPALIVE_SECS`	`15`	Keepalive interval for SSE (CI log streaming)
`pages_data_path`	`GITRIVER_PAGES_DATA_PATH`	`{repos}/../pages-data`	Directory for Pages deployments