Gitlab

The GitLab web application offers git repository management, code reviews, issue tracking, activity feeds and wikis.

This article is an extension of the NixOS manual.

Installation

A minimal local installation of Gitlab might look like this

services.gitlab = {
  enable = true;
  databasePasswordFile = pkgs.writeText "dbPassword" "zgvcyfwsxzcwr85l";
  initialRootPasswordFile = pkgs.writeText "rootPassword" "dakqdvp4ovhksxer";
  secrets = {
    secretFile = pkgs.writeText "secret" "Aig5zaic";
    otpFile = pkgs.writeText "otpsecret" "Riew9mue";
    dbFile = pkgs.writeText "dbsecret" "we2quaeZ";
    jwsFile = pkgs.runCommand "oidcKeyBase" {} "${pkgs.openssl}/bin/openssl genrsa 2048 > $out";
  };
};

services.nginx = {
  enable = true;
  recommendedProxySettings = true;
  virtualHosts = {
    localhost = {
      locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
    };
  };
};

services.openssh.enable = true;

systemd.services.gitlab-backup.environment.BACKUP = "dump";

After applying the configuration head to http://localhost and login with username root and the password specified in initialRootPasswordFile.

Even though it is easy to provide the secrets in the configuration.nix with pkgs.writeText, keep in mind that it might not be the best method, because they get written to the word readable nix-store this way. A safer solution is to put them somewhere in the file system with the right chmod and owner set and include them using ./<filename> or to use a secret managment tool

Note: Since the version 15.7 GitLab blocks weak passwords on self-managed instances by default and providing one in initialRootPasswordFile results in a silent failure to create root user.

Maintenance

Query info about your Gitlab instance

gitlab-rake gitlab:env:info

Check for configuration errors

gitlab-rake gitlab:check

Migrating an existing Gitlab to a Nixos installation

Make a backup on the on the old installation following the Gitlab backup guide. It is important to be on the same version and edition that you want to install on your new server.

Then install a Gitlab on the NixOS. Make sure you set the same secrets like on the old installation.

After a successful deploy, stop the Gitlab service using systemctl stop. Then copy the backup *_gitlab_backup.tar on the new server and run sudo -u gitlab gitlab-rake gitlab:backup:restore BACKUP=<name before the _gitlab_backup.tar>. You will be interactively asked what should be done.

After that, start the Gitlab Service again using systemctl start.

Troubleshooting

Error 422 The change you requested was rejected on login

There might be different reasons for this error to show up after a failing login. One possible issue could be that your Gitlab instance is configured to be served with SSL encryption but running unencrypted behind a reverse proxy

services.gitlab = {
  enable = true;
  port = 443;
  https = true;
[...]

To solve this, add following http headers to your upstream reverse proxy. In this example for the web server Caddy but it can be set for others too

caddy = {
  enable = true;
  virtualHosts = {
    "git.example.org".extraConfig = ''
      reverse_proxy http://10.100.0.3 {
        header_up X-Forwarded-Proto https
        header_up X-Forwarded-Ssl on
      }
    '';
  };
};