GitRiver GitRiver
RU
Navigation

Troubleshooting

Common errors when working with GitRiver and how to resolve them

Setup wizard does not appear

Cause: the wizard only launches if database_url is not specified in the config and is not set via environment variables.

Solution: if you set GITRIVER_DB_* variables in docker-compose, the wizard is not needed - the database connection is configured automatically. If you want the wizard, remove the GITRIVER_DB_* variables from docker-compose and restart.

Server does not start: database connection error

Symptoms: logs show connection refused or authentication failed.

Check:

  1. PostgreSQL is running and accessible: pg_isready -h localhost -U gitriver
  2. Connection details in the config or environment variables match the PostgreSQL settings
  3. In Docker Compose: depends_on with condition: service_healthy - GitRiver waits until the database is ready
  4. The port is not occupied by another process

JWT errors after restart

Symptoms: all users are logged out, invalid token errors.

Cause: the JWT secret is stored in the .jwt_secret file next to the config (/var/lib/gitriver/.jwt_secret in Docker). If the file is deleted, all previously issued tokens become invalid.

Solution: users need to log in again. To prevent this, do not delete the /var/lib/gitriver volume when upgrading.

CI jobs do not start

Check:

  1. Docker socket is accessible: docker-compose must have the volume -v /var/run/docker.sock:/var/run/docker.sock
  2. The gitriver user is in the docker group: in the Docker image, this is done automatically via docker-entrypoint.sh
  3. Concurrent job limit: check ci_max_concurrent_jobs (default is 4). If all slots are occupied, new jobs wait in the queue.
  4. Timeout: if a job hangs, check ci_job_timeout_secs
  5. Docker image: make sure the image is specified in the job (image: node:22)

CI jobs hang on git clone

Cause: large repository or slow network.

Solution: increase the clone timeout:

GITRIVER_CI_GIT_CLONE_TIMEOUT_SECS=300

The default is 120 seconds.

Git push is rejected

Possible causes:

  1. Branch protection: direct push is forbidden, a pull request is required. Check: Settings -> Branch Protection
  2. File size: use Git LFS for large files. In nginx, check client_max_body_size (512m recommended)
  3. Insufficient permissions: a user with the Reporter role cannot push. Check the role in the group or repository collaborators
  4. Signed commits: if the protection rule has “Require signed commits” enabled, all commits must be GPG-signed

Docker push/pull not working (Container Registry)

Check:

  1. Authentication: docker login git.example.com -u username -p token - use a token, not a password
  2. Tag format: git.example.com/owner/repo:tag (not docker.io/...)
  3. Port: if nginx listens on a non-standard port, include it in the tag
  4. SSL: Docker requires HTTPS by default. For HTTP, add the host to insecure-registries in daemon.json

Email notifications are not being sent

Check:

  1. SMTP is configured: Administration -> SMTP -> “Test” button (sends a test email)
  2. from in the config is a valid email address
  3. The port is correct: 587 (STARTTLS) or 465 (implicit TLS)
  4. The provider is not blocking outgoing mail (check SMTP logs)

LDAP: user cannot log in

Check:

  1. Test connection: Administration -> LDAP -> “Test connection” - shows the number of found users
  2. Filter: {login} in the filter is replaced with the entered username. Verify that the filter finds the user: ldapsearch -x -H ldap://host -b "ou=users,dc=example,dc=com" "(uid=username)"
  3. Bind DN: if required, the DN and password of the service account must be specified
  4. TLS: for ldaps://, the CA certificate must be trusted

High disk space usage

Causes and solutions:

  1. Container Registry: run garbage collection - Administration -> Storage -> “Cleanup”. Set up retention policies - automatic deletion of old tags
  2. CI artifacts: check ci_pipeline_retention_days (default is 90 days). Reduce if needed
  3. Git LFS: large files are stored in git_repos_path. For production, use S3 storage
  4. Backups: check rotation - Administration -> Backups -> Schedule -> maximum number of copies

Logs

Docker

docker compose logs gitriver
docker compose logs gitriver --tail 100 -f

Local Installation

Logs are output to stdout. The log level is set via the RUST_LOG variable:

RUST_LOG=info gitriver run --config gitriver.toml
RUST_LOG=debug gitriver run --config gitriver.toml

Health Check

curl http://localhost:3000/health

A response of {"status":"ok","database":"connected"} means the server is running normally.