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`	-	Path to the built frontend (set automatically in Docker)

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 the built-in SSH server. If not set - SSH works through the built-in daemon without a file (keys are stored in the database).

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_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`

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 is a Pro feature. In the Community edition, authentication is via login/password and OAuth2.

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.com

URL of the server for license heartbeat checks (once every 24 hours). Default - https://gitriver.com. The license works fully offline after activation.

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