gitaly.md

Gitaly and Praefect

GitLab uses Gitaly to abstract all Git calls. To work on local changes to gitaly, please refer to the Beginner's guide to Gitaly contributions.

For more information on Praefect, refer to Gitaly Cluster.

In GDK, you can change Gitaly and Praefect configuration in the following ways:

• Modify Gitaly and Praefect options.
• Add Gitaly nodes to the default virtual storage.
• Add virtual storages served by additional Gitaly nodes.

See also Automate different Praefect configurations for information about automating more of these processes.

Feature flags

You can set Gitaly feature flags in two ways:

• Set the feature flags in GitLab Rails. These are passed to Gitaly as they would be in production. This way is recommended and you can read more in the GitLab documentation. As documented, prepend the feature flag name with gitaly_.
• Enable all feature flags.

Enable all feature flags

To enable all Gitaly feature flags:

1. Set the following in gdk.yml:

   gitaly:
     enable_all_feature_flags: true

2. Run gdk reconfigure.

Gitaly and Praefect options

By default, GDK is set up use Praefect as a proxy to Gitaly. To disable Praefect, set the following in gdk.yml:

praefect:
  enabled: false

For other GDK Gitaly and Praefect options, refer to the gitaly: and praefect: sections of the gdk.example.yml.

Add Gitaly nodes

By default, GDK generates Praefect configuration containing only one Gitaly node (node_count: 1). To add additional backend Gitaly nodes to use on the default virtual storage:

1. Increase the number of nodes by increasing the node_count in gdk.yml. For example:

   praefect:
     node_count: 2

2. Run gdk reconfigure.

3. Run gdk restart.

Two Gitaly nodes now start when GDK starts. GDK handles the required Praefect configuration for you.

Add virtual storages

If you need to work with multiple repository storages in GitLab, you can create new virtual storages in Praefect. You need at least one more Gitaly node or storage to create another virtual storage.

1. Assuming one extra Gitaly node has been created, add a virtual_storage definition to gitaly/praefect.config.toml. For example if one extra Gitaly node was added, your configuration might look like:

   [[virtual_storage]]
   name = 'default'
   
   [[virtual_storage.node]]
   storage = "praefect-internal-0"
   address = "unix:/Users/paulokstad/gitlab-development-kit/gitaly-praefect-0.socket"
   
   [[virtual_storage]]
   name = 'default2'
   
   [[virtual_storage.node]]
   storage = "praefect-internal-1"
   address = "unix:/Users/paulokstad/gitlab-development-kit/gitaly-praefect-1.socket"

   This creates two virtual storages, each served by their own Gitaly node.

2. Edit gitlab/config/gitlab.yml to add the new virtual storage to GitLab. For example:

   • Before:

     repositories:
       storages: # You must have at least a `default` storage path.
         default:
           path: /
           gitaly_address: unix:/Users/paulokstad/gitlab-development-kit/praefect.socket

   • After:

     repositories:
       storages: # You must have at least a `default` storage path.
         default:
           path: /
           gitaly_address: unix:/Users/paulokstad/gitlab-development-kit/praefect.socket
         default2:
           path: /
           gitaly_address: unix:/Users/paulokstad/gitlab-development-kit/praefect.socket

3. Run gdk restart.

Praefect on a Geo secondary

Praefect needs a read-write capable database to track its state. On a Geo secondary the main database is read-only. So when GDK is configured to be a Geo secondary, Praefect uses the Geo tracking database instead.

If you have modified this setting, you need to recreate the Praefect database using:

gdk reconfigure

Transactions

To run Gitaly with transactions, configure the following:

gitaly:
  transactions:
    enabled: true
praefect:
  enabled: false

For more information on the implementation, see Gitaly merge request 6496.